api - OpenAPI: what schema to accept any (complex) JSON value

Question

The API for which I'm writing a Swagger 2.0 specification is basically a store for any JSON value.

I want a path to read value and a path to store any JSON values (null, number, integer, string, object, array) of non-predefined depth.

Unfortunately, it seems that Swagger 2.0 is quite strict on schemas for input and output and does not allow the whole set of schemas allowed by JSON Schema. The Swagger editor doesn't allow for example mixed values (for example a property that can be either a boolean or an integer) or loosely defined arrays (the type of items must be strictly defined) and objects.

So I'm trying a workaround by defining a MixedValue schema:

---
swagger: '2.0'
info:
  version: 0.0.1
  title: Data store API
consumes:
- application/json
produces:
- application/json
paths:
  /attributes/{attrId}/value:
    parameters:
    - name: attrId
      in: path
      type: string
      required: true
    get:
      responses:
        '200':
          description: Successful.
          schema:
            $ref: '#/definitions/MixedValue'
    put:
      parameters:
      - name: value
        in: body
        required: true
        schema:
          $ref: '#/definitions/MixedValue'
      responses:
      responses:
        '201':
          description: Successful.
definitions:
  MixedValue:
    type: object
    properties:
      type:
        type: string
        enum:
        - 'null'
        - boolean
        - number
        - integer
        - string
        - object
        - array
      boolean:
        type: boolean
      number:
        type: number
      integer:
        type: integer
      string:
        type: string
      object:
        description: deep JSON object
        type: object
        additionalProperties: true
      array:
        description: deep JSON array
        type: array
    required:
    - type

But the Swagger Editor refuses the loosely defined object and array properties.

Questions: - Is there a way to workaround this issue? - Is it just a Swagger Editor bug or a strong limit of the Swagger 2.0 spec? - Is there a better way (best practice) to specify what I need? - Can I expect some limitations in code produced by swagger for some languages with my API spec?

Answer 1

An arbitrary-type schema can be defined using an empty schema {}:

# swagger: '2.0'
definitions:
  AnyValue: {}

# openapi: 3.0.0
components:
  schemas:
    AnyValue: {}

or if you want a description:

# swagger: '2.0'
definitions:
  AnyValue:
    description: 'Can be anything: string, number, array, object, etc. (except `null`)'

# openapi: 3.0.0
components:
  schemas:
    AnyValue:
      description: 'Can be anything: string, number, array, object, etc., including `null`'

Without a defined type, a schema allows any values. Note that OpenAPI 2.0 Specification does not support null values, but some tools might support nulls nevertheless.

In OpenAPI 3.0, type-less schemas allow null values unless nulls are explicitly disallowed by other constraints (such as an enum).

See this Q&A for more details on how type-less schemas work.

Here's how Swagger Editor 2.0 handles a body parameter with the AnyValue schema:

I don't know how code generators handle this though.