Depth & Breadth Limits

## A finite schema, an infinite set of legal documents A GraphQL schema declares a finite list of types, and that fact misleads people into assuming the set of legal documents is bounded too. It is not. An object type may declare a field whose type is another object type — including itself, directly or through a chain of other types. The schema is a **graph**, and graphs have cycles. A livestock pedigree service is the clearest case, because the domain itself is recursive: ```graphql type Animal { id: ID! tag: String! sire: Animal dam: Animal offspring(first: Int = 25): [Animal!]! } ``` One object type, four fields. `Animal.sire` returns an `Animal`, so `sire { sire { sire { tag } } }` is a legal selection — and so is the same construction four hundred levels deep. Nothing in the schema says how many times a caller may go round the cycle, because **depth is a property of the document, not of the schema**. Two object types that merely reference each other (`Herd.animals` and `Animal.herd`) are enough; a single self-referencing field is not required. ## The specification does not bound it, and only one of its rules is about cycles GraphQL's validation rules are about *correctness*: a selected field must exist on the type, an argument must have the right type, a declared variable must be used, a fragment must be spreadable on the type it lands on. None of them is a size, depth or cost rule. The specification defines what a valid document *means*; it deliberately says nothing about what a server should be willing to *run*. The one cycle rule people half-remember is real, but narrower than they think: **fragment spreads must not form cycles**. This is invalid — ```graphql fragment Ancestry on Animal { tag sire { ...Ancestry } } ``` — because `Ancestry` spreads itself transitively, and a validating server rejects the document. That rule exists so that fragment expansion and validation terminate, not as an abuse control. The proof is that you can write the identical nesting by hand, unrolled, as deep as you can type it, and the document is perfectly valid. So the specification closes exactly one route to an unbounded document and leaves the obvious one open. ## Why deep nesting costs, and when it does not Depth is expensive along two very different axes, and a good answer separates them. **Parsing and validation** are roughly linear in document size. A three-hundred-level chain is a few kilobytes of text; parsing it is not what hurts you. Naively recursive validators or serializers can blow a stack, but that is an implementation bug, not the resource story. **Execution** depends entirely on whether the cycle passes through a *list* field. Nesting through a to-one field — `sire { sire { sire } }` — resolves one record per level, so three hundred levels is three hundred single-row lookups: slow and serial, but linear. Nesting through a list field is multiplicative. If a recorded sire averages 12 offspring, then `offspring { offspring { offspring … } }` reaches roughly 12^n nodes: about 249,000 at five levels and over 400 million at eight. That is the shape a depth cap is really a proxy for, and saying so is what separates a memorised answer from an understood one. ## What servers do about it, and what it is called Every mainstream GraphQL server ships a maximum-depth check, and it is a **widespread convention, not a specified feature** — say that plainly, because interviewers listen for it. It is implemented as an additional validation rule: after the document parses, walk each operation's selection sets, track the longest root-to-leaf path, and reject the request if it exceeds the configured cap. Because it fails during validation, the *shape* of the failure is specified even though the rule is not. A document that fails validation is answered with an `errors` entry and **no `data` key at all** — the request never entered execution, so there is no partial data to report. That is a different response shape from a resolver throwing mid-execution, which yields `data` with a null hole and a field error beside it. ## Counting depth correctly Depth must be measured on the *flattened* document. A fragment spread contributes its own nesting at the point where it is spread, so a six-level fragment spread inside a selection already five levels deep is eleven. Counting only the literal brace nesting in the operation body under-reports, and it is the single most common bug in a hand-rolled limiter — an attacker only has to move the deep part into a fragment. ## What a depth cap does not solve It bounds one dimension. A document that is two levels deep and eight hundred fields wide slips under any depth cap, and a legitimately deep traversal — twelve generations of ancestry — is rejected by a cap tuned for a flat schema. Depth is a floor, not the whole control.