skip to content

In an OpenAPI security scheme of type http, what do scheme and bearerFormat actually specify?

level: middleimportance: should knowfreq 50%

answer

  1. One field picks the Authorization header's shape
  2. Its legal values come from a registry
  3. The other field is a comment
  4. Conventionally it says JWT
  5. Nothing parses the token because of it

basics

~20 s

OpenAPI's http scheme field names an HTTP authentication scheme from the IANA registry — basic, bearer, digest — and determines the Authorization header's form. bearerFormat is a free-text documentation hint about the token's format and is ignored by tooling.

solid answer

~40 s

`type: http` says the API uses the HTTP authentication framework, so credentials travel in the `Authorization` header. The `scheme` field names which HTTP authentication scheme: values come from the IANA registry established with RFC 7235, so `basic`, `bearer` and `digest` are the ones you see. That value is what makes tooling build `Authorization: Bearer <token>` or `Authorization: Basic <base64>` correctly. `bearerFormat` applies only when `scheme` is `bearer` and is **purely informational** — a free-text hint, conventionally `JWT`, telling a human reader what the opaque string contains. No generator, validator or renderer parses or verifies anything because of it; writing `bearerFormat: JWT` does not make a document require, or a tool check, a JWT. Because `type: http` already describes the header, a header parameter named `Authorization` is ignored by the spec.

code

yaml · 17 lines
yaml
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Documentation-only hint; nothing validates the token here.
    basicAuth:
      type: http
      scheme: basic

    # Anti-pattern kept for contrast - generated clients then demand the
    # caller type the word Bearer themselves.
    wrongBearer:
      type: apiKey
      in: header
      name: Authorization

go deeper

for a junior

Know that type: http with scheme: bearer is how a token in the Authorization header is declared, and that the scheme value picks Basic versus Bearer.

for a middle

Explain that scheme values come from the HTTP authentication registry and that bearerFormat is documentation only, plus why the apiKey workaround is a Swagger 2.0 leftover.

for a senior

Demonstrate that you separate description from enforcement — the document tells clients what to send, while the gateway or filter chain is what actually rejects a bad token.

for a principal

Own how the declared scheme and the enforced one stay in step across services, so a misconfigured gateway does not sit behind a document that still claims every operation is protected.

## What type: http means HTTP has its own authentication framework: a server challenges with `WWW-Authenticate`, and a client answers with `Authorization: <scheme> <credentials>`. The scheme names in that exchange are not free-form — they live in an IANA registry established alongside RFC 7235. OpenAPI's `type: http` security scheme is a declaration that the API participates in this framework, and its `scheme` field carries one of those registered scheme names, lowercased. The values that appear in practice: - **`basic`** — `Authorization: Basic <base64 of user:password>` - **`bearer`** — `Authorization: Bearer <token>` - **`digest`** — challenge/response with nonces; rare in modern APIs Because the header's shape follows from the scheme name, tooling can construct it. A Swagger UI Authorize dialog for `basic` prompts for a username and password and does the encoding; for `bearer` it prompts for a token and prepends `Bearer `. A generated SDK exposes a credential setter and adds the header on every request. That automation is the whole reason to use `type: http` rather than modelling the header by hand. ## What bearerFormat is `bearerFormat` is an optional string, meaningful only when `scheme` is `bearer`. The specification describes it as a hint to the client to identify how the bearer token is formatted, primarily for documentation purposes. The conventional value is `JWT`; teams also write things like `opaque`. The critical point, and the reason interviewers ask: **it has no machine semantics**. Nothing validates it. No generator produces different code for `bearerFormat: JWT` than for a bearer scheme with no `bearerFormat` at all. No request validator inspects the token to check it parses. It is a comment with a schema-blessed home. A candidate who says "setting `bearerFormat: JWT` makes tooling verify the token" has misunderstood the document's role: OpenAPI describes the interface; verification is the service's job. ## Why not model the header as a parameter The recurring anti-pattern is declaring `type: apiKey` with `in: header` and `name: Authorization`, or worse, a plain header parameter named `Authorization`. Three problems. First, the specification says a header parameter named `Accept`, `Content-Type` or `Authorization` SHALL be ignored, so the parameter version simply does not describe anything. Second, the apiKey version treats the whole header value as an opaque string, so the generated client asks the caller to supply `Bearer eyJ...` including the prefix — and callers forget it. Third, renderers cannot offer the right Authorize control. The habit comes from **Swagger 2.0**, which had no `http` type: it offered only `basic`, `apiKey` and `oauth2`, so bearer tokens genuinely had to be declared as an apiKey in a header there. In 3.x that workaround is obsolete. ## Applying it Defining the scheme is half the job. It must then be applied through a security requirement — `security: [ { bearerAuth: [] } ]` at the root, or per operation. For an `http` scheme the array is empty: scope lists are meaningful only for `oauth2` and `openIdConnect`. ## What this buys you and what it does not What it buys: consistent generated clients across languages, a working Authorize dialog in documentation, and lint rules that can check every operation is covered. What it does not buy: any runtime guarantee. The document is a contract description. If the gateway is misconfigured and serves an operation anonymously, the OpenAPI document will still say `bearerAuth` and every validator will still pass. Keeping declaration and enforcement in step is an engineering discipline — contract tests, gateway configuration generated from or checked against the spec — not something the syntax provides.

  • Does bearerFormat: JWT cause any tool to validate the token?
    No. It is a documentation hint identifying how the bearer token is formatted, and the specification says as much. Generators emit identical code with or without it, request validators do not parse the token, and renderers only display it. If a JWT must actually be validated, that happens in the service or gateway; the document merely tells a human reader what to expect inside the opaque string.
  • Where do the legal values of the http scheme field come from?
    From the IANA HTTP Authentication Scheme registry established with RFC 7235 — the same names that appear after `Authorization:` and in `WWW-Authenticate` challenges. `basic`, `bearer` and `digest` are the ones seen in API documents. Inventing a value there means tooling cannot construct the header correctly, since the header's shape is determined by the registered scheme.
  • What scope array does an http scheme take in a security requirement?
    An empty one: `- bearerAuth: []`. Scope lists carry meaning only for `oauth2` and `openIdConnect` schemes. OpenAPI 3.0 requires the array to be empty for every other type, while 3.1 relaxed it to permit role names that the specification leaves undefined and that are not exchanged in-band — so tooling still does nothing with them.

saying these in an interview costs you the question

  • Says bearerFormat makes tooling validate the token
  • Declares bearer auth as an apiKey Authorization header
  • Invents scheme values outside the HTTP registry
  • Adds a header parameter named Authorization
  • Puts scope names in an http scheme's requirement array

context

resolving links…