# Composition, checks, and registry for federated GraphQL

Automatic composition when subgraphs publish, layered schema checks before production, and a single source of truth for SDL. Contracts, feature flags, and a simple path from monograph to federation when you are ready.

Federation v1 and v2, declarative auth, and CI-native checks. Integrated with Studio and the Cosmo Router.

## What Cosmo covers

[Federated GraphQL](/content/graphql-federation/index.html) only stays healthy if composition, validation, and visibility keep pace with how fast subgraphs change. Cosmo merges subgraph schemas when you publish, records every composition outcome, and blocks changes that would break peers or active operations, before a new router config ships.

Subgraph lifecycle operations (create, publish, check, update, and delete) live in the same CLI and Studio workflows as those checks, so teams are not juggling ad-hoc scripts, mystery schema files, or unclear graph membership rules.

## Why dedicated federation tooling exists

### Why teams outgrow ad-hoc GraphQL operations

Distributed schemas, multiple subgraph owners, and production clients amplify small mistakes. Generic repos and one-off scripts do not give you composition history, traffic-aware checks, or a single registry the whole org trusts.

Teams scaling federated GraphQL tend to hit the same walls.

### Composition breaks surface too late.

Conflicts, missing references, and directive mismatches are painful when you only find them after deploy, or when a peer subgraph changes underneath you.

### Breaking changes hide in plain sight.

Static review misses what real clients still query. Without operation-aware checks, removals and type changes surprise apps that were “fine” in staging.

### Nobody agrees which SDL is “production.”

Schemas scattered across repositories go stale the moment someone copies a file. Codegen, docs, and support all drift from what routers actually serve.

### Audiences need different shapes of the same graph.

Duplicating graphs for public, partner, and internal consumers multiplies maintenance. Tag-based contracts and runtime feature subgraphs need first-class support.

Cosmo ties composition, checks, registry, and delivery workflows into one platform, with a router-ready artifact path you can self-host.

## Cosmo capabilities

01 Protocol & directives  
02 Schema lifecycle  
03 Governance & delivery  
04 Single service

[GraphQL Federation v1 & v2](/content/cosmo/federation/version-support/index.html)

Complete compatibility with both Apollo Federation v1 and v2 so you can unify microservices into one API, run mixed-version subgraphs, and migrate gradually. Built on a mature GraphQL engine implemented in Go.

## Which federation capability do you need?

| If you need to… | Start here |
| --- | --- |
| Running Federation v1 and v2 subgraphs together | [GraphQL Federation v1 & v2](/content/cosmo/federation/version-support/index.html) |
| Declaring @shareable, @authenticated, and related patterns | [Federation Directives](/content/cosmo/federation/federation-directives/index.html) |
| Registering and publishing subgraphs from CI or the terminal | [Subgraph Management](/content/cosmo/federation/subgraph-management/index.html) |
| Understanding why a composition failed after a publish | [Schema Composition](/content/cosmo/federation/schema-composition/index.html) |
| Blocking breaking changes before they hit production routers | [Schema Checks](/content/cosmo/federation/schema-checks/index.html) |
| Downloading the current supergraph or a subgraph SDL | [Schema Registry](/content/cosmo/federation/schema-registry/index.html) |
| Serve different audiences different slices of the same graph | [Schema Contracts](/content/cosmo/federation/schema-contracts/index.html) |
| Canary or segment-based schema rollout with instant rollback | [Feature Flags & Progressive Delivery](/content/cosmo/federation/feature-flags/index.html) |
| Enforce company-specific lint checks or compliance gates on every check | [Subgraph Check Extensions](/content/cosmo/federation/subgraph-check-extensions/index.html) |
| Start with one GraphQL service and migrate to federation later | [Monograph Support](/content/cosmo/federation/monograph-support/index.html) |

## How Cosmo compares

Rows summarize positioning called out across capability briefs (self-hosting, composition automation, history, checks, and subgraph membership). Not an exhaustive vendor matrix.

|  | Cosmo | Apollo Studio | DIY / scripts | Partial tooling |
| --- | --- | --- | --- | --- |
| Self-hosted Cosmo stack | Yes | No | Yes | Varies |
| Automatic composition on publish | Yes | Yes | Manual | Partial |
| Composition history & diffs | Full | Limited | None | Uncommon |
| Traffic-aware operation checks (same flow) | Yes | Yes | No | Rare |
| Label-based subgraph-to-graph matching | Yes | No (variants) | Custom | Custom |

## Federation platform use cases

### Migration

**Gradual Federation v1 to v2 migration**  
**Scenario**  
A company has many subgraphs on Federation v1 and wants v2 capabilities for new services without freezing the whole graph.  
**How Cosmo handles it**  
Teams keep v1 subgraphs unchanged while new services use v2 directives. Cosmo composes both into one graph and handles compatibility and query planning across versions.  
**Outcome**  
New capabilities ship on new services; legacy subgraphs move when they are ready, without a forced big-bang migration.

### CI/CD

**Pull request validation before merge**  
**Scenario**  
A developer removes a deprecated field and needs to know whether any real clients still request it.  
**How Cosmo handles it**  
CI runs subgraph check: composition against peers, breaking-change detection, and operation checks over recent client traffic. Failing checks show which operations would break.  
**Outcome**  
Safe merges when traffic confirms the change is clear; risky changes get flagged for review instead of surprising production.

### Governance

**Public API without internal-only fields**  
**Scenario**  
The same federated graph serves internal apps and external partners, but sensitive fields must never appear on the public surface.  
**How Cosmo handles it**  
Sensitive areas carry @tag metadata. A public contract excludes those tags and gets its own router deployment that stays synchronized when the source graph evolves.  
**Outcome**  
One graph to maintain, multiple tailored APIs. No duplicated schemas, no manual drift between the public and full SDL.

### Rollout

**Monolith to federation with production confidence**  
**Scenario**  
A team is splitting a monolithic GraphQL API into subgraphs and needs to validate behavior against real traffic before switching everyone over.  
**How Cosmo handles it**  
Feature subgraphs and shadow mode compare new implementations to the base graph; activation by claims or headers controls who sees the new composition.  
**Outcome**  
Measured migration with rollback by toggling flags, without coordinating emergency redeploys across every client.

## Why teams run Cosmo

- **Composition runs when subgraphs publish. No manual merge step.** Failed compositions stay out of router configs; successful ones are versioned with diffs and audit context.  
- **Checks combine composition, breaking changes, real traffic, and lint checks.** Operation-aware analysis means you see which clients would break, not just that a field disappeared.  
- **One registry for the supergraph and every subgraph SDL.** Copy and export for codegen and docs so local environments track production.  
- **Contracts and feature flags for different rollout models.** Tag-filtered contracts for stable audience views; feature subgraphs for gradual, reversible changes in production traffic.

## Frequently Asked Questions

### Can we run Apollo Federation v1 and v2 subgraphs in the same graph?

Yes. Cosmo supports both Federation v1 and v2 protocols out of the box. Teams can run mixed environments, migrate gradually from v1 to v2, or start fresh with v2 features. The router handles directive compatibility and query planning across both versions, so you are not forced to pick one version for the whole organization.

### What do Schema Checks validate before a publish?

### What is the difference between Schema Contracts and Feature Flags?

### When should we use a Monograph instead of a federated graph?

### What are Subgraph Check Extensions?

### Where do federation directives get enforced?

## Ship federated GraphQL with Cosmo