State of Federation 2026

Prithwish Nath

October 24, 2023·9min read

Edited on June 24, 2026 by Brendan Bondurant

TL;DR

On large federated GraphQL APIs, merging individual service schemas easily introduces composition errors and breaking changes. WunderGraph Cosmo gives you an open source schema registry with proper validation and schema checks: a central source of truth that stores your composed federated schema and every subgraph schema, detects field/type/directive conflicts, and flags breaking changes before they reach production. You run checks with the Cosmo CLI (wgc), often wired into CI/CD, and Cosmo can even suggest AI-assisted fixes for composition errors that you review before applying.

What is WunderGraph Cosmo?

Before we move forward, I wanted to make sure we’re on the same page when it comes to the tool I’ll be covering.

WunderGraph Cosmo includes open source components (Apache 2.0 license) for creating and managing federated GraphQL APIs, alongside a managed cloud offering. Using Cosmo, teams can also scale GraphQL-based architectures easily.

Cosmo is made up of different modules that make this possible:

• The Studio: It’s going to be here where you’ll spend most of your time, since this is the user-friendly UI that allows you to interact with almost everything else we’ll mention below. It contains the Schema Registry we’ll talk about today, and you can perform Schema Checks and Validation here, too.
• The Router: This component understands the Federation specification and how to bring together subgraphs into the federated graph. For each incoming query it builds a query plan, delegates execution to the relevant subgraphs (including entity resolution across them), and composes the individual responses into a single unified response for the client.
• The Control Plane: It’s the heart of the entire platform and it communicates with both the Studio and with the CLI (you can think of it as the glue binding everything together).
• The CLI: With Cosmo’s CLI, you’ll be able to create, update, and delete new schemas, validate them, start new projects and more. It talks directly to the Control Plane to perform these actions and it’s going to be one of your main points of contact with the stack.

The Schema registry

Your first stop should be the Schema registry, which is where you can see the most recent state of your federated schema. You’ll be able to read the entire composed schema in full detail (including all types, fields, directives, and subgraph schemas). You can’t edit the schema here, because, after all, this is the result of composing all subgraphs. However, you can review all of them here — including individual schemas of all subgraphs in your federated graph — and even download each as a .graphql file in case you need it for any external tooling you might be using, audits, etc.

Doing Schema Checks with Cosmo

Keep in mind that when you’re running a federated GraphQL API, you’re not just dealing with a single schema. Yes, you have the federated schema that encompasses all APIs, but you also, in practice while developing your app, have to deal with all the individual subgraph schemas.The UI for this is quite straightforward, you’ll find the “Checks” section at the bottom of the left-hand-side menu. From this table, we get 4 really interesting data points:

1. The subgraph where the check was performed.
2. The status of the check, clearly either “Passed” or “Failed”.
3. A composability indicator that tells you whether the new schema can be composed into the federated one without causing conflicts.
4. A non-breaking change indicator showing if the changes can break existing clients.

Notice there is a subtle difference between errors in composability and breaking change. Composability focuses on “conflicts” when merging, in other words, whether or not the schema makes sense at the end of the merge. A breaking change on the other hand, is going to affect client applications. Breaking changes can definitely be merged into the main schema, and the schema itself will be valid, however, applications using it will have to adapt.

In summary:

• Composition errors: The merge is NOT possible, and you cannot continue without fixing the generated conflicts.
• Breaking changes: The merge is possible, but client applications will break.

Performing schema checks with WunderGraph Cosmo

Schema checks won’t happen automatically, it’s your job to make sure you run them using Cosmo’s CLI tool (wgc) whenever you make any changes to one of the subgraphs of your API.

Checking subgraphs

You can check a subgraph by providing its name along with the path to the file where you store your schema locally.

For example, this could be your very simple schema file for a blogging subgraph:

// Example schema
type Post {
  id: ID!
  title: String!
}

Let’s now pretend you introduce a change on the Post entity because you want to change the title property to be postTitle. That’s definitely a change you can push, however, it’s also a breaking change for any app using this API.

Fixing Composition Errors with AI

This is probably one of the coolest features of Cosmo: proposing AI-assisted fixes for composition problems. Thanks to their integration with OpenAI, you can issue a command through their CLI tool that will analyze the proposed schema in the context of the federated graph, identify composition issues, and propose AI-assisted fixes for you to review.

Conclusion

Large federated APIs can be complicated to maintain, especially so if several teams work independently on each one without having any real coordination with each other. When that happens, schema problems can easily start appearing. Thanks to tools like Cosmo, you’re now able to see those problems way before they reach production.

Frequently Asked Questions (FAQ)

What is a GraphQL schema registry?

A schema registry is a central source of truth for managing your federated GraphQL schemas. In Cosmo, it stores the current and historical state of your composed federated schema along with every subgraph schema.

What is the difference between a composition error and a breaking change?

A composition error means the subgraph schemas cannot be merged into the federated schema at all, so you must fix the conflict before continuing. A breaking change means the merge is possible and the schema stays valid, but existing client applications will break.

How do I run a schema check with Cosmo?

Schema checks are run with the Cosmo CLI (wgc) whenever you change a subgraph. For example, you can run npx wgc subgraph check <name> --schema <path-to-schema> to check a single subgraph.

Can I check a federated graph before publishing changes to it?

Yes. Use npx wgc federated-graph check <name> --label-matcher <labels...> to check one federated graph for composition errors before composing and publishing changes.

Can Cosmo fix composition errors automatically?

Through its OpenAI integration, Cosmo can attempt to resolve composition errors with AI-assisted suggestions using npx wgc subgraph fix <name> --schema <path-to-schema> --out-schema <path-to-out-schema>. It validates and proposes a corrected schema.