Schema Checks

The Schema Registry runs a suite of checks on a schema.

You can check a subgraph schema before publishing in a federated graph.

Run Schema Checks with the grafbase check command. Read more in the reference documentation.

A successful check returns a successful exit code (0).

Check errors return a non-zero exit code and print the errors, making the command suitable for scripts and CI pipelines.

When you run grafbase check, the Schema Registry:

1. Gathers all subgraph schemas for the branch
2. Validates each schema as a valid GraphQL schema
3. Composes all subgraph schemas together with the new version of the checked subgraph

The Schema Check fails if errors occur in steps 2 or 3.

APIs evolve. Most changes add functionality: new mutations, fields on types, or input objects for filtering collections. You can make these changes safely without breaking API consumers.

Other changes break clients using queries written for previous API versions. Common examples include removing fields or adding required field arguments. These changes disrupt service because GraphQL servers reject invalid queries that don't match the current schema.

Operation Checks help prevent breaking changes to your GraphQL schema. They provide rules that surface breaking changes as errors when you run grafbase check.

Breaking changes must meet two criteria:

• The change breaks existing functionality. See list of breaking changes.
• Clients actively use the changed or removed schema parts.

Without the second criterion, Operation Checks would prevent schema iteration even for unused parts. Operation checks analyze request data to focus on actual API usage rather than theoretical breaking changes.

Configure Operation Checks in the dashboard as an opt-in feature.

Enable checks for your entire graph or specific branches. Select query thresholds and timeframes for schema usage analysis.

Exclude operations by name. For example, this GraphQL document names the operation "JapaneseProducts":

query JapaneseProducts {
  products(filter: { madeIn: "JP" }) {
    id
    name
  }
}

Exclude specific clients by identifying them through the x-grafbase-client-name header. Include this header in any GraphQL client.

The grafbase check command runs Operation Checks with other schema checks. Errors indicate breaking changes that would occur when deploying the new schema. The system analyzes real client usage data from the target branch.

This list shows potentially breaking changes:

• Removal of a root query, mutation or subscription type.
• Removal of an object, interface or input object field.
• Removal of a field argument.
• Removal of an interface from implements.
• Removal of a member type in a union.
• Removal of a value of an enum.
• Addition of a nonnullable argument on a field.
• Addition of a nonnullable field on an input object.
• Change of a field's type.
  • Either change of the inner type: String becoming Int for example,
  • or a change of wrapping types making the field nullable: String! to String or [String!] to [String] for example. The client would not expect null here.
• Change of a field argument's type.
  • Either change of the inner type: String becoming Int for example,
  • or a change of wrapping types making the argument nonnullable: String to String! or [String] to [String!] for example. The client could be passing null.
• Removal of a field argument's default, if the argument is required.

We check actual usage before triggering Operation Check errors.

Lint checks analyze your schema to find potential issues like mistakes, oversights or disallowed behaviors that don't cause hard compilation errors.

• Naming conventions
  • Types: PascalCase
    • Forbidden prefixes: "Type"
    • Forbidden suffixes: "Type"
  • Fields: camelCase
  • Input values: camelCase
  • Arguments: camelCase
  • Directives: camelCase
  • Enums: PascalCase
    • Forbidden prefixes: "Enum"
    • Forbidden suffixes: "Enum"
  • Unions
    • Forbidden prefixes: "Union"
    • Forbidden suffixes: "Union"
  • Enum values: SCREAMING_SNAKE_CASE
  • Interfaces
    • Forbidden prefixes: "Interface"
    • Forbidden suffixes: "Interface"
  • Query fields
    • Forbidden prefixes: ["query", "get", "list"]
    • Forbidden suffixes: "Query"
  • Mutation fields
    • Forbidden prefixes: ["mutation", "put", "post", "patch"]
    • Forbidden suffixes: "Mutation"
  • Subscription fields
    • Forbidden prefixes: "subscription"
    • Forbidden suffixes: "Subscription"
• Usage of the @deprecated directive requires specifying the reason argument

• The CLI runs lint checks through grafbase check or in the dashboard after passing validation and composition checks
• Run lint checks locally on SDL schemas with the grafbase lint command

Proposal checks enforce that all changes in the checked schema — compared to the currently published schema — are part of an approved schema proposal. The changes must not exactly match a given proposal, they only have to be part of any approved proposal. That means a given check or publish can implement in parts on in entirety one or more proposals. The check is based on semantic diffs between the checked schema and the relevant approved proposals.

Proposal checks are opt-in. You can enable them in the dashboard's Graph settings page.

$ grafbase check --schema products.graphql --name products grafbase/fed-demo@main
Grafbase CLI 0.82.3

⏳ Checking...

Errors were found in your schema check:

Proposal checks

❌ [Error] No approved schema proposal contains the field `name` in the new object type `Seller`

View past schema checks in the Checks tab of the Grafbase dashboard.

If you use GitHub Actions for CI, there is a pre-packaged and documented grafbase-schema-check action that uses the same approach as the description below..

Use the command in scripts by providing the same arguments as interactive use.

Authentication differs from interactive use. Instead of the grafbase login flow, provide a Grafbase access token. Generate tokens in the dashboard:

The grafbase introspect --dev command generates GraphQL schema files for the --schema argument of grafbase check. See examples in the GitHub workflow of the example repository. A federated graph example is also available.