Why does a typed client generator inject __typename into a selection on a union?

## The shape problem Suppose a hospital appointment graph exposes a clinician's day as a mixed timeline: ```graphql union ScheduleEntry = Appointment | BlockedSlot | OnCallShift type Query { scheduleEntries(clinicianId: ID!, day: Date!): [ScheduleEntry!]! } ``` A union declares no fields. There is no field common to `Appointment`, `BlockedSlot` and `OnCallShift` that a document could select on the union directly, so the only way to ask for anything is to say *if it is this member, give me these fields*, using inline fragments: ```graphql query ClinicianTimeline($clinicianId: ID!, $day: Date!) { scheduleEntries(clinicianId: $clinicianId, day: $day) { ... on Appointment { id startsAt patient { displayName } } ... on BlockedSlot { id reason } ... on OnCallShift { id rotaCode } } } ``` At execution the server resolves the concrete type of each entry and collects only the fragments that apply. So one element of the list is `{ id, startsAt, patient }` and the next is `{ id, reason }`. There is no single object shape covering both, and — crucially — nothing in those payloads *says* which one you are holding. `reason` being absent is not proof: a nullable field can be absent for other reasons. ## What __typename gives you `__typename` is a meta-field defined by the specification. It is implicitly available on the selection set of any object, interface or union type and returns a `String!` — the name of the **concrete object type** of the value being resolved. On a union it is the exception to the no-common-fields rule: it is the one field a document may select directly on the union, without an inline fragment. That makes it the discriminant. Add it, and each element is self-describing: ```json {"__typename": "BlockedSlot", "id": "bs-4471", "reason": "Theatre list"} ``` A generator can now emit a **tagged union**: one alternative per selected member, each with its `__typename` member narrowed to that member's literal name rather than to a general string. In a host language with sum types or literal-typed discriminants, matching on that member narrows the value to exactly one alternative's fields, and the compiler can flag a branch you forgot. This is why generators add `__typename` to abstract-typed selection sets automatically. It is not a convention invented by tooling — the meta-field is specified — but *injecting it* is a tooling behaviour, and it means the document that reaches the server is not byte-identical to the document you wrote. That matters if you also hash documents for a persisted-document workflow: the hash must be computed over the transformed text the client actually sends. ## Interfaces are the same problem, mostly An interface *does* have common fields, so a selection on one can be a single flat shape when you only select interface fields. The moment you add inline fragments to reach member-specific fields, you are back to alternatives and need the same discriminant. Generators typically inject `__typename` on any abstract-typed selection set for that reason, and often on object-typed ones too, since a normalized cache wants it for identity — a separate concern from typing. ## What you get without it Drop the discriminant and a generator has one honest option: emit a single merged shape with every member's fields marked optional. Then the caller writes `if (entry.reason != null)` and hopes, exhaustiveness checking is gone, and adding a fourth member to the union silently compiles. The value of the tagged union is precisely that the fourth member breaks the build. Two smaller consequences worth naming. Selecting `__typename` costs nothing on the server — it is answered from the executor's own knowledge of the resolved type, not from a resolver — so there is no reason to strip it for performance. And the string it returns is a **type name**, not a stable identifier: renaming a type in the schema changes the discriminant value and breaks a client whose generated alternatives were pinned to the old literals, which is one more reason type renames belong in the breaking-change column.