GraphQL Federation Vocabulary: Apollo Federation and Supergraph Terms

If you work on distributed GraphQL architectures, you have almost certainly encountered a dense cluster of technical terms that can feel overwhelming at first — subgraph, supergraph, entity, federation. These words carry precise meaning in the Apollo ecosystem, and using them correctly signals to your team that you understand how federated GraphQL systems are actually composed and executed. This guide unpacks the essential vocabulary for GraphQL federation, with realistic developer conversation examples to help you internalise each term in context.

Core Terms: Federation and the Graph

Federation — an architectural approach where multiple independent GraphQL services (each owning a slice of the schema) are composed into a single unified API. Rather than maintaining one monolithic GraphQL server, teams own separate services that collectively form a coherent graph.

“We moved away from the monolith six months ago. Full federation now — each domain team owns its own service, and the router stitches it all together at runtime.”

“Before you add that field, check which subgraph should own it. Federation only works when ownership boundaries are clear.”

Supergraph — the unified, composed schema that results from combining all subgraphs. From a client’s perspective, the supergraph looks like a single GraphQL API. The term also refers to the overall system: the router, the subgraphs, and the composition pipeline together.

“The client doesn’t know or care how many subgraphs exist — it just queries the supergraph.”

“Our supergraph currently spans seven subgraphs across three teams. Adding a new one requires a composition check before anything goes to production.”

Subgraph — an individual GraphQL service that contributes part of the schema to the supergraph. Each subgraph is a standalone service with its own resolvers, data sources, and deployment lifecycle.

“The Product subgraph owns everything related to catalogue and pricing. If you need to add a discount field, that PR goes to the products team.”

“We keep our subgraphs small and focused. One subgraph per bounded context — it keeps the blast radius of a breaking change manageable.”

Schema composition — the process of merging multiple subgraph schemas into a single valid supergraph schema. Composition validates that the schemas are compatible, that shared types are consistent, and that directives are applied correctly.

“Composition failed again. Looks like the User type in the auth subgraph and the accounts subgraph have conflicting field definitions.”

“We run schema composition in CI on every pull request. Catching composition errors before deployment has saved us a lot of pain.”

Directives: The Grammar of Federation

Directives are annotations that instruct the Apollo Router how to route queries, resolve references, and share data across subgraph boundaries. Understanding them is essential for debugging and designing federated schemas.

@key directive — marks a type as an entity and specifies which field or fields uniquely identify an instance of that type. The @key directive is what allows a type to be referenced and resolved across subgraph boundaries.

“You need to add @key(fields: \"id\") to the Order type before the fulfilment subgraph can extend it.”

“We use a composite key on some entities — @key(fields: \"tenantId orderId\") — because no single field is globally unique.”

@external directive — marks a field on a type that is defined and owned by another subgraph. A subgraph uses @external to declare that it knows a field exists but does not resolve it locally.

“That email field is @external in the notifications subgraph — it’s resolved by auth. We reference it only so we can use it in @requires.”

“Don’t try to add a resolver for an @external field. It’s a declaration, not an ownership claim.”

@requires directive — specifies that a resolver in one subgraph needs fields from another subgraph (typically @external fields) before it can compute its own field. The Apollo Router will fetch those dependencies first, then call the local resolver.

“The shippingCost field uses @requires(fields: \"weight dimensions\") — those come from the catalogue subgraph, and we need them before we can calculate shipping.”

“Be careful with @requires on hot paths. It adds an extra subgraph fetch, which means extra latency.”

@provides directive — tells the router that a particular query path can return certain entity fields locally, avoiding an extra fetch to the owning subgraph. It is an optimisation hint.

“We added @provides(fields: \"name\") to the order line type. Now the order subgraph can return the product name inline without a round-trip to the catalogue service.”

“Don’t overuse @provides — it means you’re duplicating data, and you have to keep it in sync.”

Execution and Planning

Entity (cross-subgraph type) — a type annotated with @key that can be referenced and resolved across subgraph boundaries. Entities are the mechanism by which federated subgraphs share and extend types without tight coupling.

“The Customer type is an entity defined in the accounts subgraph. Any other subgraph can extend it and add fields, as long as they can resolve the entity by its key.”

“If a type isn’t an entity, it can’t be referenced from another subgraph. You have to decide upfront which types need to cross boundaries.”

Reference resolver — a special resolver (typically __resolveReference in Apollo Server) that takes an entity reference (an object containing only the @key fields) and returns the full entity object. It is called by the router during query planning when a subgraph needs to resolve an entity owned elsewhere.

“The router is calling your reference resolver with just { id: '123' } — you need to look up the full object from your database and return it.”

“Reference resolvers are the glue of federation. If yours is slow or unreliable, it will cascade across any query that crosses a subgraph boundary.”

Query plan — a structured execution plan generated by the Apollo Router that describes how to break a single client query into multiple subgraph fetches, in what order, and how to merge the results. Developers can inspect query plans for debugging and performance analysis.

“Pull up the query plan for this request — I want to see whether it’s doing a sequential fetch or if it can parallelise those two subgraph calls.”

“The query plan shows four fetches for what the client thinks is a single query. That’s why the p99 latency is so high. We need to restructure the entity ownership.”

Schema Management and Tooling

Schema registry — a centralised store that tracks the published schemas of all subgraphs and the composed supergraph over time. The registry is the source of truth for schema history, change validation, and composition.

“Before you publish that schema change, check the registry for downstream impact. Three other subgraphs reference that type.”

“We enforce schema checks against the registry in CI. No schema change ships without passing a composition check and a field usage analysis.”

Apollo Studio — Apollo’s cloud platform for managing federated graphs. Studio provides the schema registry, explorer, field usage metrics, operation checks, and observability tooling for federated architectures.

“The field usage data in Studio shows that legacyAccountCode has had zero queries in 90 days. Safe to deprecate.”

“Check Studio before the incident call — it shows which operations are hitting the failing subgraph.”

Apollo Router — the high-performance, open-source runtime (written in Rust) that sits in front of all subgraphs and is responsible for query planning, subgraph fan-out, result merging, and traffic routing. Replaces the older Apollo Gateway for production supergraphs.

“We migrated from Gateway to Router last quarter. The CPU footprint is significantly smaller and the query planning is faster.”

“Router supports custom plugins via Rhai scripts and co-processor hooks. We use it to inject auth headers before each subgraph request.”

Contract schema — a filtered subset of the supergraph schema published specifically for a particular consumer audience (e.g., a public API or a partner integration). Contracts exclude types, fields, or tags not intended for that audience.

“The public contract schema strips out all the internal admin fields. Partners query against the contract, not the full supergraph.”

“We use @tag directives to mark which fields belong to which contract. That way the contract is always in sync with the schema, not maintained separately.”

How to Use These in Conversation

Architecture review: “We need to decide whether Subscription should be its own entity with a @key on subscriptionId, or whether it stays a nested type under Customer. If any other subgraph ever needs to extend it, we have to make it an entity now.”

Debugging a slow query: “The query plan is doing three sequential fetches because the @requires chain is linear. If we move the billingAddress field to the order subgraph and use @provides, we can collapse it into one fetch and cut the latency roughly in half.”

Onboarding a new team: “Your service will be a new subgraph. You will publish your schema to the registry, define @key on any types you own that other subgraphs might reference, and implement __resolveReference for each entity. The router handles everything else.”

Schema governance discussion: “Before we expose this to external partners, we should define a contract schema. Tag the internal fields with @tag(name: \"internal\") and configure a contract that excludes that tag. That way the public surface area is explicit and stable.”

Quick Reference

Term	Plain-English meaning
Federation	Architecture pattern: multiple GraphQL services composed into one unified API
Supergraph	The composed, unified schema and the overall system (router + subgraphs)
Subgraph	An individual GraphQL service contributing part of the schema
Schema composition	Merging subgraph schemas into a valid supergraph schema
Entity	A type with @key that can be referenced across subgraph boundaries
Reference resolver	Resolves a full entity from only its key fields; called by the router
Query plan	The router’s execution plan: which subgraphs to call, in what order
@key	Marks a type as an entity and defines its unique identifier
@requires	Declares that a field needs external fields resolved before it can compute
Schema registry	Centralised store of subgraph schemas and composed supergraph history
Apollo Router	Rust-based runtime that executes query plans across subgraphs
Contract schema	A filtered subset of the supergraph published for a specific audience