no-$ref-siblings

JSON Schema References allow authors to re-use schemas for objects in multiple places. In the standard, $ref nodes are allowed sibling nodes (most commonly description) nodes that allow authors to describe the use of the reference in the context of the current definition.

OpenAPI is a superset of JSON Schema. However, in the OpenAPI standard, $ref values CANNOT place any sibling nodes (like a description) next to that $ref.

Essentially, OpenAPI will discard anything next to that $ref, it’s going to ignore it. Often this is where authors place a description, thinking that it was going to be picked up by tooling.

Why did this violation appear?

A $ref value was used, but it contains a sibling node (another property on the same level). in OpenAPI $ref values need to be the only child of a parent.

Bad example

paths:
  /pizzas:
    get:
      summary: "Get all pizzas"
      responses:
        '200':
          description: "A list of all the pizzas we have."
          content:
            application/json:
              schema:
                $ref: '#/shared-components/schemas/PizzaList'
                description: "A list object contains a list of pizzas"
components:
  schemas:
    PizzaList:
      properties:
      ...

Good Example

paths:
  /pizzas:
    get:
      summary: "Get all pizzas"
      responses:
        '200':
          description: "A list of all the pizzas we have."
          content:
            application/json:
              schema:
                $ref: '#/shared-components/schemas/PizzaList'
components:
  schemas:
    PizzaList:
      description: "A list object contains a list of pizzas"
      properties:
      ...

How do I fix this violation?

Make sure $ref values are the only child node, don’t place anything next to them.

Spectral Equivalent

The rule is equivalent to no-$ref-siblings