Swagger schema properties ignored when using $ref – why?

by

TL;DR: $ref siblings are supported (to an extent) in OpenAPI 3.1. In previous OpenAPI versions, any keywords alongside $ref are ignored.

OpenAPI 3.1

Your definition will work as expected when migrated to OpenAPI 3.1. This new version is fully compatible with JSON Schema 2020-12, which allows $ref siblings in schemas.

openapi: 3.1.0
...

components:
  schemas:
    Time:
      type: string
      description: Time in 24 hour format "hh:mm".

    TimeInterval:
      type: object
      properties:
        lowerBound:
          # ------- This will work in OAS 3.1 ------- #
          $ref: "#/components/schemas/Time"
          description: Lower bound on the time interval.
          default: "00:00"
        upperBound:
          # ------- This will work in OAS 3.1 ------- #
          $ref: "#/components/schemas/Time"
          description: Upper bound on the time interval.
          default: "24:00"

Outside of schemas – for example, in responses or parameters – $refs only allow sibling summary and description keywords. Any other keywords alongside these $refs will be ignored.

# openapi: 3.1.0

# This is supported
parameters:
  - $ref: '#/components/parameters/id'
    description: Entity ID

# This is NOT supported
parameters:
  - $ref: '#/components/parameters/id'
    required: true

Here’re some OpenAPI feature requests about non-schema $ref siblings that you can track/upvote:

OpenAPI 2.0 and 3.0.x

In these versions, $ref works by replacing itself and all of its sibling elements with the definition it is pointing at. That is why

      lowerBound:
        $ref: "#/definitions/Time"
        description: Lower bound on the time interval.
        default: "00:00"

becomes

      lowerBound:
        type: string
        description: Time in 24 hour format "hh:mm".

A possible workaround is to wrap $ref into allOf – this can be used to “add” attributes to a $ref but not override existing attributes.

      lowerBound:
        allOf:
          - $ref: "#/definitions/Time"
        description: Lower bound on the time interval.
        default: "00:00"

Another way is to use replace the $ref with an inline definition.

definitions:
  TimeInterval:
    type: object
    properties:
      lowerBound:
        type: string  # <------
        description: Lower bound on the time interval, using 24 hour format "hh:mm".
        default: "00:00"
      upperBound:
        type: string  # <------
        description: Upper bound on the time interval, using 24 hour format "hh:mm".
        default: "24:00"

More Related Contents:

  1. How to return an array of objects in SwaggerHub?
  2. How to define a mixed-type array (with different element types) in OpenAPI 2.0?
  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. How to export swagger.json (or yaml)
  24. Swagger Inheritance and Composition
  25. Swagger HashMap property type
  26. Swagger: map of
  27. Swagger API which is having query string
  28. Combining defintions in Swagger docs
  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