Managing GraphQL schemas in organizations

This chapter follows Evolving a GraphQL schema.

A single repository may publish multiple GraphQL endpoints or variants of one supergraph. Governance connects schema changes to owners, consumers, and compliance requirements.

Multiple audiences

Contracts (GraphOS contracts, Hive, Cosmo variants) filter which types and fields appear per audience from one composed supergraph or subgraph set.

Schema registries and environments

A schema registry stores subgraph SDL, composition results, and changelog history:

• Apollo GraphOS — schema checks, launches, field metrics
• GraphQL Hive — open-core registry, usage reporting, CDN
• WunderGraph Cosmo — federation composition and routing

Promote schemas dev → staging → prod with the same CI gates. Drift between environments causes “works on staging” incidents when composition differs.

CI checks against real operations

Pull requests should run:

1. Schema diff against the target environment
2. Breaking change detection on registered operations (client repos, mobile bundles, partner documents)
3. Lint rules (naming, mutation payloads, max nesting) via graphql-eslint or custom rules
4. Ownership — CODEOWNERS on schema.gql or generated SDL paths

Failing a check blocks merge until consumers update or the change is reclassified as safe.

Ownership and documentation

Assign domain teams to types (@tag(name: "checkout") in federation, or internal docs). Descriptions in SDL are the first line of API documentation—keep them accurate when deprecating.

Run weekly reports of orphaned types (no client usage) to prune schema debt.

Versioning strategies

GraphQL spec discourages /v1 URLs, but organizations still choose policy:

Pick one strategy per audience. Mixing undocumented continuous change with partner contracts without registry checks creates support churn.

Next: Pitfalls when updating a GraphQL backend.