How to define a mixed-type array (with different element types) in OpenAPI 2.0?

by

The answer depends on which version of the OpenAPI Specification you use.

OpenAPI 3.1

type can be a list of types, so you can write your schema as:

# openapi: 3.1.0

obj1:
  type: array
  items:
    type: [string, integer]
    # or if nulls are allowed:
    # type: [string, integer, 'null']

OpenAPI 3.0.x

Mixed types are supported in OpenAPI 3.0 using oneOf / anyOf and optionally nullable: true to also allow nulls.

# openapi: 3.0.1

obj1:
  type: array
  items:
    oneOf:
      - type: string
        nullable: true  # If nulls are allowed
      - type: integer

OpenAPI 2.0

OpenAPI 2.0 (Swagger 2.0) does not really support mixed-type array and parameters. The most you can do is to use a typeless schema {} for items, which means the items can be anything (except null) – numbers, objects, strings, etc. You cannot specify the exact types for items, but you can add an example of an array with different item types.

# swagger: '2.0'

obj1:
  type: array
  items: {}  # <--- means "any type" (except null)
  example:
    - string data
    - 1

Note: Typeless schema {} can only be used in body parameters and response schemas. Path, header and form parameters require a primitive type for array items.

More Related Contents:

  1. How to return an array of objects in SwaggerHub?
  2. Swagger schema properties ignored when using $ref – why?
  3. Swagger 2.0: Multiple Path objects with different paths but same request and response
  4. Swagger/OpenAPI – use $ref to pass a reusable defined parameter
  5. Swagger: wildcard path parameters
  6. Schema object without a type attribute in Swagger 2.0
  7. Swagger: take one or more values from enum
  8. Swagger: How to have a property reference a model in OpenAPI 2.0 (i.e. nest the models)?
  9. How to specify if a field is optional or required in OpenAPI/Swagger?
  10. Swagger/OpenAPI mock server
  11. How to document dynamic query parameter names in OpenAPI (Swagger)?
  12. How can I represent ‘Authorization: Bearer ‘ in a Swagger Spec (swagger.json)
  13. How to define a property that can be string or null in OpenAPI (Swagger)?
  14. How to define mutually exclusive query parameters in Swagger (OpenAPI)?
  15. How to convert OpenAPI 2.0 to OpenAPI 3.0? [closed]
  16. Swagger complex response model with dynamic key value hash maps
  17. How to define an optional parameter in path using swagger
  18. Swagger: “equivalent path already exists” despite different parameters
  19. Re-using model with different required properties
  20. How to write OpenAPI 3 (Swagger) specification for property name in `map` object?
  21. How not to copy-paste 3 generic error responses in almost all paths?
  22. How to define global parameters in OpenAPI?
  23. Use object type query param in swagger documentation
  24. How do I include subclasses in Swagger API documentation/ OpenAPI specification using Swashbuckle?
  25. Freeform subobject in json-schema
  26. OpenAPI query string parameter with list of objects
  27. OpenAPI path/query parameters nested structure serialization
  28. How to change Swagger-ui URL prefix?
  29. How to document default None/null in OpenAPI/Swagger using FastAPI?
  30. Why `additionalProperties` is the way to represent Dictionary/Map in Swagger/OpenAPI 2.0

Leave a Comment