GraphQL Federation v2: Patterns That Survive Team Growth
Digital Engineering
Federation v2 changed the contract between teams. We have shipped it on three large client codebases and the patterns that prevent breaking changes are not the ones in the docs. Here is what works.
By Arjun Raghavan, Security & Systems Lead, BIPI · July 10, 2024 · 7 min read
Federation v1 was a clever hack. Federation v2 is a contract. The shift matters because v1 let teams paper over schema design problems with @key directives and clever resolvers. v2 forces you to think about ownership, value types, and what a shared concept actually means across team boundaries. The teams that succeed treat schema design as a product, not a side effect of code.
We have rolled federation v2 onto three large client codebases (one e-commerce, one fintech, one media). The pattern of what works has converged. The pattern of what breaks has also converged.
Subgraph design starts with ownership, not entities
The most common failure mode: teams design subgraphs around their database tables. They end up with a User subgraph owned by the auth team, a UserProfile subgraph owned by the profile team, and a UserPreferences subgraph owned by the personalization team. Now every product change touches three subgraphs and three teams.
The pattern that works: design subgraphs around capabilities, not entities. A Catalog subgraph owns everything about a product as it appears in the catalog. A Pricing subgraph owns price calculation. An Inventory subgraph owns stock levels. The Product type is shared across them through @key, but the resolution is split by what each team actually owns.
Value types and shareable: the v2 win
@shareable is the directive that makes federation v2 actually work. It lets you declare that a field can be resolved by multiple subgraphs without forcing a single owner. Sounds dangerous; in practice it is the cleanest way to handle metadata that legitimately lives in multiple places.
The example we keep coming back to: a Product type with a 'name' field. The catalog subgraph has it. The order-history subgraph also has it (because orders cache the name at the time of purchase). With @shareable, both subgraphs can resolve it. The router picks the closest source. Without @shareable, you would either force a federation call from order-history to catalog (slow, fragile) or duplicate the type in a different shape (confusing for clients).
Schema review is where the work actually happens
Federation does not protect you from breaking changes. It just makes them explicit. A subgraph deploys a schema that removes a field, the supergraph composition fails, and now your deploy pipeline is blocking everyone. We have seen this take down deploys for half a day on a client with 14 subgraphs.
The schema review process that survives team growth:
- Every schema change opens a PR against a separate schema-changes repo
- Composition is checked in CI on every PR (rover subgraph check)
- Breaking changes require explicit @deprecated for at least 30 days before removal
- A weekly cross-team schema review reviews all proposed @key changes and entity additions
- The supergraph schema is a build artifact published with versioned tags, not a live merge
Operational lessons learned the hard way
Things we wish we had known on the first rollout:
- Query planning is expensive. Cache the query plan, not just the response
- Subgraph timeouts cascade. A 5-second subgraph turns into a 5-second supergraph response. Set explicit per-subgraph timeouts at the router
- Tracing must propagate through the router. Apollo Router supports OpenTelemetry; use it from day one
- Persistent queries are not optional at scale. They cut router CPU by 60-80 percent
- Authorization at the supergraph layer is a trap. Authorize in subgraphs where the data lives
When not to use federation
Federation has a fixed cost: a router, query planning, schema composition CI, cross-team schema review. If you have under five teams and one or two subgraphs would cover everything, monolithic GraphQL is faster to ship and faster to debug. We have helped two clients un-federate when the team size did not justify the overhead. There is no shame in that move; the federation tax is real and growing.
The teams that succeed with federation v2 treat the schema as the contract, not the code. The teams that fail treat federation as a way to deploy independently without coordinating. The directives in v2 are good. The discipline they require is what actually matters.
Read more field notes, explore our services, or get in touch at info@bipi.in. Privacy Policy · Terms.