Selection Sets & Aliases

## A request is a tree, not a path A GraphQL document does not name a resource; it draws a tree over the schema's graph. Each pair of braces is a **selection set** — the list of fields being requested at that one point in the tree — and every field inside it may open a selection set of its own. The operation itself carries the root selection set, whose members are the fields declared on the root operation type. So the document's shape *is* the response's shape. Reading a document top to bottom tells you the keys of the JSON that comes back, level for level, with no schema lookup needed — which is the property most of GraphQL's tooling is built on. ## Where nesting stops The schema decides where the tree can keep growing. GraphQL divides output types into two groups: * **Composite types** — object, interface and union types. These *have* fields, so a selection over them is meaningful. * **Leaf types** — scalars (`Int`, `Float`, `String`, `Boolean`, `ID`, and any custom scalar) and enums. These have no fields at all; the value is the whole answer. The specification turns that into one validation rule with two halves, named **Leaf Field Selections**: 1. If the field's type is composite, its selection set must be present and non-empty. 2. If the field's type is a leaf, it must have no selection set. Both halves are strict. There is no “select the object and get all of its fields” shorthand — GraphQL deliberately has no `*`, because a server can only bound the work a request causes if the request says exactly what it wants. And there is no way to reach *inside* a scalar: if a custom scalar carries structured JSON, the client receives that value whole and picks it apart itself. ## Nullability and list modifiers do not change the rule A field's declared type may be wrapped: `Leg`, `Leg!`, `[Leg!]!`. Those wrappers say whether the value may be null and whether it is a list; they do not change what the value *is made of*. The selection set is written once, against the underlying named type, and the server applies it to every element of a list. A field typed `[TrackingEvent!]!` takes one selection set, not one per event — there is no syntax for asking different fields of the third element than of the first. ## Two symmetrical errors ```graphql # invalid: `code` is a String — a leaf cannot be selected into shipment(id: "BKG-40913") { legs { terminal { code { value } } } } # invalid: `terminal` is an object type — it needs a selection set shipment(id: "BKG-40913") { legs { terminal } } ``` Both of these **parse**. The grammar permits a selection set after any field, so the lexer and parser are content; it takes the schema to know that `code` is a `String` and `terminal` is an object type. That is why both are *validation* errors rather than syntax errors, and it is a distinction worth being able to state: the same document text can be valid against one schema and invalid against another, so a client cannot decide legality from the document alone. Because validation runs before execution, the whole request is rejected. Nothing resolves, and the failure is a property of the document, not of any one field's data. ## Depth is the client's choice, and that is the tradeoff Nothing in the rule caps how deep a tree may go. A schema with a cycle — a shipment has legs, a leg has a carrier, a carrier has shipments — lets a client write a legal document of essentially unbounded depth over a modest type system. Selection sets are what make GraphQL precise about what the client wants; they are also what make an unguarded endpoint easy to abuse, which is why depth and cost limiting exist as a separate concern. ## The meta-field exception that is not one `__typename` is available on every composite type and is typed `String!`. It is a leaf like any other, so it never carries a selection set — it is simply a field the schema did not have to declare. ## What to say in an interview Define the selection set as the brace-delimited request at one level; say nesting continues while the type is composite and stops at scalars and enums; state both halves of the rule; and add that neither violation is a syntax error — they are caught by validation, which needs the schema, before a single resolver runs.