GraphQL Federation Vocabulary

Federation solves the "who owns the schema?" problem at organisational scale.

The monolithic GraphQL schema problem:
• A single GraphQL service starts simple but grows with every new team and feature
• All teams submit schema changes to one repository — merge conflicts, slow reviews, deployment coupling
• One team's schema breaking change can block all other teams' deployments

Federation architecture:

Client
  ↓
[Federation Gateway / Router]  ← Composes subgraphs into the supergraph
  ↓              ↓             ↓
[Users Subgraph] [Orders Subgraph] [Products Subgraph]
  (Auth team)    (Checkout team)    (Catalogue team)

Key benefits:
• Each team deploys their subgraph independently
• Schema changes are reviewed and approved per-team
• The gateway composes everything — clients see one unified API
• One subgraph going down doesn't necessarily take down the entire API

Real-world adoption:
Apollo Federation (spec + router) is the dominant implementation, used by Netflix, Expedia, Wayfair, and others with 50+ teams sharing a GraphQL API.

Key vocabulary:
• Subgraph — a team-owned GraphQL service with a partial schema and its own data sources
• Supergraph — the complete, composed GraphQL schema created by merging all subgraphs
• Federation gateway / router — the entry point that routes and composes queries across subgraphs
• Schema composition — the process of merging subgraph schemas into the supergraph

The @key directive is what makes entities "stitchable" across subgraph boundaries.

Without @key:
• Each subgraph is an isolated island — no object can span two subgraphs
• A User in the Users subgraph and a User in the Orders subgraph are unrelated types

With @key:
• @key(fields: "id") declares that User.id is the stable identifier for the entity
• Any subgraph can contribute fields to User as long as it knows the entity's key
• The gateway knows: "to fully resolve a User, I may need to call multiple subgraphs"

Query execution with federation:

query {
  user(id: "123") {     # Resolved by Users subgraph
    name                # ← Users subgraph provides this
    email               # ← Users subgraph provides this
    orders { total }    # ← Orders subgraph provides this
  }
}

The gateway's query plan:
① Fetch User { name email } from Users subgraph
② Fetch User(id: "123") { orders { total } } from Orders subgraph
③ Merge results and return to client

Key vocabulary:
• @key directive — declares the primary key used to identify an entity across subgraphs
• Entity — a type decorated with @key that can be referenced and extended across subgraphs
• Entity reference — using the @key fields to look up an entity in another subgraph
• Query plan — the gateway's execution strategy for a query (which subgraphs to call, in what order)

Understanding the schema stitching vs Federation debate is a common architectural conversation topic.

Schema Stitching (older approach):
• A central gateway manually imports schemas from multiple services
• The gateway writes type merging resolvers that know how to join types across services
• The joining logic lives in the gateway — if you add a new service, only the gateway changes
• ✅ Works with any GraphQL service (no subgraph requirements)
• ❌ The gateway becomes a bottleneck for schema changes; gateway team knows everyone else's schema
• ❌ More boilerplate; no standard tooling

Apollo Federation (modern approach):
• Subgraphs declare their own composition instructions using @key, @external, @provides directives
• The gateway is a generic router — it doesn't need to know each service's internals
• Schema changes are pushed from subgraph teams, not the gateway team
• ✅ Scales better for 10+ teams; clear ownership boundaries
• ✅ Industry-standard tooling (Apollo Studio, schema checks, composition validation)
• ❌ Requires services to implement the Federation spec

When to choose each:
• Small team, few services, want flexibility → schema stitching
• Multiple teams, need clear ownership, long-term scalability → Apollo Federation

Key vocabulary:
• Schema stitching — manual approach to combining GraphQL schemas at the gateway
• Type merging — schema stitching's mechanism for combining types from multiple schemas
• @external directive — Federation directive indicating a field is defined in another subgraph
• @provides directive — Federation directive indicating fields a subgraph can provide as part of query planning

Entity extension is one of Apollo Federation's most powerful features.

Products subgraph defines the entity:

# Products subgraph — entity owner
type Product @key(fields: "id") {
  id: ID!
  name: String!
  price: Float!
}

Reviews subgraph extends the entity:

# Reviews subgraph — entity extender
type Product @key(fields: "id") {
  id: ID!              # Required to identify the entity
  averageRating: Float!  # New field owned by Reviews subgraph
}

# Resolver in Reviews subgraph
Product: {
  averageRating: ({ id }, _, { db }) =>
    db.reviews.getAverageRating(productId: id)
}

What happens when a client queries:

query {
  product(id: "42") {
    name          # ← Products subgraph
    price         # ← Products subgraph
    averageRating # ← Reviews subgraph
  }
}

The gateway's query plan calls both subgraphs and merges the response.

Key vocabulary:
• Entity extension — a subgraph adding fields to an entity originally defined in another subgraph
• Stub entity (reference resolver) — the minimal entity definition (just the @key fields) in an extending subgraph
• Reference resolver — the Federation-specific resolver that loads an entity by its key (used when the gateway needs to resolve extension fields)

Understanding representations and query plans is essential for debugging federated APIs.

How Federation resolves cross-subgraph queries:
① Client sends query to the router
② Router generates a query plan — a directed execution graph of subgraph calls
③ For each entity extension, the router sends a _entities query to the extending subgraph
④ The _entities query includes representations — minimal objects with just the @key fields

Example representation for Product:

// What the router sends to the Reviews subgraph:
{
  _representations: [
    { __typename: "Product", id: "42" }
    //              ↑                 ↑
    //  Required type name     The @key field value
  ]
}
// If id is missing, the Reviews subgraph can't look up the product

Common causes of this bug:
• The Products subgraph resolver doesn't include id in its return value (so the router has nothing to put in the representation)
• The Products subgraph schema has id as nullable (ID instead of ID!) — null id → empty representation
• A query plan caching bug — the router uses an outdated plan from before the entity was added

Debugging approach:
① Enable Apollo Router's query plan logging to inspect the representation
② Check the Products subgraph resolver returns a non-null id
③ Validate schema composition in Apollo Studio

Key vocabulary:
• Representation — the minimal JSON object containing __typename and @key fields sent to an extending subgraph
• Query plan — the router's optimised execution plan for a federated query
• _entities query — the internal GraphQL query the router uses to fetch extension fields from a subgraph
• Partial response — a GraphQL response where some fields are null due to resolver or network failures