Link cannot be a JSON reference pointing outside '#/components/links'

Issue ID: v3-validation-reference-link

Description

One or more JSON references to reusable links in your API point outside the #/components/links object in the API definition. The $ref of all reusable links mus point to a link 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 link has been defined, but it is incorrectly referenced from schemas and therefore ignored:

{
    "get": {
        "operationId": "getUserByName",
        "parameters": [
            {
                "name": "username",
                "in": "path",
                "required": true,
                "schema": {
                    "type": "string"
                }
            }
        ],
        "responses": {
            "200": {
                "description": "The User",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/user"
                        }
                    }
                },
                "links": {
                    "userRepositories": {
                        "$ref": "#/components/schemas/UserRepositories"
                    }
                }
            }
        }
    },
    // ...
    "components": {
        "links": {
            "UserRepositories": {
                "operationId": "getRepositoriesByOwner",
                "parameters": {
                    "username": "$response.body#/username"
                }
            }
        }
    }
}

Remediation

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

{
    "responses": {
        "200": {
            "description": "The User",
            "content": {
                "application/json": {
                    "schema": {
                        "$ref": "#/components/schemas/user"
                    }
                }
            },
            "links": {
                "userRepositories": {
                    "$ref": "#/components/links/UserRepositories"
                }
            }
        }
    }
}