Description
OpenAPI 3.0 can define data structures in components.schemas and reuse them through $ref. A missing schema target can prevent documentation tools from resolving request or response fields and types.
Potential impact
- Request or response structures may not display correctly in the documentation.
- Code generation or validation can fail, and API users may make incorrect assumptions about fields and types.
Remediation
Match the schema $ref path and name to an existing Schema Object. Check components.schemas for local references and the target document and path for external references. Update all uses when renaming a definition, then validate the specification and data structures.
Examples
These examples reference a JSON schema inside response content. The first target, MyWrongObject, 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": {
"$ref": "#/components/schemas/MyWrongObject"
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"MyObject": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
}
}
}
}
}
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": {
"$ref": "#/components/schemas/MyObject"
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"MyObject": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
}
}
}
}
}
The second example references MyObject and describes id and name as strings. The schema defines the body’s data structure; it does not replace the entire Response Object.