What is GraphQL Federation?

GraphQL Federation is an approach to unifying multiple GraphQL services into a single API. Teams define subgraphs that are composed into one federated graph and served through a router.

What is the difference between Federation v1 and v2?

Federation v1 includes directives such as @extends, @external, @key, @provides, @requires, and @tag. Federation v2 adds support for directives such as @inaccessible, @override, @shareable, @authenticated, @requiresScopes, and @interfaceObject, along with resolvable key argument support and interface entity support.

Can I run v1 and v2 subgraphs in the same graph?

Yes. Cosmo Router supports Federation v1 and v2 out of the box, so teams can run mixed environments with v1 and v2 subgraphs in the same federated graph. The router handles directive compatibility and query planning across both versions.

What license is the Cosmo Router under?

The Cosmo Router is Apache 2.0 licensed, with no vendor dependency and full code transparency.

Is the router self-hostable?

Yes. Cosmo supports self-hosted deployment. You need Cosmo Control Plane access, Cloud or self-hosted, subgraphs that implement Federation v1 or v2 protocols, and router deployment infrastructure such as Docker or Kubernetes.

What is graphql-go-tools?

graphql-go-tools is the Go-based GraphQL engine that Cosmo Router is built on. It is mature and battle-tested, and serves as the foundation for Cosmo Router's federation support.

Federation v1 and v2 Support in Cosmo

The problem

Incompatible federation tooling creates fragmentation and slows migration

Teams should be able to support existing v1 schemas while adopting v2 features gradually.

Incompatible tooling blocks a unified API strategy

Organizations with existing v1 schemas cannot always migrate immediately, while new projects may need v2 features. If tooling cannot support both versions, teams can end up with fragmented graphs instead of one unified API strategy.

Migration can become a complex project

Without support for both versions, moving from Federation v1 to v2 can require a complex migration project before teams can adopt v2 features broadly.

Federation overhead creates performance concerns

Federation can introduce performance concerns from query planning overhead. Teams need a router and query planner designed for high-throughput federation scenarios.

Our solution

One router for Federation v1 and v2

Cosmo Router supports Federation v1 and v2 simultaneously. Teams can migrate at their own pace, adopt v2 features for new services, and continue running existing v1 subgraphs in one federated graph.

How it works end-to-end

Subgraph teams can define schemas using Federation v1 or v2 directives.
Cosmo supports mixed Federation v1 and v2 subgraphs in the same federated graph, including directive compatibility across both versions.
The Router fetches the latest valid router configuration from the CDN and periodically checks for updates.
The Router creates a cached query planner that serves requests across v1 and v2 subgraphs through one unified API.
When router configuration updates are available, the router reconfigures its engine on the fly for zero-downtime schema updates.

Apache 2.0 licensed router. Cloud or self-hosted control plane.

GraphQL Federation

Before & After

Before Cosmo	With Cosmo
Forced to choose v1 or v2 exclusively	Run both versions simultaneously
Complex migration projects required	Gradual migration at your own pace
Limited directive support	Full directive compatibility for Federation v1 and v2
Performance concerns with federation overhead	Highly-optimized Go-based query planner

Directive support

Federation v1 and v2 directives supported

Federation v1

@extends
@external
@key
@provides
@requires
@tag

Federation v2

@inaccessible
@override
@shareable
@authenticated
@requiresScopes
@interfaceObject

Full reference in the directives index and compatibility matrix.

Key benefits

Why teams choose Cosmo for federation

Full protocol compatibility

Compatibility

All Federation v1 directives (@extends, @external, @key, @provides, @requires, @tag) and Federation v2 directives (@inaccessible, @override, @shareable, @authenticated, @requiresScopes, @interfaceObject). Interface entity support via @key on INTERFACE (v2.3).

Zero vendor lock-in

Open source

The Cosmo Router is Apache 2.0 licensed, with full code transparency and no vendor dependency.

Enterprise performance

Performance

Built in Go on graphql-go-tools, a mature GraphQL engine. The router creates a highly optimized query planner that is cached across requests for performance.

Mixed version support

Migration

Run Federation v1 and v2 subgraphs together in the same federated graph. Teams can use the federation version that matches their expertise while maintaining one unified API for consumers.

Future-ready

Future specs

Cosmo continuously updates to support new federation specifications as they emerge. Teams can start with existing v1 schemas, adopt v2 features for new services, and migrate gradually.

How it works

From subgraph schemas to a unified API

01

v1 and v2 directives both accepted.

Subgraphs use Federation v1 or v2

Each subgraph can implement Federation v1 or v2 protocols, allowing teams to run mixed environments while migrating gradually.

02

Mixed environments supported.

Cosmo supports mixed v1 and v2 subgraphs

Cosmo supports mixed Federation v1 and v2 subgraphs in the same federated graph, with directive compatibility across both versions.

03

Cached query planner.

Router fetches router configuration from the CDN

The router fetches the latest valid router configuration from the CDN, creates a highly optimized query planner, and caches it across requests for performance.

04

Transparent to API consumers.

Query planner serves requests across v1 and v2 subgraphs

The router uses its query planner to serve requests across Federation v1 and v2 subgraphs through one unified API.

05

Reconfigures on the fly.

Zero-downtime schema updates

The router periodically checks the CDN for updates and reconfigures its engine on the fly, ensuring zero-downtime schema updates.

Use cases

Where teams use Cosmo v1 and v2 federation support

Gradual migration, greenfield deployment, or multi-team schema ownership.

Gradual v1 to v2 migration

Migration

A company has existing Federation v1 subgraphs and wants to adopt v2 features for new services without disrupting existing infrastructure. Existing v1 subgraphs keep running while new services use v2 directives. Both versions are served through one unified graph.

Greenfield federation deployment

Greenfield

A team building a new microservices architecture can use Federation v2 features from day one. Teams can define subgraphs using v2 directives like @shareable and @authenticated, then serve the federated graph with full v2 support.

Multi-team schema ownership

Multi-team

Different teams own different subgraphs and have varying levels of GraphQL expertise. Some may prefer v1 patterns. Each team can use the federation version that matches its expertise while the platform team maintains a unified API for consumers.

Good fit when

When to use Cosmo v1 and v2 federation support

You have existing Federation v1 subgraphs and want to adopt v2 features for new services without disrupting existing infrastructure.
You are building a new federated graph and want full v2 feature support from day one.
Multiple teams own subgraphs and need flexibility to use the federation version that matches their expertise.
You need an Apache 2.0 licensed router with code transparency and no vendor dependency.

Requirements

What you need to get started

Cosmo Control Plane access — use Cosmo Cloud or a self-hosted control plane. The router fetches the latest valid router configuration from the CDN.
Federation v1 or v2 subgraphs — your subgraphs must implement Federation v1 or v2 protocols.
Router deployment infrastructure — Docker, Kubernetes, or another supported deployment environment.

Start running Federation v1 and v2 together

Apache 2.0 licensed router. Go-based GraphQL engine. Full directive compatibility. Gradual migration at your own pace.

Start Free Read the Docs

Documentation

Dive deeper

Router introduction

Get started with the Cosmo Router: setup, deployment, and configuration basics.

Federation compatibility matrix

Full table of which Federation v1 and v2 features Cosmo supports.

Federation directives index

Reference for every federation directive supported across both versions.

Router configuration

Router configuration options and deployment settings.

Run Federation v1 and v2 with Cosmo Router