How to define a JSON array with concrete item definition for every index (i.e. a tuple) in OpenAPI?

by

You need OpenAPI 3.1 to define tuples precisely. In earlier versions, you can only define generic arrays without a specific item order.

OpenAPI 3.1

Your example can be defined as:

# openapi: 3.1.0

type: array
prefixItems:
  # The 1st item
  - type: integer
    description: Description of the 1st item
  # The 2nd item
  - type: string
    description: Description of the 2nd item
  # Define the 3rd etc. items if needed
  # ...

# The total number of items in this tuple
minItems: 2
maxItems: 2
additionalItems: false   # can be omitted if `maxItems` is specified

OpenAPI 3.1 is fully compatible with JSON Schema 2020-12, including the prefixItems keyword (the new name for the tuple form of items from earlier JSON Schema drafts).

OpenAPI 3.0.x and earlier

Earlier OpenAPI versions do not have a way to describe tuples. The most you can do is define “an array of 2 items that can be either number or string”, but you cannot specifically define the type of the 1st and 2nd items. You can, however, mention additional constraints in the schema description.

# openapi: 3.0.0

type: array
items:
  oneOf:
    - type: integer
    - type: string
minItems: 2
maxItems: 2
description: >-
  The first item in the array MUST be an integer,
  and the second item MUST be a string.

If you are designing a new API rather than describing an existing one, a possible workaround is to use an object instead of an array to represent this data structure.

More Related Contents:

  1. Extended tuple unpacking in Python 2
  2. In C# 7 is it possible to deconstruct tuples as method arguments
  3. Combine elements of a list [closed]
  4. C# using Tuple with Sum [closed]
  5. What’s the difference between lists and tuples?
  6. How does tuple comparison work in Python?
  7. How does swapping of members in tuples (a,b)=(b,a) work internally?
  8. Why is there no tuple comprehension in Python?
  9. Ignore python multiple return value
  10. What’s the difference between System.ValueTuple and System.Tuple?
  11. When are parentheses required around a tuple?
  12. Swagger: How to have a property reference a model in OpenAPI 2.0 (i.e. nest the models)?
  13. Sort tuples based on second parameter
  14. Add Variables to Tuple
  15. Getting one value from a tuple
  16. How to document dynamic query parameter names in OpenAPI (Swagger)?
  17. Template tuple – calling a function on each element
  18. Swagger HashMap property type
  19. Why is tuple faster than list in Python?
  20. What’s the difference between lists enclosed by square brackets and parentheses in Python?
  21. C++11 way to index tuple at runtime without using switch
  22. lambda arguments unpack error
  23. Swagger: “equivalent path already exists” despite different parameters
  24. Python lambda does not accept tuple argument [duplicate]
  25. How to add multiple example values for an array in OpenAPI/Swagger?
  26. Why is there no piecewise tuple construction?
  27. how to avoid undefined execution order for the constructors when using std::make_tuple
  28. python – get list of tuples first index?
  29. Generate all subsets of size k (containing k elements) in Python
  30. In what case would I use a tuple as a dictionary key? [closed]

Leave a Comment