Interfaces and Unions for Polymorphism

Shared Fields vs Shared Label

A catalog search returns three kinds of hit: products, articles, and vendor pages. Two questions decide the abstraction.

Do the types share fields the client should read without asking which type it got? Then an interface. Do they share nothing but the fact that they are all results? Then a union.

interface SearchResult {
  id: ID!
  title: String!
}

type Product implements SearchResult {
  id: ID!
  title: String!
  price: Money!
  sku: String!
}

type Article implements SearchResult {
  id: ID!
  title: String!
  author: Author!
  publishedAt: DateTime!
}

type VendorPage implements SearchResult {
  id: ID!
  title: String!
  domain: String!
}

union SearchHit = Product | Article | VendorPage

The difference shows up in the query:

# interface: shared fields need no fragment
query Featured {
  featured { id title }
}

# union: every selection needs a type condition
query Search($q: String!) {
  search(q: $q) {
    results {
      __typename
      ... on Product   { id title price }
      ... on Article   { id title author { name } }
      ... on VendorPage { id title domain }
    }
  }
}

__typename in the union query is not decoration — it is how the client knows which branch arrived before it decides how to render. Choosing wrong is cheap in one direction: a union later grows an interface when shared fields appear, but moving from an interface to a union forces every client to rewrite selections, because fields that used to be readable now need fragments.

Implementing, Querying, and Resolving

What the schema enforces

interface Node { id: ID! }
interface Timed { createdAt: DateTime! }

type Product implements Node & Timed {
  id: ID!
  createdAt: DateTime!
  price: Money!     # extra fields are allowed and expected
}

type Article implements Node & Timed {
  id: ID!
  createdAt: DateTime!
  body: String!
}

Two rules have teeth:

1. Every implementing type declares every interface field with a compatible type. Leave createdAt off Article and the schema fails to build: "Type Article must declare field createdAt." Extra fields beyond the interface are where type-specific data lives, so the contract is a floor, not a ceiling.
2. A type may implement multiple interfaces, provided no two of them declare the same field with conflicting types. implements Node & Timed composes behavior across domains; conflicting definitions fail validation instead of silently shadowing each other.

Picking the runtime type

An abstract field arrives at the resolver as a plain object with no GraphQL type attached, so something must say which member it is:

const resolvers = {
  SearchResult: {
    __resolveType: (obj) => obj.__typename, // stamped where the data loads
  },
  SearchHit: {
    __resolveType: (obj) => {
      if (obj.sku) return 'Product';
      if (obj.authorId) return 'Article';
      return 'VendorPage';
    },
  },
};

Stamping __typename during load beats property-based inference: one missed branch in the inference becomes a runtime error that surfaces only for the rare object shape — "Abstract type SearchResult must resolve to an Object type at runtime." Returning null or a name that is not a member fails execution for that response, so a test that walks every member of possibleTypes and asserts resolution pays for itself immediately.

Abstract types also interact with nullability. If a member type omits a non-null interface field at runtime — the database returned null for title — the error propagates according to the same null-propagation rules a query follows, which is worth checking when interface fields are non-null and member data comes from joins.

Evolving Abstract Types Without Breaking Clients

Interfaces and unions evolve differently, and clients break differently for each.

Adding a field to an interface. Every implementer must gain it in the same release or the schema will not build — an internal failure you catch in CI, never a client-facing one. Clients see an additive change. The cost is coordinated edits across every implementing type and its resolvers, which is why interfaces should stay small: Node with an id is cheap to implement, a five-field interface taxes every new type.

Adding a member to a union. The schema builds fine, but a client that enumerates members with inline fragments silently drops the new type: the object arrives, no fragment matches, and a hole appears in the UI. The resilient client pattern handles __typename first and treats anything unknown as generic:

switch (hit.__typename) {
  case 'Product':  return renderProduct(hit);
  case 'Article':  return renderArticle(hit);
  default:         return renderGeneric(hit); // survives members added later
}

Removing a member or a shared field breaks clients both ways and needs the runway in deprecation strategy.

The choice is reversible in one direction

Moving from a union to an interface is smooth: introduce the interface, add implements to each member, and existing fragments keep matching because union fragments are still legal on the new shape. Moving from an interface to a union forces every client to rewrite selections, because fields that were readable directly now need type conditions. If the types may converge on a shape, start with the interface; if they are genuinely unrelated results, a union costs clients less to read.

What tooling needs

Apollo and similar clients fetch __schema { types { possibleTypes { name } } } once at startup to know which fragments are legal on which abstract field — that is how a client-side cache normalizes ... on Product into the right normalized entry. Designing with possibleTypes in mind — every union member covered by some fragment, shared fields read through the interface — keeps both the cache and the rendered UI correct as the graph grows.