在 openAPI 3.1 中定义精确的自定义属性

Question

I have a JSON schema I am trying to describe, a JSON object which has a additionalProperties node which contains an array of key value pairs.

{
  "additionalProperties": [
    {
        "key": "optionA",
        "value": "1"
    },
    {
        "key": "optionB",
        "value": "0"
    },
    {
        "key": "optionC",
        "value": "1"
    }
  ],
}

Whilst I can use quite a generic schema for this like this

    additionalProperties:
      properties:
        key:
          type: string
        value:
          type: string
      required:
        - key
        - value
      type: object

I ideally wish to explain what the various keys that can appear and what they mean. Ie optionA means this and OptionB means that. Is there a way I can describe the exact options which will appear in the array?

Answer 1

The description field is used when you want to provide additional information or context to the reader that isn't necessarily explained by schema alone.

additionalProperties:
  description: Your explanation goes here. Note that you can use markdown formatting if desired.
  properties:
    key:
      type: string
    value:
      type: string
  required:
    - key
    - value
  type: object

You can also more accurately describe your options in the schema if they are all known values using oneOf , allOf , or anyOf . ( Documentation here )

additionalProperties:
  properties:
    anyOf:
      - $ref: '#/components/schemas/optionA'
      - $ref: '#/components/schemas/optionB'
      - $ref: '#/components/schemas/optionC'