spec-ref-siblings

Checks that only specification-permitted properties are used next to a $ref.

OpenAPI 3.1 treats $ref differently depending on where it appears:

• In a Schema Object keywords next to $ref take effect. All siblings are allowed.
• A Reference Object $ref cannot be extended. Only summary and description are allowed alongside $ref.

OAS 2.0 and OAS 3.0 predate JSON Schema 2020-12 and allow only the $ref itself. AsyncAPI and Open-RPC also allow only the $ref itself.

A Path Item Object is the exception: every OpenAPI version lists $ref among its own fields, so a Path Item keeps its siblings and the rule does not report them.

In Overlay 1.2, an item in actions that has a $ref applies a reusable action from components.actions. It must have a target, and it can also have a description and specification extensions. Action fields such as update, copy, and remove belong in the reusable action's fields, so the rule reports them next to $ref.

To configure the rule, add it to the rules object in your configuration file, and set the desired severity.

An example configuration:

rules:
  spec-ref-siblings: error

Given the following configuration:

rules:
  spec-ref-siblings: error

Example of incorrect siblings next to a Reference Object $ref (OAS 3.1), where neither headers nor the x-internal extension is allowed:

responses:
  '200':
    $ref: '#/components/responses/Ok'
    x-internal: true
    headers:
      X-Rate-Limit:
        schema:
          type: integer

Example of correct siblings next to a Reference Object $ref (OAS 3.1), where only summary and description are allowed:

responses:
  '200':
    $ref: '#/components/responses/Ok'
    description: overrides the referenced description

Example of correct siblings next to a Schema Object $ref (OAS 3.1), where JSON Schema 2020-12 keywords are allowed:

schema:
  $ref: '#/components/schemas/Base'
  readOnly: true
  description: a read-only variant of Base
  x-internal: true

• spec-strict-refs
• struct

• Rule source
• Reference Object docs