Description
OpenAPI 3.0 can reuse definitions in components.headers through $ref. If a target is missing, documentation tools may be unable to display the response header’s format or meaning correctly.
Potential impact
- Response header information may be absent from the rendered documentation.
- Unresolved references can disrupt specification validation or client generation.
Remediation
Match local header reference paths and component names to definitions in components.headers, including exact letter case. For external references, check the target file and path. Validate reference resolution after the change.
Examples
These examples reference the X-Pages header definition from the response’s headers. The first target, wPages, is not defined.
Before
json
{
"openapi": "3.0.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"paths": {
"/": {
"get": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"responses": {
"200": {
"description": "success",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/MyObject"
}
}
}
},
"headers": {
"X-Pages": {
"$ref": "#/components/headers/wPages"
}
}
}
}
}
}
},
"components": {
"schemas": {
"MyObject": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
}
}
},
"headers": {
"xPages": {
"schema": {
"type": "integer",
"description": "number of pages"
}
}
}
}
}
After
json
{
"openapi": "3.0.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"paths": {
"/": {
"get": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"responses": {
"200": {
"description": "success",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/MyObject"
}
}
}
},
"headers": {
"X-Pages": {
"$ref": "#/components/headers/xPages"
}
}
}
}
}
}
},
"components": {
"schemas": {
"MyObject": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
}
}
},
"headers": {
"xPages": {
"schema": {
"type": "integer",
"description": "number of pages"
}
}
}
}
}
The second example references the existing xPages definition and its integer schema. Matching a component name is separate from HTTP header names being case-insensitive.