GraphQL Union Type

How GraphQL union types work

A union type is a schema-level way to say that one field can return one of several object types. The client does not get a single fixed shape, so it must inspect the returned __typename or use type-specific fragments to interpret the result correctly. That flexibility is useful, but it also means the schema is describing polymorphic output rather than a predictable object.

In practice, unions are most useful when the domain genuinely has multiple valid result forms, such as search results, mixed activity feeds, or workflows that may yield different object classes. The important design point is that the API still presents one query path, while the response semantics vary by concrete type.

Why union types are used in GraphQL schemas

Unions help schema authors model variation without forcing unrelated fields into one oversized object. They keep the schema expressive when the server needs to return different shapes from the same resolver, and they can make clients cleaner when each result type has its own meaningful fields.

That said, unions are not a substitute for a well-designed object model. If a response always carries the same core attributes, an interface or a regular object type is often easier for clients to work with. Unions are best when the result types are genuinely distinct and the client is expected to branch on the concrete type.

Security implications of polymorphic response shapes

Polymorphic output can become a security issue when developers assume every response will expose the same fields or be processed by the same downstream logic. If a client or gateway parses union members loosely, it may mishandle unexpected fields, skip validation, or reveal type-specific data that was not intended for every consumer.

Union-driven schema design also affects authorization boundaries. A resolver that returns multiple object types must ensure each concrete type is subject to the right access checks, because a single query path can otherwise surface different privilege-sensitive records through the same endpoint. OWASP API Security Top 10 is a useful reference point for understanding how broken authorisation and API exposure risks can emerge in such designs. GraphQL Security Guide covers the GraphQL-specific controls that matter here, including resolver authorisation and schema abuse patterns.

Implementation considerations for clients and servers

On the client side, union handling should be explicit. Consumers need to branch on the concrete type and avoid assuming the presence of fields that belong only to one union member. That is especially important in strongly typed front ends, code generation pipelines, and shared component libraries where a schema change can ripple quickly.

On the server side, union resolvers should be designed so that each member type has clear ownership, validation, and authorization logic. If a union is used to expose search or discovery results, it should not become a shortcut that mixes public and restricted records under one response envelope. The safer pattern is to keep the union narrow, document the possible members clearly, and make the resolver logic unambiguous.

Related resources from NHI Mgmt Group

• GraphQL
• Why is a union type often better than forcing a shared interface for audit logging and similar cross-entity workflows?
• What breaks when TypeScript type information is lost at runtime in a union-based design?
• What is the difference between an interface and a union type in TypeScript for this kind of logging use case?