.osano-cm-dialog--type_box {
  border-radius: 0.375rem;
  --box-shadow: 0 10px 15px -3px rgb(248 248 251 / 0.3),
    0 4px 6px -4px rgb(248 248 251 / 0.3);

  -webkit-box-shadow: var(--box-shadow);
  -moz-box-shadow: var(--box-shadow);
  box-shadow: var(--box-shadow);
}

.osano-cm-info {
  --box-shadow: 0 10px 15px -3px rgb(248 248 251 / 0.3),
    0 4px 6px -4px rgb(248 248 251 / 0.3);

  -webkit-box-shadow: var(--box-shadow);
  -moz-box-shadow: var(--box-shadow);
  box-shadow: var(--box-shadow);
}


.osano-cm-widget:focus {
    outline: none;
}

Documentation for Open Federation Directives.

Overview

Directives

WunderGraph

WunderGraph Cosmo is the Full Lifecycle GraphQL API Management Solution to manage Federated Graphs at scale. Composition checks, routing, analytics, and distributed tracing all in one platform.

WunderGraph Cosmo

High-level architecture of the Cosmo Platform

Architecture

Learn more about why Cosmo is the ideal GraphQL Federation solution for Enterprise

Enterprise

Cosmo, with SOC 2 Type II certification and enterprise-grade access controls, ensures security, privacy, and compliance by design.

Security & Compliance

Learn more about how to self-host Cosmo on your own Infra using Docker, Kubernetes, VMs, or Bare Metal.

Self Hosting

Tutorial

This guide offers a hands-on introduction to Cosmo using a sample demo repository. You'll set up the demo subgraphs and Cosmo Router locally, allowing you to start querying right away.

From Zero to Federation in 5 Steps using Cosmo

A Step-by-Step Guide to Running and Enhancing Your Federated Graph for Rapid Development.

Mastering Local Development for GraphQL Federation

How to compose a federated graph with WunderGraph Schema Composition, a TypeScript composition library.

Composing Graphs

Let us go over how to use the subgraph check command in CI to prevent breaking changes in production. Use our GitHub app to seamlessly approve breaking changes in the Cosmo Studio.

PR Based Workflow for Federation

How to setup OTEL instrumentation on subgraphs.

OTEL Instrumentation on Subgraphs

Learn how to leverage Persisted Operations / Persisted Queries / Trusted Documents with Cosmo & Cosmo Router

Using Persisted Operations with Federated GraphQL

The easiest way to migrate away from Apollo GraphOS

Using Apollo Router / Gateway with Cosmo OSS Schema Registry

Setup github actions for supergraph previews.

Supergraph Previews for every Pull Request

An example of how feature flags could be used to release an experimental feature to a subset of a federated graph's consumers.

Gradual and Experimental Feature Rollout with Feature Flags

Learn how to deploy your first federated graph and integrate it with your Cosmo Router.

Cosmo Cloud Onboarding

Switch from Apollo to Cosmo

Proposals allow you to introduce changes to your federated graph in a structured way.

Proposals

An overview of feature subgraphs, feature flags, and implementing your first feature flag.

Feature Flags

Namespaces allow you to group and/or isolate different instances of the same federated graph.

Namespaces

Empower yourself as a developer by leveraging the simplicity and efficiency of WunderGraph Cosmo Schema Contracts. Schema Contracts allow you to build versatile, multi-audience graphs, simplifying development and ensuring the maintainability of your graph.

Schema Contracts

The Cache Warmer is an optimization feature designed to enhance GraphQL Federation performance by precomputing query plans and storing them in the cache. This proactive caching mechanism reduces latency spikes caused by cold starts and ensures that high-traffic applications can handle demand surges without performance degradation.

Cache Warmer

This page provides an overview on router compatibility versions.

Router Compatibility Versions

The following list gives you an Overview of the compatibility between Cosmo and other Federation Implementations.

Federation Compatibility Matrix

An index of directives supported by WunderGraph Cosmo.

Federation Directives Reference

@shareable is a federation V2-only directive. Examples and usages are outlined herein.

@shareable

The @authenticated directive declares a GraphQL definition to require the agent (person, service, or device) to be authenticated. Lack of authentication will yield an authorization error.

@authenticated

The @requiresScopes directive declares a GraphQL definition to require the agent (person, service, or device) to possess certain permissions. Lack of permissions will yield an authorization error.

@requiresScopes

@openfed__subscriptionFilter is an Open Federation directive used to filter subscription events based on filter predicates.

@openfed subscriptionFilter

The @openfed__configureDescription directive allows granular control over descriptions. It is not considered to be a V2-only directive.

@openfed configureDescription

Event-Driven Federated Subscriptions

NATS

Kafka

The Event-Driven Graph (or EDG) is an "abstract" subgraph, so it must not define any resolvers. EDGs are also subject to special compositional rules.

Composition Rules

The cosmo CLI tool: wgc. Used to manage the cosmo platform e.g. pushing schema, checking schemas, creating new projects, managing users, etc. It interacts with the control plane.

Cosmo CLI

Please read through this to have a better understanding of the nuances that take place when executing commands which we will cover in the upcoming pages.

Essentials

API Keys are required to perform any of the **wgc** CLI commands. To create an API key, follow the steps shown [here](/studio/api-keys).

API Keys

Commands to manage namespaces within the organization

Namespace

Creates a namespace for the organization on the control plane

Create

Delete

Rename an existing namespace within the organization

Rename

List all namespaces within the organization

List

Subgraphs are the building blocks of a federated graph. Each subgraph in a Federated GrapQL Architecture is responsible for defining its own part of the schema and handling the corresponding queries.

Subgraph

Creates a federated subgraph on the control plane.

Publishes a subgraph on the control plane. Optionally, you can publish and create a subgraph in one step.

Publish

Checks for breaking changes and composition errors for all the connected federated graphs.

Check

Updates subgraph metadata like URL, labels on the control plane.

Update

Deletes a subgraph on the control plane. The subgraph will be deleted from all federated graphs.

Fetches the latest published SDL of a subgraph. If the federated graph is specified, the latest successfully composed version of the subgraph will be fetched.

Fetch

Move a subgraph into a different namespace

Move

Introspect

Checks for composition errors across all connected federated graphs and tries to fix them through OpenAI integration.

A federated graph refers to a single, unified data graph that is composed of multiple subgraphs.

Federated Graph

Creates a federated graph on the control plane.

Checks for composition errors and presents a list of subgraphs that constitute the new federated graph.

Updates a federated graph on the control plane.

Deletes a federated graph on the control plane.

Fetches the latest valid SDL of a federated graph and all its subgraphs and the latest valid router config of a federated graph.

Fetches the latest valid SDL of a federated graph. The output can be piped to a file. This is primarily used for debugging purposes

Fetch-Schema

Retrieves the changelog for a federated graph

Changelog

A monograph refers to a graph with GraphQL Federation disabled and is limited to a single subgraph.

Monograph

Creates a monograph on the control plane.

Publishes a monograph on the control plane.

Updates monograph metadata like URL, subscription configuration and more on the control plane.

Checks for breaking changes and composition errors in the proposed schema for the monograph.

Deletes a monograph on the control plane.

Moves the monograph from one namespace to another.

Fetches the latest valid SDL of a monograph. The output can be piped to a file. This is primarily used for debugging purposes

Fetch Schema

Converts the monograph into a federated graph. Once done you can update label matchers and labels to compose with more graphs in your organization.

Migrate

Router

Fetches the latest valid router execution config of a federated graph.

Compose generates the router execution config locally from your subgraphs. The config can be used to start your router with a pre-built router config.

Compose

Download-binary directly downloads the latest router executable of the appropriate architecture for your system.

Download Binary

Auth

Login a user into the Cosmo platform. Supports browser-based authentication.

Login

Displays the identity currently authenticated and in use.

Whoami

Logout

Operations

Push persisted operations to your routers

Push

Schema contracts helps you provide filtered out versions of your composed graph to different customers.

Creates a contract from a federated graph or monograph.

This command updates the tag filters for the contract. To update other aspects of the contract graph please use the federated-graph or monograph update commands.

Delete, List, Fetch And More

An overview of feature-subgraph (alias "fs") commands.

Feature Subgraph

Create Feature Subgraph

Publish Feature Subgraph

Update Feature Subgraph

Delete Feature Subgraph

An overview of feature-flag (alias "ff") commands.

Create Feature Flag

Disable Feature Flag

Enable Feature Flag

Update Feature Flag

Delete Feature Flag

The Cosmo MCP Server allows developers to integrate Cosmo into their modern LLM/AI supported IDEs.

Cosmo MCP Server

Proposal

Creates a proposal for a federated graph.

Updates an existing proposal for a federated graph.

Studio is your copilot to execute and maintain GraphQL Federated Architectures.

Cosmo Studio

This page provides top level information about your federated graph at a glance.

Overview Page

An interactive explorer to navigate though your federated graph schema. It has built in search and usage tracking for every type in your schema

Schema Explorer

This page presents the current state of your federated graph's schema and the schema of all its subgraphs.

Schema Registry

Validate schema changes before deploying them to production. Ship breaking changes safely through operation checks.

Schema Checks

Schema Contracts enable you to build a multi-purpose, multi-audience graph, which can be split into subsets for different use cases. This simplifies development and keeps your graph maintainable.

Override the result of breaking changes in schema checks for individual operations which you deem are safe. Overrides are active across all graphs in a namespace.

Overrides

This page provides you with a detailed history of all schema changes made to your federated graph, including both additions and deletions.

Enhanced GraphiQL with Advanced Request Tracing to test and optimize your queries

Playground++

Run scripts before or after executing operations in the playground for authentication, validation and other workflows

Custom Scripts

You can now share your Cosmo Playground session with others using a single URL. This feature enables easier collaboration and debugging across your team — no need to copy and paste queries or configurations manually.

Sharing Playground Sessions

Upload a markdown file to your federated- and sub-graphs to share on-boarding or common information with your organization.

Graph Documentation

Comprehensive records detailing every instance of a subgraph publication.

Compositions

This page provides you with a detailed breakdown of requests made to your federated graph. It's equipped with grouping, filtering and date range features to enable you to analyze your data.

Analytics

Metrics give a general overview of the performance of your federated graph. From here you can zoom in on specific time ranges and filter metrics by operation name, client name, and version.

Metrics

Lists all the requests made to your router. For each request, it shows the relevant details, such as the operation performed, the client who made the request, and any error message

Traces

This page shows the path taken by the request through your federated graph and the operation content.

Distributed Tracing

Evolve your schema by making decisions based on how every field is used by different clients and operations

Schema Field Usage

Enrich your clients with the proper client name and version to distingush them in the analytics.

Client Identification

This page enables the management of API tokens for automation purposes, such as CI/CD or local CLI usage.

Configure the permissions of your api keys

API Key Permissions

Configure the resources accessible to your api keys.

API Key Resources

Migrate from Apollo GraphOS to WunderGraph Cosmo with a single click

Getting Started

Concepts

Federation

CLI (wgc)

Studio

Router

Control Plane

Deployments and Hosting

Directives

@shareable

@authenticated

@requiresScopes

@openfed__subscriptionFilter

@openfed__configureDescription

Federation Directives Index