Which federation schema do you diff for client-breaking changes before a subgraph deploys?

## Three diffs, three different questions Every federated change produces three documents that could be diffed, and each diff answers a different question. Picking the wrong one is how a "purely additive" subgraph change reaches production and breaks a client. The pedigree graph's `Animal` is a 37-field type assembled from three subgraphs. Suppose the breeding team ships a change. What do you compare? ### The subgraph SDL diff answers: what did this team intend? Useful for review, useless as a safety gate, because a subgraph's SDL is only one input to the merge. Changes that look identical here have opposite consequences: * Removing a field that **another** subgraph also declares as shareable removes nothing from the API schema. * Removing a field that another subgraph `@requires` does not break clients at all — it breaks *composition*, and nothing ships. * Adding `@inaccessible` to an existing field is a one-line addition here and a **field removal** in the API schema. The subgraph diff cannot distinguish those, because the answer depends on documents the diff never looked at. ### The supergraph diff answers: what changed for the router? This is a strict superset of what changed for clients — every API-schema change shows up here, plus a great deal that never reaches a client. A subgraph URL moving, a field's ownership moving between subgraphs, a new subgraph declaring an existing value type, a composition run under a newer join version: all rewrite the supergraph and change nothing a client can observe. Gating on this diff means alerting on changes that are, by construction, invisible outside the platform. ### The API schema diff answers: what changed for consumers? This is the contract. Recompose with the candidate subgraph, derive the API schema, and diff it against the API schema currently published. The classes that matter are ordinary GraphQL breaking changes, not federation ones: * a type, field, enum value or argument removed; * an output field's type made nullable, or narrowed to something a client's existing selection cannot handle; * an argument or input field made non-null, or a new required argument added; * a member removed from a union, or an interface no longer implemented. Because the API schema is derived from the whole graph, this diff catches the `@inaccessible` case and the shareable-field case that the subgraph diff missed, and it stays quiet about routing churn that the supergraph diff would have shouted about. ## The check that comes before the diff Composition itself is the first gate, and it fails closed: if the candidate subgraph does not compose with its siblings, there is no new API schema to diff and nothing deploys. A composition failure is a broken build, not a client incident — a distinction worth making explicitly in an interview, because it separates "everyone's deploys are blocked" from "someone's app crashed". ## The check that comes after the diff A breaking change in the abstract is only an incident if something selects the removed element. With 37 fields on `Animal`, most of them have a handful of consumers and some have none. So the diff feeds a second question: over a window at least as long as the slowest client's refresh cycle, did any recorded operation select this field? That needs either a registry of the operations clients are allowed to send, or field-usage telemetry from the router. Without one of them, the only safe policy is never to remove anything, which is how a graph accumulates dead fields. Deprecation is the mechanism that makes the window work: mark, publish, watch usage fall, then remove. The deprecation reason is part of the API schema, so it is visible in exactly the document consumers introspect. ## The trap: identical API schema, different behaviour The most instructive failure on this leaf is the one where every check passes. Move a field's ownership from one subgraph to another and the API schema is byte-identical — same fields, same types, same nullability. But the query plan is not: the field now comes from a different service, possibly a fetch deeper in the plan, possibly one that must wait on a key fetch that used to be unnecessary. That is how you get a pedigree query that times out only in production. Staging has a few thousand animals and every fetch is fast; production has the real herd book, the new owning subgraph's fetch sits behind another one, and a document that used to complete comfortably now exceeds the client's timeout. The schema diff was empty. The supergraph diff — the one you were tempted to ignore as noise — was the only artefact that showed the change at all. So the honest answer to "which schema do you diff" has two halves: **the API schema is the contract, and the supergraph is the changelog.** Diff the first to decide whether consumers are affected; read the second to explain a latency regression that the first swears did not happen.