Schema Checks

Certain changes to your graph's schema, such as removing a field or type, might break one of your application's clients. GraphOS schema checks help you identify breaking changes before you make them. They can also help you identify when a potentially dangerous change is, in fact, safe.

You run schema checks using the Rover CLI and can integrate checks into your CI pipeline for automated validation of each schema change. GraphOS Studio displays check results, helping you make informed decisions about evolving your graph.

Each schema check run consists of several check types or tasks. By default, build, operations, and linter checks are included in each schema check run. Custom, proposals, and contract checks require an Enterprise plan.

All other schema checks are free as part of all Apollo plans.

Types of checks

GraphOS can perform the following types of schema checks:

This article provides further details on build and operations checks.

• For details on linter checks, see Schema linting.

• For details on custom checks, see Custom checks.

• For details on proposals checks, see Schema proposals check configuration.

• For details on contract checks, see Contract checks.

Build checks

When you run a schema check, GraphOS performs a build check before performing any other checks. A build check verifies that changes you make to a subgraph schema are valid GraphQL definitions and are compatible with your other subgraph schemas, enabling them to compose into a supergraph schema for your router. For that reason, build checks are sometimes called composition checks.

If a build check fails, GraphOS performs no other checks for the provided schema.

Operations checks

If a build check succeeds, GraphOS then validates schema changes with operations checks. Operations checks use your graph's historical client operation data to determine whether any clients would be negatively affected by the proposed schema changes. For example, an operations check would flag a change that removes a field that multiple clients use in their operations.

Limitations

Operations check cardinality

Operations checks run against a maximum of 10,000 distinct operations. GraphOS Studio displays when a larger cardinality has been reached.

Input field usage reporting

GraphOS tracks operation usage. To deduplicate operations, Apollo uses operation signatures to denormalize the arguments and inputs. However, operation signatures don't track which fields on input types are used.

For example, by default, GraphOS doesn't track how many times the input field GetUsersInput.firstName is used in this schema:

type Query {
  getUsers(filters: GetUsersInput): [User]
}

input GetUsersInput {
  firstName: String
  lastName: String
}

type User {
  id: ID!
  firstName: String!
  lastName: String!
}

Next steps

To learn how to run your first schema check and integrate checks into your CI pipeline, refer to Run Schema Checks. You can also connect schema checks to GitHub to add links to check results on the pull requests that initiate them. For a guide on configuring checks, see Check Configurations. See the Checks Reference for the types of schema changes that checks detect.