Description
A callback defined in components.callbacks is not part of an operation’s callback contract unless it is referenced from that operation. Reference active callbacks through callbacks, and remove unnecessary definitions only after checking other documents that may use them.
Potential impact
- Readers may mistake an unused callback for an implemented API feature.
- Unnecessary definitions add maintenance work when the API changes.
Remediation
Reference the component with $ref in callbacks on the operation that needs it. Before removing a definition, check references from other documents and tools. Validate the references and callback URL expressions after changes.
Examples
These examples compare a callback definition with its attachment to an operation. The POST request body supplying inProgressUrl is omitted.
Before
{
"openapi": "3.0.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"paths": {
"/": {
"post": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"responses": {
"200": {
"description": "Success"
}
}
}
}
},
"components": {
"callbacks": {
"inProgress": {
"{$request.body#/inProgressUrl}": {
"post": {
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "OK"
}
}
}
}
}
}
}
}
After
{
"openapi": "3.0.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"paths": {
"/": {
"post": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"responses": {
"200": {
"description": "Success"
}
},
"callbacks": {
"myEvent": {
"$ref": "#/components/callbacks/inProgress"
}
}
}
}
},
"components": {
"callbacks": {
"inProgress": {
"{$request.body#/inProgressUrl}": {
"post": {
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "OK"
}
}
}
}
}
}
}
}
The second example references inProgress through callbacks.myEvent. This documents the callback contract; it does not implement the server’s outbound request.