Skip to main content

Schema governance & CI — composition as a contract

A federated graph is a distributed system whose type system spans repositories. Governance is what keeps 30 teams from breaking each other — and it must be automated, because policy documents don't block merges.

The pipeline every subgraph PR goes through​

  1. Lint — naming conventions, nullability rules, deprecation format, banned patterns (see schema design). Machine-enforced style guides end the bikeshedding.
  2. Compose against live state — rover subgraph check (or your platform's equivalent) validates the proposed schema against the current production supergraph, not a snapshot from last week.
  3. Operation impact check — would this change break any operation seen in production traffic (or the persisted-operation registry) in the last N days? Breaking a field nobody queries is a cleanup; breaking one that 3 clients query is an incident.
  4. Supergraph SDL diff in the PR — reviewers see the composed result, where the silent composition changes hide (the silent ones).
  5. Serialized publish on merge — schema registry publish is the deploy; it must be atomic, ordered and rollbackable per subgraph.

Governance rules that earn their keep​

  • Owner approval for entity changes. Adding fields to an entity you don't own requires the owning team's review — enforced via CODEOWNERS on schema files, not tribal memory.
  • Deprecations carry a date and a destination. @deprecated(reason: "Use pricing.current. Removal 2026-Q4.") — lintable, and lint it.
  • No new value-type duplication. Shared enums/inputs come from the contracts package; hand-copied definitions are a lint error (why).
  • Breaking-change budget, not a ban. Teams get a lightweight exception path (sunset window + client sign-off) instead of learning to fear the pipeline and route around it.

The federation working group​

Ten minutes of process that saves the architecture: a rotating group (one person per few subgraphs) that owns the lint rules, arbitrates entity-ownership disputes, and reviews cross-cutting changes (new shared types, router config, directive policy). Not a committee that approves everything — a court of appeal for the 5% of changes the pipeline can't decide.

What "good" looks like​

  • A new engineer can propose a schema change and know within one CI run whether it's safe.
  • Nobody has merge rights to the supergraph — only to their subgraph; the supergraph is computed.
  • Schema history answers "when did this field change and which PR did it" in one query.
  • Removal of a zero-traffic deprecated field is a routine chore, not a cross-team negotiation.