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

Related rules

Further reading

Last updated on View as Markdown
Was this helpful?