Join us from October 8-10 in New York City to learn the latest tips, trends, and news about GraphQL Federation and API platform engineering.Join us for GraphQL Summit 2024 in NYC
Docs
Start for Free

Schema Checks

Validate proposed changes to your schema are safe


Certain changes to your 's schema, such as removing a or type, might break one of your application's clients. 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 using the and can integrate checks into your CI pipeline for automated validation of each schema change. displays check results, helping you make informed decisions about evolving your graph.

Schema check results in Studio

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. 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:

Check TypeDescription

Build checks

For , verify whether proposed changes to a schema successfully compose with other . Also known as composition checks.

Operations checks

Compare proposed schema changes against historical operations to verify whether the changes break any of your graph's active clients.

Linter checks

Analyze proposed schema changes for violations of formatting rules and other GraphQL best practices.

Proposals checks

(Enterprise only)

Check whether your proposed schema changes have matching and approved schema proposals.

(Downstream) contract checks

(Enterprise only)

When running schema checks on a , check whether your proposed schema changes break any downstream contract .

This article provides further details on build and 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 are valid definitions and are compatible with your other subgraph schemas, enabling them to compose into a for your . For that reason, build checks are sometimes called checks.

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

You can inspect a particular build check from your graph's Checks page in GraphOS Studio to view its result. If composition succeeded, you can view the composed supergraph schema. Regardless of success, you can view the proposed subgraph schema.

Failed build check results in Studio

Operations checks

If a build check succeeds, GraphOS then validates schema changes with operations checks. 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.

Failed operations check results in Studio

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

NOTE

This limitation only applies to reporting metrics from and older versions of the .

If you use the to report operation metrics, you can configure enhanced operation signature normalization and extended reference reporting to track input field usage.

GraphOS tracks usage. To deduplicate operations, Apollo uses operation signatures to denormalize the and inputs. However, don't track which 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.

Previous
Overview
Next
Run Schema Checks
Rate articleRateEdit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc., d/b/a Apollo GraphQL.

Privacy Policy

Company