Callback cannot be a JSON reference pointing outside '#/components/callback'

Issue ID: v3_1-validation-reference-callback

Description

One or more JSON references to reusable callbacks in your API point outside the #/components/callback object in the API definition. The $ref of all reusable callbacks must point to a callback object in the components object, otherwise they have no effect.

For more details, see the OpenAPI Specification.

Example

The following is an example of how this issue could look in your API definition. Here, a reusable callback has been defined, but it is incorrectly referenced from parameters and therefore ignored:

{
    "responses": {
        "201": {
            "description": "subscription created",
            "content": {
                // ...
            },
            "callbacks": {
                "callback_1": {
                    "$ref": "#/components/parameters/onData"
                }
            }
        }
    },
    // ...
    "components": {
        // ...
        "callbacks": {
            "onData": {
                "{$request.query.callbackUrl}/data": {
                    "post": {
                        "requestBody": {
                            "description": "subscription payload",
                            "content": {
                                "application/json": {
                                    "schema": {
                                        "properties": {
                                            "timestamp": {
                                                "type": "string",
                                                "format": "date-time"
                                            },
                                            "userData": {
                                                "type": "string"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}

Remediation

Make sure that all JSON references to reusable links point to #/components/callbacks.

{
    "responses": {
        "201": {
            "description": "subscription created",
            "content": {
                // ...
            },
            "callbacks": {
                "callback_1": {
                    "$ref": "#/components/callbacks/onData"
                }
            }
        }
    }
}