Cosmo

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.

Overview

What Cosmo covers

Federated GraphQL 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

GraphQL Federation v1 & v2

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.

Free / Pro / Enterprise

Federation Directives

Full directive support for entity relationships, field sharing, visibility, and declarative authorization. No workarounds or custom middleware for patterns the spec already covers.

Free / Pro / Enterprise

Which federation capability do you need?

If you need to…Start here
Running Federation v1 and v2 subgraphs togetherGraphQL Federation v1 & v2
Declaring @shareable, @authenticated, and related patternsFederation Directives
Registering and publishing subgraphs from CI or the terminalSubgraph Management
Understanding why a composition failed after a publishSchema Composition
Blocking breaking changes before they hit production routersSchema Checks
Downloading the current supergraph or a subgraph SDLSchema Registry
Serve different audiences different slices of the same graphSchema Contracts
Canary or segment-based schema rollout with instant rollbackFeature Flags & Progressive Delivery
Enforce company-specific lint checks or compliance gates on every checkSubgraph Check Extensions
Start with one GraphQL service and migrate to federation laterMonograph Support

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.

CosmoApollo StudioDIY / scriptsPartial tooling
Self-hosted Cosmo stackYesNoYesVaries
Automatic composition on publishYesYesManualPartial
Composition history & diffsFullLimitedNoneUncommon
Traffic-aware operation checks (same flow)YesYesNoRare
Label-based subgraph-to-graph matchingYesNo (variants)CustomCustom
Use cases

Federation platform use cases

Scenarios drawn from Cosmo capability briefs: migration, CI safety, multi-audience schemas, and progressive delivery.

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.
Questions & Answers

Frequently Asked Questions

Federation versions, schema checks, contracts versus feature flags, monographs, custom check extensions, and directive behavior.

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. See GraphQL Federation v1 & v2 for protocol support and migration paths.

Get started

Ship federated GraphQL with Cosmo