GraphQL Schema Composition | Cosmo by WunderGraph - WunderGraph
Your subgraphs compose automatically — and protect the router when they don't
Publish a subgraph and Cosmo automatically composes the full federated graph. Errors surface before any router sees the change. Successes roll out with zero downtime.
Automatic on every publish. Full composition history. Zero-downtime router updates.
The problem
Why federated graph composition fails
Merging subgraph schemas into a single supergraph is harder than it looks. Without proper tooling, type conflicts, missing references, and federation directive issues can stay hidden until deployment.
Composition failures surface too late
Type conflicts, missing references, and broken federation references can go unnoticed until a subgraph change reaches deployment. By then, teams may already be dealing with production risk.
No clear record of what changed or who changed it
When a federated graph starts behaving unexpectedly, teams need to know what changed, when it changed, and who triggered it. Without composition history, root cause analysis gets slower.
Manual merging does not scale across teams
Maintaining a hand-merged supergraph schema breaks down as more teams publish subgraph changes. Conflicts become harder to track, and the merge process becomes a bottleneck.
Our solution
Automatic composition with complete history
Cosmo's composition engine runs on every subgraph publish. It validates the full federated graph, distributes new router configurations on success, and records every composition attempt with inputs, outputs, errors, and version history.
What happens on every publish
- A developer publishes a subgraph with
wgc subgraph publish. The publish triggers composition. - The composition engine validates the new schema against every other subgraph in the federated graph, checking for type conflicts, missing references, and federation directive compliance.
- If composition succeeds, the new router configuration is distributed through the CDN, and routers hot reload the update.
- If composition fails, the error is recorded with detailed, actionable error messages. The existing valid schema remains active.
- Each composition attempt is saved with trigger details, timestamps, inputs, outputs, errors, and resulting schema versions.
Schema composition
| Before Cosmo | With Cosmo |
|---|---|
| Manual schema merging with potential errors | Automatic composition on every publish |
| No visibility into composition history | Complete audit trail of all compositions |
| Difficult to identify what changed | Visual diff between schema versions |
| Unclear which version routers are using | Clear indication of active router configuration |
What the engine validates
- Type compatibility: conflicting definitions across subgraphs fail composition.
- Entity references: referenced entities and relationships are validated across subgraphs.
- Federation directive compliance: federation directives are checked for composition compatibility.
- Missing fields: fields or references required for composition surface before routers receive the change.
Key benefits
Ship subgraph changes without breaking the graph
Composition runs automatically on every publish
Included: No manual merging, no separate composition step. When a developer publishes a subgraph, Cosmo automatically composes it against the other subgraphs in the federated graph. The result is recorded in Studio with the composition outcome and any errors.
Failed compositions do not reach production routers
Included: When composition fails, the existing valid schema remains active. The failure is recorded with detailed, field-level error information so teams can see which types, fields, references, or federation directive compliance issues caused the conflict.
Every composition attempt is recorded
Included: The composition history tracks each attempt with trigger details, timestamps, inputs, outputs, errors, and resulting schema versions. Teams can use that history for audits, debugging, and understanding graph changes.
See exactly what each publish changed
Included: Studio shows visual diffs between schema versions, including additions, removals, and modifications. Teams can see what changed in the federated graph without manually reconstructing schema changes across services.
Routers receive successful configurations automatically
Included: When composition succeeds, the new router configuration is pushed to the CDN. Routers periodically check for updates and hot reload the new configuration, enabling zero-downtime router updates.
How schema composition works
01
Publish a subgraph
Run wgc subgraph publish to publish a subgraph schema. The publish triggers composition in the control plane.
02
Composition is attempted
The control plane validates the new schema against every other subgraph. Type conflicts, missing references, and federation directive compliance issues surface before routers receive the change.
03
Success: router configuration updates
If composition succeeds, the new router configuration is pushed to the CDN. Routers periodically check for updates and hot reload the new configuration, enabling zero-downtime updates.
04
Failure: existing valid schema stays active
If composition fails, the existing valid schema remains active. The error is logged with detailed, field-level information so the team can understand the conflict and publish a corrected schema.
05
Full audit trail, always.
Every composition attempt is recorded with trigger details, timestamps, inputs, outputs, errors, and resulting schema versions. Studio gives teams a composition history they can use for audits, debugging, and understanding graph changes.
Use cases
When teams rely on composition
Continuous schema delivery
A team publishing multiple subgraph updates a day needs each change to compose safely. Each wgc subgraph publish triggers composition with the other subgraphs in the federated graph. If composition fails, the existing valid schema remains active. If it succeeds, the new router configuration is made available to routers.
Debugging a composition failure
A new subgraph update fails to compose. The Compositions page in Studio shows detailed error messages indicating which types, fields, or federation directive compliance issues caused the conflict. Developers can review the input schemas and understand the root cause.
Compliance and audit trail
A compliance review requires documentation of schema changes over the past quarter. The Compositions page provides a complete history of composition attempts with timestamps, triggering users, and resulting schemas. Teams can compare schema versions with visual diffs.
Multi-team coordination
When multiple teams publish to the same federated graph, composition history helps show which publish triggered a composition failure. Detailed error messages and trigger tracking help teams identify what changed, who triggered it, and where to investigate.
When to use schema composition
- You are building a federated GraphQL graph with multiple subgraphs and need reliable, automatic composition.
- Multiple teams publish subgraph changes and you need shared composition history for auditing, debugging, and change tracking.
- You want failed compositions to leave the existing valid router configuration active instead of replacing it.
When not to use
- You are running a single non-federated GraphQL graph with no subgraphs to compose.
- You need pre-publish validation in CI/CD. Use Schema Checks before publishing, then rely on composition to validate published subgraph changes against the federated graph.
Start composing federated subgraphs in minutes
Free tier. No credit card. Full composition history from day one.
Ready to go deeper?
Full reference for publish commands, composition error types, Studio interface, and router version management.