2

I'm updating my API spec (OAS 3.0.0), and am having trouble understanding how to properly model a "complex" default value.

In general, default values for parameters are scalar values (i.e. the field offset has a default value of 0). But in the API I'm spec'ing, the default value is actually calculated based on other provided parameters.

For example, what if we take the Pet model from the example documentation, and decide that all animals need to be tagged. If the user of the API wants to supply a tag, great. If not, it will be equal to the name.

One possibility:

Pet:
  required:
    - id
    - name
  properties:
    id:
      type: integer
      format: int64
    name:
      type: string
    tag:
      type: string
      default: '#/components/schemas/Pet/name'

This stores the path value as the default, but I'd like to have it explain that the default value will be calculated.

Bonus points if I can encode information from a parent schema.

Is the alternative to just describe the behavior in a description field?

kmbenitez
  • 33
  • 5

1 Answers1

0

OpenAPI Specification does not support dynamic/conditional defaults. You can only document the behavior verbally in the description.

That said, you can use specification extensions (x-...) to add custom information to your definitions, like so:

tag:
  type: string
  x-default: name

or

tag:
  type: string
  x-default:
    propertyName: name

# or similar

and extend the tooling to support your custom extensions.

Helen
  • 87,344
  • 17
  • 243
  • 314