ref-no-siblings
Since 0.12.0 · In the rulesets: Recommended at warning, Strict at error, All at error
This rule checks that, in an OpenAPI 3.0 document, no property other than an extension sits next
to the $ref of a Reference Object.
Rule details
In OpenAPI 3.0, an object with $ref is replaced by the object it refers to: any other property
next to $ref is ignored. A description or a nullable: true next to $ref does not apply:
the specification says to ignore it, and tools that follow it do so without a message. OpenAPI
3.1 allows a summary and a description next to $ref in a Reference Object, and any keyword
next to $ref in a schema. The rule checks 3.0 documents only: in 3.1 and 3.2 it does not report
the other keys a Reference Object ignores.
The rule reports "<property>" next to $ref is ignored in OpenAPI 3.0 on each such property.
Specification extensions (x-...) are not reported. A Path Item Object’s $ref is not checked:
OpenAPI 3.0 allows fields next to it. A $ref key in data is not a reference. Data are the
values of example, default and enum, of a schema’s examples list, of an Example Object’s
value, of a Link Object’s parameters and requestBody, and of extensions. A YAML alias is
checked where its anchor stands, once.
Turn the rule off when every tool that reads the document applies the properties next to $ref.
To keep a description with a reference in 3.0, wrap the reference in allOf:
Pet:
description: A pet
allOf:
- $ref: '#/components/schemas/Animal'
Examples
Good.
openapi: 3.0.3
components:
schemas:
Pet:
$ref: '#/components/schemas/Animal'
Bad. The description is ignored.
openapi: 3.0.3
components:
schemas:
Pet:
$ref: '#/components/schemas/Animal'
description: A pet
Turn it off or change its severity
In apigenie.yaml, off turns the rule off and warning or error sets its severity; a rule with options takes the severity and the options as a pair, [warning, options]. lint.rules has the details.
commands:
lint:
rules:
ref-no-siblings: off