oas3-no-$ref-siblings
This rule should only apply to OpenAPI 3.1+ documents.
JSON Schema References allows 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.
Not all key values are acceptable as siblings, the only allowed sibling keywords in OpenAPI 3.1+ are:
summary and description
Why did this violation appear?
A $ref value was used, but it contains a sibling node (another property on the same level) that is not allowed.
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'
type: [string]
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'
description: An object that describes a list of pizzas.
components:
schemas:
PizzaList:
description: "A list object contains a list of pizzas"
properties:
...
How do I fix this violation?
Make sure $ref values only contain siblings that are approved (summary and description)
Spectral Equivalent
The rule is equivalent to no-$ref-siblings