Security scheme cannot be a JSON reference that points outside '#/components/securitySchemes'

Issue ID: v3-validation-reference-securityscheme

Description

One or more JSON references to reusable security schemes in your API point outside the #/components/securitySchemes object in the API definition. The $ref of all reusable security schemes must point to a securityScheme 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 security scheme has been defined incorrectly in schemas and therefore ignored:

{
    "components": {
        "securitySchemes": {
            "APIkey": {
                "type": "apiKey",
                "name": "X-API-Key",
                "in": "header"
            },
            "OAuth": {
                "$ref": "#/components/schemas/OAuth"
            }
        },
        //...
        "schemas" :{
            "OAuth": {
                "type": "oauth2",
                "flows": {
                    "authorizationCode": {
                        "authorizationUrl": "https://example.com/api/oauth/dialog",
                        "tokenUrl": "https://example.com/api/oauth/token",
                        "scopes": {
                            "write:pets": "modify pets in your account",
                            "read:pets": "read your pets"
                        }
                    }
                }
            }
        }
    }
}

Remediation

Make sure that all JSON references to reusable security schemes point to #/components/securitySchemes.

{
    "components": {
        "securitySchemes": {
            "APIkey": {
                "type": "apiKey",
                "name": "X-API-Key",
                "in": "header"
            },
            "OAuth": {
                "$ref": "#/components/securityschemes/OAuth"
            },
            //...
            "OAuth": {
                "type": "oauth2",
                "flows": {
                    "authorizationCode": {
                        "authorizationUrl": "https://example.com/api/oauth/dialog",
                        "tokenUrl": "https://example.com/api/oauth/token",
                        "scopes": {
                            "write:pets": "modify pets in your account",
                            "read:pets": "read your pets"
                        }
                    }
                }
            }
        }
    }
}