In OpenAPI, is a self-referential schema legal, and what breaks with circular $ref chains?

## Recursion is a feature, not an accident Plenty of real payloads are recursive: comment threads, org charts, category trees, filter expressions, file-system nodes. OpenAPI's Schema Object inherits JSON Schema's reference model, and JSON Schema explicitly permits a schema to reference itself. So `Comment` with a `replies` array whose `items` is `#/components/schemas/Comment` is legal and idiomatic. Cycles can also be indirect: `A` references `B`, `B` references `A`. Nothing forbids that either. ## The question that decides validity: can an instance terminate? A recursive schema describes a set of documents. That set is non-empty only if the recursion can bottom out. Two shapes matter. **Terminating.** The self-reference is reached through an optional property, or through an array's `items`. An empty array, or an absent property, ends the descent. `{ "id": "c1", "replies": [] }` satisfies the recursive `Comment` schema, so the contract is satisfiable. **Non-terminating.** Every step of the cycle is mandatory: `Node` has `required: [child]` and `child` is a `Node`. Now every valid instance must contain another valid instance, forever. No finite JSON document satisfies it. This is not an error a validator is obliged to catch — most will happily accept the document as a *spec* and then reject every payload you send. It is a modelling bug, and the symptom in the wild is "the schema validates but nothing I send ever passes". The same trap appears through composition: a schema that composes itself unconditionally, rather than behind an optional property, cannot terminate either. ## What breaks in tooling The spec permits recursion; individual tools vary in how well they cope. **Inlining resolvers loop.** Anything that replaces a `$ref` with a copy of its target cannot finish on a cycle. A full dereference of a recursive spec either detects the cycle and bails, or expands until it exhausts memory. This is the single most common way a recursive model breaks a build, and it is why you bundle (rewrite references to local pointers) rather than inline. **Example and mock generation.** Producing a sample payload from a recursive schema means choosing a depth. Well-behaved renderers cut off after a couple of levels and show a placeholder; less careful sample generators recurse until they hang the page or emit a megabyte of nested objects. **Code generation.** Most target languages handle a self-referential type naturally — a class with a list of its own type is ordinary. Trouble concentrates where a generator flattens or synthesises names for inline schemas, or where a cycle spans multiple files and a bundler renames one participant, silently producing two types where you meant one. **Validators and diff tools.** Anything doing a recursive walk needs a visited set. Tools that lack one stack-overflow on cyclic input; the giveaway is a crash with a deep, repeating stack rather than a validation message. ## How to keep recursion safe *Name every participant in a cycle.* A cycle made of named components under `components.schemas` is easy for tools to represent as a pointer; a cycle involving inline anonymous schemas is much harder for them to name and reuse. *Make the recursive edge optional or an array.* This is what makes the contract satisfiable and simultaneously gives every generator a natural termination point. *Bound the depth in the contract's prose.* Schemas cannot express "at most five levels", so state the server's limit in the `description` and enforce it in the implementation. Unbounded nesting is also a denial-of-service surface: a client can post a deeply nested body specifically to blow up your parser. *Prefer identifiers over embedding when the depth is unbounded in practice.* Returning `parentId: string` instead of an embedded `parent` object removes the cycle entirely and usually reflects how clients consume the data anyway — they fetch what they need. This is the standard fix when recursion causes more pain than it saves. *Test the pipeline, not just the document.* If your spec is recursive, run the actual generator, the actual docs build and the actual mock server in CI. A recursive schema that validates cleanly can still be the thing that hangs your documentation job.