Errata and/or Spec Clarification Required for Security Scheme Object (OAS 3.0 and OAS 3.1)

[hornworm61]

(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"
                ]
              }
            }
          }
        }
      ]
    }

[hkosova]

From #1876 (comment):

As per RFC7235 auth scheme is case insensitive:

2.1. Challenge and Response

HTTP provides a simple challenge-response authentication framework
that can be used by a server to challenge a client request and by a
client to provide authentication information. It uses a case-
insensitive token as a means to identify the authentication scheme,
followed by additional information necessary for achieving

https://tools.ietf.org/html/rfc7235#section-2.1

So if that means that bearer in the definition of bearerFormat is also case-insensitive, then JSON Schema should be changed from

"enum": [
  "bearer"
]

to something like

"pattern": "^[Bb][Ee][Aa][Rr][Ee][Rr]$"

[hornworm61]

Sounds right (in both the positive and negative branches of the oneOf).

[hornworm61]

PR: #2706

[handrews]

PR was merged! Closing.