English for GraphQL Federation

Splitting one giant GraphQL schema across teams sounds simple until someone asks “which service actually owns this field,” and federation’s vocabulary — subgraphs, entities, the gateway — is exactly the language that answers that question precisely instead of vaguely.

Key Vocabulary

Subgraph — an individual GraphQL service owned by one team, exposing part of the overall schema, that gets composed with other subgraphs into a single unified graph. “The orders subgraph owns the Order type entirely, while the shipping subgraph only extends it with a trackingStatus field.”

Supergraph — the single composed schema produced by combining all subgraphs, representing what clients actually query against, even though no single service implements all of it. “Clients only ever see the supergraph — they have no idea that a query touches four different subgraphs behind the scenes.”

Gateway — the router that receives incoming GraphQL queries against the supergraph, breaks them into sub-queries for the relevant subgraphs, and stitches the results back into one response. “The gateway split that single query into three requests — one to the users subgraph, one to orders, and one to inventory — then merged the results before returning them.”

Entity — a type that spans multiple subgraphs, where one subgraph defines the type’s primary fields and other subgraphs contribute additional fields by referencing it via a key. “Product is an entity — the catalog subgraph owns the core fields like name and price, and the reviews subgraph extends it with an averageRating field, keyed by the product ID.”

Key directive — the schema annotation (@key(fields: "id")) that tells the gateway how to uniquely identify an entity across subgraphs, so it can join data contributed from different services. “We added a @key(fields: "id") directive on Product in the reviews subgraph so the gateway knows how to match reviews back to the right product from the catalog subgraph.”

Common Phrases

• “Which subgraph actually owns this field?”
• “Is this type an entity, or does it only exist in one subgraph?”
• “The gateway is timing out — is that one slow subgraph, or a composition issue?”
• “Did we add the key directive so the gateway can resolve this entity across services?”
• “Does the supergraph schema compose cleanly, or are there conflicting field definitions?”

Example Sentences

Explaining ownership boundaries in a design doc: “We’re splitting the monolithic schema into subgraphs along team boundaries — the orders team owns the Order entity’s core fields, and any team that needs to extend it adds fields in their own subgraph using the key directive.”

Debugging a slow federated query:
“The gateway is fanning this query out to five subgraphs when it only needs two — the composition is including an entity extension that isn’t actually being requested.”

Reviewing a schema composition failure: “The supergraph failed to compose because two subgraphs both declared a non-nullable status field on the same entity with different types — one of them needs to change before this can deploy.”

Professional Tips

• Name the specific subgraph that owns a field when discussing ownership or debugging — “who owns this” is one of the most common questions in a federated architecture and deserves a precise answer.
• Distinguish an entity from an ordinary type explicitly — only entities need a key directive, and treating every type as one adds unnecessary complexity.
• Explain gateway fan-out behavior when a federated query is slow — the number of subgraphs touched, not query complexity alone, often explains the latency.
• Flag composition failures as schema-level, not runtime, issues in incident write-ups — a broken supergraph composition blocks deployment before any query ever runs.

Practice Exercise

1. Write a sentence explaining the difference between a subgraph and the supergraph.
2. Explain what the key directive does for an entity.
3. Describe what the gateway does when it receives a query that spans multiple subgraphs.