Why OpenAPI 3.1.0 does not allow schema references in Parameter & Media Type objects?

[flaksp]

It feels very strange for me that Parameter Object (schema field) and Media Type Object (schema field) do not allow Reference Object to be passed. Maybe I am blind, but I can't find places in spec where schemas defined in #/components/schemas/* may be reused because there are no definitions of something like Schema Object | Reference Object in the spec. As I see currently component schemas may be reused only within another schemas (e.g. via allOf, oneOf, items, properties, etc).

Isn't it a good idea to add Schema Object | Reference Object to Parameter Object and Media Type Object?

[char0n]

JSON Schema 2020-12 used in OAS 3.1 has it's own mechanism of making references: https://json-schema.org/draft/2020-12/json-schema-core.html#ref. Which means Schema Object itself can act as a reference if defined in following way:

{ "$ref": "#/pointer" }

[flaksp]

Yeah, but OpenAPI 3.1.0 defines its own extension for Reference Object with extra fields: summary and description. The last field may be nicely used with Schemas because they may also have description field.

Seems like OpenAPI 3.1.0 lacks statement like "we extend JSON Schema's references with description and summary fields, additional fields may be used everywhere JSON Schema reference expected". It's also possible to avoid this statement by explicitly defining schema value as Schema Object | Reference Object.

I think this definition should be considered as invalid in 3.1.0:

application/json: 
  schema:
    $ref: "#/components/schemas/Pet" # this field allowed here
    description: "Description goes here" # this field is NOT allowed here by JSON Schema spec
    summary: "Summary goes here" # this field is NOT allowed here by JSON Schema spec

[char0n]

Seems like OpenAPI 3.1.0 lacks statement like "we extend JSON Schema's references with description and summary fields, additional fields may be used everywhere JSON Schema reference expected".

Reference Object is defined withing OAS 3.1 spec and has it's own rules. Schema Object is defined outside of OAS 3.1 spec in https://json-schema.org/specification.html. OAS 3.1 just defines an extending vocabulary on top of Schema Object. The de-referencing & merging rules for Schema Object are different; like for example Schema Object $id and $schema fields have big impact on resolution and dereferencing.

It's also possible to avoid this statement by explicitly defining schema value as Schema Object | Reference Object.

As already mentioned, Schema Object has it's own referencing mechanism and semantics on Schema Objects with $ref keyword. OAS 3.1 defines it explicitly:

Relative references in Schema Objects, including any that appear as $id values, use the nearest parent $id as a Base URI, as described by JSON Schema Specification Draft 2020-12. If no parent schema contains an $id, then the Base URI MUST be determined according to RFC3986.

Maybe please refer to this issue asyncapi/spec#552 in AsyncAPI spec, when they currently have only Reference Object and explicitly ignore JSON Schema referencing capabilities.

[hkosova]

@flaksp your example

application/json: 
  schema:
    $ref: "#/components/schemas/Pet"
    description: "Description goes here"
    summary: "Summary goes here"

is perfectly valid in OAS 3.1.0.

Schemas support $ref siblings as part of JSON Schema 2019-09 and later. (OAS 3.1 uses JSON Schema 2020-12 by default.) Schema $refs are a bit different from OpenAPI Reference Objects (used for parameter $refs, response $refs, etc.) in that schema $refs support any sibling keywords, whereas OAS Reference Objects only support sibling summary and description.

Note that JSON Schema doesn't have the summary keyword so it will be handled as an annotation.

[handrews]

Closing as answered (in 2021)