How does a typed client generator map GraphQL nullability onto generated types?

## The modifiers, read one at a time Every GraphQL type reference is a base type wrapped in zero or more modifiers: `!` for non-null and `[ ]` for list. Nullable is the **default**, which is the opposite of most host languages' defaults and the source of most of the surprise. A generator walks the wrapper outward and emits one decision per layer. Take a hospital appointment graph: ```graphql type Appointment { id: ID! startsAt: DateTime! cancelledAt: DateTime attendees: [Attendee!]! notes: [Note] } ``` A generator reads that as: `id` required; `startsAt` required; `cancelledAt` optional; `attendees` a required list of required items; `notes` an optional list whose items may individually be null. Four distinct shapes from two modifiers, and candidates routinely collapse the last two into "a list of notes". The distinction is not pedantry. `[Note]` means an item can be null, and the only ordinary way that happens is a **field error on an item**: a resolver for one element failed, that element is nullable, so a hole is punched at that index and the rest of the list survives. If the item type were `[Note!]` the same failure would null the whole list instead. The generated types differ accordingly — in one case you iterate over optional items, in the other you do not — and that difference is exactly the schema author's decision about how much of the payload one bad row is allowed to take with it. ## The variables side Variables follow the same modifiers with one extra rule: a **default value** changes the requirement. A variable declared `$day: Date!` with no default must be supplied, and a generator makes it a required argument. A variable declared `$day: Date! = "2026-09-03"` may be omitted, so it becomes optional in the generated signature even though its type is non-null. A nullable variable is optional regardless. There is a subtlety most generated code cannot express: for a nullable input, **omitting** a field and **passing an explicit null** are different requests. Omission means "say nothing about this"; explicit null means "set it to nothing". Servers that implement partial updates rely on the distinction, and a host language whose optional type has a single absent value flattens the two together. Teams that need both usually reach for a sentinel wrapper or hand-write that one call. ## Where the required member stops being true A required generated member says: **if this execution succeeded, this key is present and not null.** It does not say the key is always present. Two things break the promise. First, error propagation. If a resolver for a non-null field raises, the executor cannot write null into a non-null position, so it nulls the **nearest nullable ancestor** and records the failure under `errors` with a path. If every ancestor up the chain is also non-null, the null reaches the root and `data` itself is null. So a document whose generated result type declares `appointment.clinician.fullName` as a required string can still yield: ```json { "data": { "appointment": null }, "errors": [ { "message": "Clinician directory unavailable", "path": ["appointment", "clinician", "fullName"] } ] } ``` The response arrives half-empty and everything the generated type promised below `appointment` is gone. This is why generators type `data` as optional and why treating a required member as a guarantee — dereferencing without checking the ancestor — is the single most common way generated clients crash in production. Second, incremental delivery. When a document uses deferred or streamed delivery, part of the payload arrives later, so a field that will eventually be present is absent in the first chunk. Generators that support it model those branches as separately-arriving pieces rather than as members of one flat object. ## What this means when you review a schema Because the mapping is mechanical, nullability decisions in the schema are decisions about the ergonomics of every generated client. Marking a field non-null makes it pleasant to consume and enlarges the blast radius of its failure; marking it nullable pushes an optional into every caller forever. A small platform team feels this immediately: one over-eager `!` on a field backed by a flaky directory service turns every transient failure into a null parent, and one timid nullable on a field that is genuinely always present adds a check to dozens of call sites. The generated code is the mirror in which those choices become visible.