How does a GraphQL client tell which member of a union result type it received?

## Why a union needs a discriminator at all A union type says a field may return one of several **object types that share nothing**. There is no common field, no common interface, no structural overlap the client can lean on. So the response for a union-typed field is an object whose shape depends entirely on which member came back — and the client needs some way to know which one that was before it can render anything. GraphQL's answer is the `__typename` **meta-field**. It is available in any object, interface or union selection set, it takes no arguments, its type is `String!`, and its value is the **name of the concrete object type** of the value at that position — never the name of the union or interface. (The specification carves out one exception: `__typename` may not be included at the root of a subscription operation.) ## What you may select on a union This is the mechanic interviewers actually probe. A selection set on a union-typed field may contain **only fragments and meta-fields**. Even if every member of `ListingResult` happens to declare a `message` field, `listing { message }` is invalid — validation rejects it, because a union declares no fields of its own for a field selection to resolve against. So the shape is fixed: ```graphql query ListingDetail($id: ID!) { listing(id: $id) { __typename ... on Listing { id address askingPrice } ... on ListingWithdrawn { withdrawnAt reason } } } ``` The `... on X { ... }` form is an **inline fragment**; a named fragment with the same type condition, spread here, does the identical job and is how teams share a branch between documents. ## How the response is assembled During execution the server collects the fields to resolve for this position by walking the selection set and keeping only fragments whose **type condition matches the concrete type** of the value. Everything else contributes nothing at all — it is not an error, it simply does not appear. That gives the rule the whole answer turns on: **the response object contains exactly the keys contributed by matching fragments, plus any meta-fields selected directly.** If the value is a `ListingWithdrawn` and the document has no fragment on `ListingWithdrawn`, the object is `{"__typename": "ListingWithdrawn"}` — and if `__typename` was not selected either, it is `{}`. ```json { "data": { "listing": { "__typename": "ListingWithdrawn", "withdrawnAt": "2026-08-19T09:41:07Z", "reason": "SOLD_OFF_MARKET" } } } ``` ## The client side A client switches on the string and must have a default arm: ``` result = response.data.listing switch result.__typename: case "Listing": renderListingCard(result) case "ListingWithdrawn": renderWithdrawnNotice(result.reason) case "ListingNotFound": renderMissing(result.requestedId) default: renderGenericProblem() ``` The default is not paranoia. Adding a member to a union is a change the server can make at any time without breaking a single existing document — every old query stays valid, and every old client starts receiving objects it has no branch for. Without a default arm those requests render as blank space, and because the response is a completely successful one, nothing in the errors list and nothing in the client's generic failure handling ever fires. Typed client generators help here by turning the union into a closed set the client's own compiler checks for exhaustiveness, but only against the schema snapshot the code was generated from. ## Interfaces discriminate differently If the result is an **interface** rather than a union, the picture changes usefully. Fields the interface itself declares are selectable directly, no fragment required, so a client can write `listing { __typename ... }` and select a shared `message` field that renders correctly for every implementing type — including implementations added after the document was written. Inline fragments are then needed only for the branches you treat specially. That is the main reason a team choosing a carrier for failure types picks an interface: it converts "a member I have never heard of" from a blank screen into a generic but correct rendering. ## Common mistakes Selecting a field directly on a union and being surprised by a validation error. Expecting `__typename` to name the union. Assuming an unmatched member produces an error rather than a thin object. And treating exhaustiveness as guaranteed forever, when the server can add a member the day after your client shipped.