OpenAPI Schema Nested Models (more than 1 level)

Question

Using OpenAPI 3+ and Redoc, and having issues with references not working once I go more than one level deep, is there something i'm doing wrong or missing here?

openapi.yaml

components:
  schemas:
    $ref: components/schemas/_index.yaml

components/schemas/_index.yaml

AdminParticipants:
  $ref: ./admin/Participants.yaml
admin:
  $ref: "./admin/_index.yaml"

components/schemas/admin/_index.yaml

Participants:
  $ref: ./Participants.yaml

When trying to access the schema model using below reference it does not work (get Invalid reference token: Participants error)

$ref: "#/components/schemas/admin/Participants"

However this does work:

$ref: "#/components/schemas/AdminParticipants"

Is it not possible to create nested references more than one level deep for schemas or any other components?

Helen · Accepted Answer · 2023-02-07T18:05:34.313

OpenAPI does not actually support $ref directly under the components.schemas node. You can only $ref individual schemas or schema properties. Some tools might accept $refs in arbitrary places, but the behavior may vary.

Here's the version that will work with any OpenAPI-compliant tools:

# openapi.yaml

components:
  schemas:
    AdminParticipants:
      $ref: ./admin/Participants.yaml
    AnotherSchema:
      $ref: ./path/to/schema.yaml

You'll can then reference these schemas as:

$ref: '#/components/schemas/AdminParticipants'

$ref: '#/components/schemas/AnotherSchema'

The following will NOT work - not only because of non-standard $ref placement in openapi.yaml, but also because it would result in a wrong structure of the schemas section.

# openapi.yaml

components:
  schemas:
    $ref: components/schemas/_index.yaml

# components/schemas/_index.yaml

admin:
  $ref: "./admin/_index.yaml"

# components/schemas/admin/_index.yaml

Participants:
  $ref: ./Participants.yaml

After dereferencing, the snippets above become:

components:
  schemas:
    admin:
      Participants:
        type: object  # or however the schema is defined in 'Participants.yaml'
        ...

which has an extra key between the schema name and schema contents, so it's not valid OpenAPI.

Ahhh okay thank you for the clarification, I guess I just assumed that schema's could be nested like that, I appreciate the thorough explanation and examples! — sMyles, Feb 07 '23 at 17:50
With that said though, are we expected to just have a huge file with all of the models and schemes in a single file then i guess? Just seems hard to organize any large projects — sMyles, Feb 07 '23 at 17:52

OpenAPI Schema Nested Models (more than 1 level)

1 Answers1