Description
An OpenAPI 3.0 Reference Object ignores properties added beside $ref. Swagger 2.0 references follow the same JSON Reference rule. Expecting a sibling type or description to modify the target can make the intended contract differ from the effective definition.
Do not apply this rule indiscriminately to every $ref location or another specification version. A Path Item’s $ref, for example, has separate field rules.
Potential impact
Intended constraints or descriptions may not apply, leaving request validation, response validation or generated clients different from expectations.
Remediation
Keep only $ref in a Reference Object for these versions. Put additional information on the referenced definition, or consider allOf at a schema location when combined constraints are needed. Verify that the target exists and the constraints are compatible.
Examples
These OpenAPI 3.0 excerpts show reference use only. The info object and referenced components.schemas.MyObject definition are required separately.
Before
{
"openapi": "3.0.0",
"paths": {
"/": {
"get": {
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "integer",
"$ref": "#/components/schemas/MyObject"
}
}
}
}
}
}
}
}
}
After
{
"openapi": "3.0.0",
"paths": {
"/": {
"get": {
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MyObject"
}
}
}
}
}
}
}
}
}
The after example removes the ignored sibling type. The target’s type remains unchanged; this edit does not turn the referenced definition into an integer.