Modelling base type

[mwadams]

What is the thinking behind modelling a base type as a single allOf->$ref rather than just a naked $ref?

I tend to model a unitary "base" with the naked $ref and use allOf for "general composition".

[bterlson]

OpenAPI 3.0 does not allow $ref to exist next to other fields like description, so it seems like (maybe most?) 3.0 tooling has settled on nesting $ref in an allOf as a way to work around this limitation.

[bterlson]

Hmm although I am not sure if we would ever emit anything alongside the ref specifically for model extends. If this in particular is a problem, whereas a case like

model Foo extends Bar {
  /** a bar */
  bar: Bar;
}

that emits

      properties:
        bar:
          allOf:
            - $ref: '#/components/schemas/Bar'
          description: a bar

is not a problem, perhaps this could be changed.

[mwadams]

Yes; this is definitely a problem for what I laughingly call "legacy" Open API :-) Because its JSON Schema semantics are based on a pre 2019-09 JSON Schema, that isn't going to work.

For "modern" 2019-09-and-later (specifically 2020-12 and later i.e. OpenAPI 3.1) it is a nicer way to model "base", and allows us to distinguish "base" from "mix-in/composition".