Skip to content

$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.

Sources

Related pages

Try it with your own API

Create a free workspace, add an OpenAPI file, and publish its documentation and a mock server from the same repository.

Free for individuals. No credit card.

$ npm install -g @apigit/cli$ apigit auth login$ apigit doc publish