Errata and/or Spec Clarification Required for Security Scheme Object (OAS 3.0 and OAS 3.1) #2703
Description
(This applies to both 3.0 and 3.1, but I'm referencing 3.1 sections)
Section 4.8.27 defines the "scheme" field of the Security Scheme Object as "The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235]. The values used SHOULD be registered in the IANA Authentication Scheme registry."
It isn't clear whether this field is case-insensitive. RFC7235 implies that in the context of the Authorization header, the value is case insensitive, but it is confusing whether it is also case insensitive here. The IANA Authentication Scheme registry defines several values, including "Basic" and "Bearer" with an initial upper case character in each case. The examples in the OAS use "basic" and "bearer", which does imply that is should be case-insensitive in this context as well.
But confusing matters further in the OAS for Security Scheme Objects is the definition of "bearerFormat", which implies that it is valid only if "scheme" is "bearer". The official JSON Schema for OpenAPI files only allows "bearerFormat" if the scheme is literally "bearer". Should it not also be valid is the scheme is "Bearer" (or any other combination of upper and lower case characters)?
Specifically, the following OpenApi fragment does not pass schema validation, but I believe the specification implies that it should be OK:
"securitySchemes": {
"global": {
"type": "http",
"description": "A bearer token granting access to the operation is required.",
"scheme": "Bearer",
"bearerFormat": "JWE"
}
}
Some words of clarification in the specification would be helpful, as well as a confirmation that the JSON Schema is either correct or is in error.
For reference, the JSON Schema that fails this is:
"HTTPSecurityScheme": {
"type": "object",
"required": [
"scheme",
"type"
],
"properties": {
"scheme": {
"type": "string"
},
"bearerFormat": {
"type": "string"
},
"description": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"http"
]
}
},
"patternProperties": {
"^x-": {
}
},
"additionalProperties": false,
"oneOf": [
{
"description": "Bearer",
"properties": {
"scheme": {
"enum": [
"bearer"
]
}
}
},
{
"description": "Non Bearer",
"not": {
"required": [
"bearerFormat"
]
},
"properties": {
"scheme": {
"not": {
"enum": [
"bearer"
]
}
}
}
}
]
}