--- title: Unions description: Guide for defining Union types in Pothos --- A union lets a field return one of several object types. Unlike an [interface](./interfaces), a union has no fields of its own, and its members don't need to share any fields. ## Defining Union Types This example uses two kinds of giraffe facts. Each has a backing model and an [object reference](./objects): playground-examples/types-unions/schema.ts#definition The `types` array lists the union's object types. Pothos infers the union's backing type from these members, so `fact` in `resolveType` can have either backing shape. The `resolveType` function selects a member object type for each returned value. Here, the `factKind` property distinguishes the two shapes. It is part of the backing data, but isn't exposed as a GraphQL field. You can return an object reference or the member's GraphQL type name. You can also use registered classes or object type names declared in `SchemaTypes` in the `types` array. See the [Objects guide](./objects#different-ways-to-define-object-types) for these alternatives. ### Strict resolveType By default, `resolveType` accepts any string, and a name that isn't a member only fails at runtime. Refs that share a backing type are also the same TypeScript type, so returning `Dog` from a union of `Cat` alone type-checks when both are backed by the same model. Set `StrictResolveType: true` in `SchemaTypes` to rule both out, and give `types` as a record. `resolveType` then returns one of the record's keys, which TypeScript checks even when members share a backing type: ```ts const builder = new SchemaBuilder<{ StrictResolveType: true }>({}); const Cat = builder.objectRef('Cat'); const Dog = builder.objectRef('Dog'); builder.unionType('Pet', { types: { cat: Cat, dog: Dog }, resolveType: (pet) => pet.type, // must be 'cat' | 'dog' }); ``` Several keys can point at the same member, so the keys can match a discriminant in your data directly. With the flag on, an array of refs in `types` is a type error. An array of object type names declared in `SchemaTypes` also works, with `resolveType` returning one of those names. The dataloader plugin's `loadableUnion` is checked the same way and takes names. The record form also works without the flag. The flag doesn't change interfaces, or unions whose `resolveType` a plugin provides, such as the errors plugin's error unions. ## Using Union Types Use the union reference as a field's return type. A list can contain values for any of its members. `$inferType` gives us the union's backing type for the data array: playground-examples/types-unions/schema.ts#query ## Querying Union Types Use inline fragments to select fields from each member. Even though both types define `fact`, it must be selected through a fragment because the union itself defines no fields. You can select `__typename` directly on the union to identify each result's object type: playground-examples/types-unions/query.graphql ```json { "data": { "giraffeFacts": [ { "__typename": "GiraffeStringFact", "fact": "Each giraffe has a unique pattern of spots." }, { "__typename": "GiraffeNumericFact", "fact": "Top speed (MPH)", "value": 35 } ] } } ``` ## Other ways to resolve a union Without a `resolveType` function, GraphQL can use a `__typename` property on the returned data or an `isTypeOf` check on the member object types, just as it does for [interfaces](./interfaces#other-ways-to-resolve-an-interface). If your application uses classes, set `isTypeOf: (value) => value instanceof YourClass` on each member object type and return class instances. Registering a class does not add this check automatically. If an object defines `isTypeOf`, that check must pass even when its type was selected by `resolveType` or `__typename`.