In an OpenAPI document, what does a $ref such as '#/components/schemas/Pet' resolve to?

## What a $ref actually is OpenAPI documents get large fast, and the same shapes — an error body, a pagination parameter, a `404` response — repeat across dozens of operations. `$ref` is the mechanism that lets you write such a thing once and point at it everywhere else. Wherever the specification allows a **Reference Object**, you may write an object whose single key is `$ref` and whose value is a URI identifying the definition to use instead. ## Reading the pointer A value like `#/components/schemas/Pet` has two parts. Everything before `#` names the document (empty here, meaning *this* document). Everything after `#` is a **JSON Pointer** (RFC 6901): a `/`-separated path of keys walked from the document root. So the resolver takes the root object, looks up `components`, then `schemas`, then the key `Pet`, and uses whatever it finds there. Because `/` separates segments, a key that itself contains a slash must be escaped: `~1` stands for `/` and `~0` stands for `~`. That is why a pointer at a path item looks like `#/paths/~1pets/get` — the path key is literally `/pets`. If the pointer does not resolve, the document is invalid; most tools fail loudly, though a few silently render an empty schema, which is worse. ## The components object `components` is the document's reuse registry. In OpenAPI 3.0 and 3.1 it may hold `schemas`, `responses`, `parameters`, `examples`, `requestBodies`, `headers`, `securitySchemes`, `links` and `callbacks`; 3.1 adds `pathItems`. Each is a map from a name you choose to a definition of that type. Names must match `^[a-zA-Z0-9\.\-_]+$` — no spaces, no slashes — because those names become fragments of pointers and, in practice, class names in generated code. The key property to internalise is that **components is inert**. Defining `components.schemas.Pet` does not create an endpoint, a model exposed to clients, or anything else visible in the API. It becomes part of the contract only when a path, a response, another schema or a parameter references it. A document whose entire `components` section is unreferenced describes an API with no shapes at all. (Some code generators do emit a model class for every entry regardless, which is why stale unused components tend to leak into SDKs.) ## Where $ref may appear A `$ref` is legal only where the specification declares a Reference Object is allowed — a schema position, a response, a parameter list entry, a request body, a header, an example, a link, a callback, and a path item. You cannot, for example, `$ref` half of an operation object or splice a reference into the middle of an arbitrary map. When a tool complains that a reference is "not allowed here", that is usually the reason. Note also that security requirements are the odd one out: an operation's `security` entry names a scheme by its **key** under `components.securitySchemes`, not by `$ref`. ## Version differences worth knowing In OpenAPI 3.0 the Reference Object holds `$ref` and nothing else; any sibling properties SHALL be ignored, so writing a `description` next to a `$ref` to explain a specific usage silently does nothing. OpenAPI 3.1 loosens this in two ways. The Reference Object itself gained optional `summary` and `description`, which override the referenced object's own. And because 3.1 aligns Schema Objects with JSON Schema 2020-12, inside a schema `$ref` is JSON Schema's `$ref`, where sibling keywords are allowed and apply alongside the reference. Swagger 2.0, the predecessor, had no `components` object: reusable schemas lived under a top-level `definitions`, so references read `#/definitions/Pet`. Seeing that pointer in a document claiming `openapi: 3.0.3` is a reliable sign of a bad conversion. ## What tools do with references Validators resolve references to check the document is coherent. Docs renderers usually keep the reference so the rendered page can link to a single named model. Code generators map a referenced schema to one named type and an inline schema to a synthesised name, which is a practical reason to name anything you want to appear as a first-class model in an SDK. Bundlers can rewrite external references into local ones, or inline everything — the latter loses the shared name and duplicates the shape.