In OpenAPI, what can you store under components besides schemas, and how is each reused?

## The registry is wider than schemas `components` is a container of named, reusable pieces. It has a fixed set of fields — you cannot invent new ones — and each field is a map from a name you choose to an object of one specific type. In OpenAPI 3.0 the fields are: - **`schemas`** — Schema Objects; by far the most used. - **`responses`** — full Response Objects: `description`, `content`, `headers`. - **`parameters`** — Parameter Objects, complete with `name`, `in`, `required`, `schema`. - **`examples`** — Example Objects (a `value` or an `externalValue`, with a `summary`). - **`requestBodies`** — Request Body Objects: `content` keyed by media type, plus `required`. - **`headers`** — Header Objects, used inside response `headers` maps. - **`securitySchemes`** — Security Scheme Objects. - **`links`** — Link Objects describing how one operation's response feeds another operation's input. - **`callbacks`** — Callback Objects describing out-of-band requests the API makes back to the client. OpenAPI 3.1 adds **`pathItems`**. Component names must match `^[a-zA-Z0-9\.\-_]+$`, and the maps are namespaced per field — a `Pet` under `schemas` and a `Pet` under `examples` do not collide. ## How each is referenced The rule is uniform: write `$ref` where the inline object would go, and point at the matching sub-map. - A response: under an operation's `responses`, replace the whole status-code value with `$ref: '#/components/responses/NotFound'`. Note the shared response carries its own `description`, so you must not write one alongside the reference in 3.0. - A parameter: an entry in the operation's (or path item's) `parameters` array becomes `- $ref: '#/components/parameters/PageSize'`. - A request body: the operation's `requestBody` value becomes a reference. - A header: inside a Response Object's `headers` map, the value for `X-RateLimit-Remaining` becomes a reference into `components.headers`. - An example: inside a Media Type Object's `examples` map, each named example may be a reference into `components.examples`. - A link or callback: same pattern, in the operation's `links` and `callbacks` maps. Putting a reference in the wrong slot is the common error — pointing an operation's `responses.'404'` at `#/components/schemas/Error` yields a document where a schema is being used as a response, and validators reject it because a Response Object requires a `description`. ## The security exception Security requirements do not use `$ref`. Once a scheme is defined as `components.securitySchemes.bearerAuth`, an operation opts into it with `security: [ { bearerAuth: [] } ]` — the map key *is* the reference, and the array holds scopes (empty for non-OAuth2 schemes). Reaching for `$ref` here is a reliable sign someone has not read that part of the specification. ## Path items: reusing a whole path In OpenAPI 3.0 the Path Item Object has a dedicated `$ref` field, so a path's entire definition can live in another file and be pulled in: ``` /pets: $ref: './paths/pets.yaml' ``` This is how large specs are split by resource. It is a quirk — the reference sits *inside* the path item rather than replacing it — and tool support has historically been uneven. OpenAPI 3.1 tidies this up by adding `components.pathItems`, so a path item can be a named component like anything else. ## Why the breadth matters Reusing only schemas leaves most of the duplication in place. A large document typically repeats the same four or five error responses on every operation, the same pagination parameters on every collection, and the same correlation-id header on every response. Moving those into `components.responses`, `components.parameters` and `components.headers` collapses hundreds of lines and, more importantly, makes a change to the error envelope a one-line edit rather than a search-and-replace across the file. There is a limit: a shared response bakes in its own `description`, so operations that need different wording for the same status code cannot share one component in 3.0 — you either accept generic wording or define two components. That tension between deduplication and per-operation nuance is the main reason teams stop short of full reuse. ## Practical hygiene Unreferenced components accumulate silently; a linter rule that flags unused entries is worth having, because many code generators emit a model for every schema in the registry, referenced or not, and stale entries end up in shipped SDKs.