Federation & Composition

Diff the API schema, because that is the only document consumers see. A subgraph SDL diff misses changes the other subgraphs decide, and a supergraph diff is full of routing churn that never reaches a client.

Decide on audience and traversal, not tidiness. One graph earns its cost only where real client operations cross domains. Separate graphs are right when audiences, cadences or trust boundaries differ, or nobody can staff the platform a shared graph needs.

Start from the hot operations, not the schema. Place a field where the traffic that matters reaches it in the fewest dependent hops, and treat ownership as a team decision with a real migration cost.

Keep it when the mapping is edited rarely by the people who own the services, when some merged schemas are not yours to change, or when you rely on gateway transforms composition cannot express. Move when it becomes a cross-team queue.

Split it by what each layer can know. A router has the credential, the document and the schema but no data, so it can only enforce coarse rules. Per-record rules must live in the subgraph or below.

Only the ones whose absence would make the rest of the response wrong or unsafe to act on. Everything else degrades to a hole. Tier the subgraphs by that test, then encode each tier in nullability, budgets and the client contract.

The GraphQL specification reserves the double-underscore prefix for the introspection system and forbids schema authors from using it. Federation is a layer built on ordinary GraphQL, so its added members take a single underscore instead — legal, and conventionally set aside for machinery.

The extend keyword marks the type as owned by another subgraph: this schema only contributes extra fields to a type it did not define, so composition treats the two declarations as one type rather than a clash.

It depends where the enum is used. Federation 2 takes the union for an enum used only in output positions, the intersection for one used only in input positions, and exact agreement when it is used both ways.

Because a list usually names the same entity many times: 143 artworks by 37 artists yield 37 distinct keys. Sending each key once cuts payload and subgraph work. It is a router optimization, not a rule the federation specification imposes.

Because the next step has to be addressable. Into each fetch the router injects __typename and the key fields of any object whose remaining fields another subgraph owns, then strips those values back out before serialising the response.

The gateway becomes a client of that service. It resolves the parent first, then builds a brand-new document against the second service using values from that parent as arguments, and grafts the result into the response tree.

When the subgraph only points at the entity and cannot look one up. It declares the identity so its own fields can reference the object, while telling composition never to route key lookups for that type here.