$ref with a description next to it: OpenAPI 3.0 against 3.1
Last checked and updated
In OpenAPI 3.0, anything written next to a $ref is ignored: the specification says so, and a linter reports it. In OpenAPI 3.1 it is allowed. In a schema, any keyword may sit next to $ref; next to other references (to a parameter, a response) a description may, and a summary where the referenced object has one.
The same lines in both versions
buyer:
description: The user who placed the order
$ref: "#/components/schemas/User"
With openapi: 3.0.3:
$ apigit lint good30.yaml
37:34 error no-$ref-siblings $ref must not be placed next to any other properties (paths./orders.get.responses.200.content.application/json.schema.properties.buyer.description)
With openapi: 3.1.0 the same file has no finding on those lines.
A linter tells you; a bundler does not: it keeps the lines as written in both versions, and a documentation tool reading a 3.0 file may show the description of User ("A user account") where you expected "The user who placed the order".
Why the versions differ
A 3.0 Reference Object "cannot be extended with additional properties", and any that are added "SHALL be ignored". 3.1 schemas are JSON Schema 2020-12, where $ref is an ordinary keyword that applies together with its neighbours: the value must match the referenced schema and the keywords beside it. That is more than a description override:
nickname:
$ref: "#/components/schemas/Name"
maxLength: 20
In 3.1 this means a Name that is also at most 20 characters long. In 3.0 the maxLength does nothing.
Outside schemas, 3.1 is narrower: a reference to a parameter, a response, an example or a similar object may carry only summary and description, which by default override those of the referenced object. A summary has no effect where the referenced object has no such field: parameters and responses have only a description.
The form that works in both
buyer:
description: The user who placed the order
allOf:
- $ref: "#/components/schemas/User"
allOf with one entry means "this schema, plus what is written beside the allOf". It is valid in 3.0 and 3.1, and it is what to write while a file must stay on 3.0.
Migrating to 3.1
After changing the version, the allOf wrappers can be folded back into a plain $ref with siblings. The opposite direction is the risk: siblings that were silently ignored in 3.0 start to apply in 3.1. A stray maxLength or enum beside a $ref becomes a real constraint. Lint the 3.0 file for no-$ref-siblings first, and decide each finding before the version changes. nullable is the other keyword that changes meaning in the same migration.