Group schema components by content-type

[souenzzo]

I'm working on an API that has many content-type, and they use references to schema

The references to the user entity, for example, aren't the same on each content-type.

I'm currently handling that by adding a content-type prefix on each schema:

schemas:
  application/json_user:
    type: object
  application/custom+json_user:
    type: object

I'd like to use something like

schemas:
  application/json:
    user:
      ...
  application/custom+json:
    user:
      ...

[MikeRalphson]

Is your desire to group the schemas for ease of editing, production of documentation or another use-case?

[souenzzo]

Because they are distinct and I don't want to pollute the name of the schema

For example, in my application/custom+json content-type, we wrap enums with objects like {_t: enum, _v: "admin"}

So we have 2 distinct user schemas, one for application/json, other for application/custom+json

schemas:
  application/json_user:
    type: object
    properties:
      id:
        type: string
      role:
        type: string
        enum: [ admin, regular ]
  application/custom+json_user:
    type: object
    properties:
      id:
        type: string
      role:
        type: object
        properties:
          _t:
            type: string
            enum: [ enum ]
          _v:
            type: string
            enum: [ admin, regular ]

[karenetheridge]

You could use subschemas inside /components/schemas, via $defs:

components:
  schemas:
    user:
      $defs:
        application/json:
          ..
        application/custom:
          ..

And then reference them as "$ref": "#/components/schemas/user/$defs/application~1json"

[souenzzo]

@karenetheridge

This indeed partially works, but swagger-ui does not support this kind of references

• Open https://petstore.swagger.io/#/default/get_
• paste this on swagger url

data:application/json;base64,eyJjb21wb25lbnRzIjp7InNjaGVtYXMiOnsidXNlciI6eyIkZGVmcyI6eyJhIjp7InR5cGUiOiJudW1iZXIifX19fX0sIm9wZW5hcGkiOiIzLjAuMyIsInBhdGhzIjp7Ii8iOnsiZ2V0Ijp7InJlc3BvbnNlcyI6eyJkZWZhdWx0Ijp7ImNvbnRlbnQiOnsiYXBwbGljYXRpb24vanNvbiI6eyJzY2hlbWEiOnsiJHJlZiI6IiMvY29tcG9uZW50cy9zY2hlbWFzL3VzZXIvJGRlZnMvYSJ9fX19fX19fX0=

As we can see in the image

• The resolution of the schema works (we can find the number type in GET / route
• The bottom Schemas component does not support this kind of reference, showing an empty group

I would like to have an explicit example of this in OAI spec, then swagger-ui and other tools will be able to implement proper support.

[MikeRalphson]

I would like to have an explicit example of this in OAI spec, then swagger-ui and other tools will be able to implement proper support.

@karenetheridge it would be great if you could PR a new example to the examples/v3.1 directory 😁

[souenzzo]

@MikeRalphson I can do this PR?

[handrews]

Note that $defs is only allowed in OAS 3.1 and later, which Swagger UI does not support.

[souenzzo]

Something like this

components:
  schemas:
    Error:
      $defs:
        application/json:
          type: object
            required:
              - code
              - message
            properties:
              code:
                type: integer
                format: int32
              message:
                type: string
        text/plain:
          type: string

Can be added to petstore example

[souenzzo]

@MikeRalphson // @karenetheridge

is there anything i can do to help?

[handrews]

@souenzzo anyone can submit a PR! For a PR on the examples, you need a slight change as the first thing under /components/schemas still needs to be a schema name:

components:
  schemas:
    Error:
      $defs:
        application/json:
          type: object
          required:
            - code
            - message
          properties:
            code: 
              type: integer
              format: int32 
            message:
              type: string
        text/plain:
          type: string

So you would use "$ref": "#/components/schemas/Error/$defs/application~1json" to reference the JSON version, and "$ref": "#/components/schemas/Error/$defs/text~1plain" to references the plain text version. (The ~1 is how JSON Pointer escapes the presence of a /).

It's probably worth making a separate example rather than changing Petstore as my impression is that Petstore is the basic starting point. But that's just my impression, not any sort of official guidance.

Beyond that, you'll need swagger-ui to support OAS 3.1 which looks like it might happen in version 5.0. Theres nothing that the OAS spec can do about that.

[handrews]

This is more about documenting a possible convention in examples than about changing the spec, so I'm going to move it to the learn repo.

[karenetheridge]

Also note that media-types can be defined under /components as well, starting with v3.2.