Type unions and interfaces in GraphQL — model polymorphic data correctly

A field can return one of several different object types (search results, notification types, media items). Representing this as a single generic type loses type safety and requires clients to check a type field manually.

Use unions for 'one of these unrelated types', interfaces for 'shared fields across related types'.

# Interface — shared shape
interface Node {
  id: ID!
}

interface Media {
  id: ID!
  url: String!
  mimeType: String!
}

type Image implements Media & Node {
  id: ID!
  url: String!
  mimeType: String!
  width: Int!
  height: Int!
}

type Video implements Media & Node {
  id: ID!
  url: String!
  mimeType: String!
  duration: Float!
}

# Union — unrelated types
union SearchResult = User | Post | Product

type Query {
  search(q: String!): [SearchResult!]!
}

# Client query with inline fragments
query Search($q: String!) {
  search(q: $q) {
    ... on User { id name }
    ... on Post { id title }
    ... on Product { id sku }
  }
}

Unions and interfaces push type discrimination into the schema where the type system enforces it. Clients get type-safe exhaustive handling. Code generators produce discriminated union TypeScript types.

Modeling heterogeneous data like search results, notification feeds, or media libraries