What inputs does a GraphQL typed client generator need, and what does it emit?

## Why two inputs and not one It is tempting to think of a typed client generator as a schema-to-types translator, the way a tool that reads a database schema emits a row class per table. GraphQL does not work that way, and the reason is the whole point of the query language: **the server declares a graph, the client declares a slice of it.** The schema says an `Appointment` has fourteen fields. The document your screen actually sends asks for three of them. A type that carried all fourteen would be a lie — the other eleven are simply not keys in the response object. So the generator needs both halves. The schema tells it what is legal, what each field's type and nullability are, and what the enums and input objects look like. The documents tell it which of that legal surface this application asked for. Only the intersection can be typed honestly. ## The schema half The schema arrives in one of two forms. As **SDL** — a text file of type definitions, usually committed to the repository or published as a build artefact. Or as an **introspection result** — the JSON a server returns when queried through the introspection meta-fields, which a generator can fetch by pointing at a running endpoint. Both describe the same type system; they are not equally complete, and which one you feed the tool has consequences, but for the basic shape of the output either will do. ## The document half The second input is a set of executable documents: named operations and the named fragments they spread. Anonymous documents are awkward for a generator, because the operation name is what the generated type gets named after — this is why codegen setups almost always require every operation to carry a name. ## What comes out For each operation the generator emits a pair: * A **variables type**, built from the operation's variable definitions. A variable declared non-null with no default becomes a required member; a nullable variable becomes an optional one. * A **result type**, built by walking the selection set. Every selected field becomes a member; the member's name is the **response key** — the alias when one is written, otherwise the field name — and its type is the schema type of the field, recursively expanded for object-typed fields. Alongside those it emits shared declarations for the schema's enums and input object types, because those appear inside variables and results by reference rather than by selection. ```graphql query ClinicianDayView($clinicianId: ID!, $day: Date!) { clinician(id: $clinicianId) { fullName appointments(day: $day) { id startsAt patient { displayName } } } } ``` That single document produces one variables type with a required `clinicianId` and a required `day`, and one result type nested exactly three levels deep — clinician, appointments, patient — with `displayName` and nothing else under `patient`, even though the schema's `Patient` type has a dozen more fields. ## Two consequences people miss **The result type is per-operation, not per-type.** A second query that selects `patient { displayName dateOfBirth }` gets a *different*, unrelated generated shape. Some generators let a named fragment become a reusable named type, which is why fragment colocation is a common house style: it is the only way to get a shareable, non-duplicated piece of a result type. **Aliases move the key.** Writing `morning: appointments(day: $day)` renames the member in the response and therefore in the generated type. The generated code follows the document text, not the schema. ## What generation is not Generated code is a **compile-time assertion**, not a runtime guard. Nothing in it validates the bytes that come back. If the schema changed after generation — a field removed, a type narrowed — the compiler still sees the old promise and the code still compiles; you find out when a member you were told exists is missing at runtime. That gap is the whole reason a small platform team wires regeneration into the build rather than running it by hand: the artefact is only as true as the schema snapshot it was produced from. It is also not a validator of your documents. Most generators will refuse to emit code for a document the schema rejects, so in practice they catch invalid selections early — but that is a side effect of needing to resolve every field's type, not a substitute for validating the shipped documents against the schema the server is actually running.