/
Launch Apollo Studio

Federated schema checks

For an introduction to schema checks, see Schema checks.

Whenever you make changes to a subgraph schema, running rover subgraph check helps ensure that all your subgraph schemas still compose to a valid supergraph schema. This helps teams work independently on their portion of your federated graph without negatively affecting your users or other teams.

When you run rover subgraph check on a particular subgraph, Apollo Studio takes your schema changes and attempts to compose a supergraph schema from all of your registered subgraph schemas.

  • If composition succeeds, the result is compared against your most recently registered supergraph schema to confirm that no known clients are affected by the proposed changes.
  • If composition fails, validation ends and results are returned to the user.

Running rover subgraph check never updates your current registered supergraph schema.

Handling check failures

There are two types of failures that can occur during validation: failed usage checks and failed composition.

  • Failed usage checks are failures due to breaking changes, like removing a field that an active client is querying.
  • Failed composition is a failure due to inability to compose the graph, like missing a @key for an extended entity.

In most cases, you should run rover subgraph publish only after a successful run of rover subgraph check. However, certain workflows require intentionally publishing a subgraph schema that fails composition (such as migrating an entity or field between subgraphs).

Even after rover subgraph check succeeds, however, it's possible that rover subgraph publish encounters composition errors because of simultaneous changes to another subgraph. When this occurs, your subgraph's registered schema is still updated as long as it is spec-compliant. However, the supergraph schema is not updated. This means that your gateway's configuration is also not updated.

An example output of this behavior looks like this:

$ rover subgraph publish docs-example-graph@current --name books --schema ./schema.graphql

Publishing SDL to docs-example-graph:current (subgraph: books) using credentials from the default profile.
The gateway for the 'docs-example-graph' graph was NOT updated with a new schema
WARN: The following composition errors occurred: 
Field "Author.name" can only be defined once.
There can be only one type named "Author".
Field "Book.title" can only be defined once.
Field "Book.author" can only be defined once.
There can be only one type named "Book".

The reasoning behind this functionality is that the Apollo schema registry should always reflect what is running in your infrastructure. Even if that means that composition is failing in your infrastructure, the registry should reflect that.

However, you still want your gateway to function as it was before the most recent deployment. Additionally, this functionality can be used to make dependent changes, like smoothly migrating a field from one subgraph to another or introducing a circular dependency.

Edit on GitHub