GraphQL schema diff: the change classes the visitor walks.
Compare any two GraphQL schemas and get a categorized report of the breaking changes, deprecations, and schema modifications it detects — in seconds.
What the Diff Engine Detects
CodeRifts parses GraphQL SDL and reports the change classes the visitor actually walks — not a text diff, and not every GraphQL construct.
Breaking Change Types
- ✕ Type removed from the schema
- ✕ Field removed from a type
- ✕ Argument removed from a field
- ✕ Type changed for a field
- ✕ Required argument added to a field
- ✕ Enum value removed (direction not measured for GraphQL)
- ✕ Interface field removed
- ✕ Union member removed
- ✕ Input field removed
- ✕ Input field type changed
- ✕ Nullability follows direction: output T! to T is a break, output T to T! is not, an input or argument T to T! with no default is a break, and an input or argument T! to T is not.
Non-Breaking Changes
- ✓ New field added to an existing type
New types, new enum values, new directives, description updates and deprecations are not reported. A field added is the only non-breaking class the visitor emits.
Why Automated GraphQL Diffing Matters
Manually comparing two versions of a GraphQL schema is not only tedious but also highly error-prone. As GraphQL APIs evolve, their schemas can grow to be very complex, with intricate relationships between types, fields, and arguments. A simple text-based diff, like the one you might see in a Git commit, is insufficient because it fails to understand the semantic meaning of the GraphQL structure.
Automated tooling is essential for managing this complexity. A purpose-built GraphQL diff tool doesn't just compare text; it parses the schema, resolves all references, and understands the hierarchical structure of the API contract. For example, changing a field from optional to required within a type is a significant breaking change, but it might appear as a minor, one-word alteration in a text file. Without an automated, semantically-aware diff, teams risk shipping breaking changes unknowingly.
How CodeRifts Performs the Diff
CodeRifts parses both GraphQL schemas as SDL (graphql.buildSchema) and compares removed types, object types, interface fields, union members and enum values. A GraphQL input type no longer crashes the diff. Nullability follows direction: output T! to T is a break, output T to T! is not, an input or argument T to T! with no default is a break, and an input or argument T! to T is not. Custom scalars as scalars, directives, deprecations, and default-value changes are not compared. Removing an interface from an implementing type is not compared. Non-breaking changes that are reported: a field added to an existing type.
There is no $ref to resolve — the input is SDL. Detected changes are labelled breaking or, for a field added to an existing type, non-breaking. There is no deprecation class. Each breaking change contributes to a risk score. The output is the change list, the score, and a decision derived from that score.
Use Cases
CI/CD Pipelines
By incorporating CodeRifts into your Continuous Integration and Continuous Deployment (CI/CD) pipeline, you can automatically fail builds that introduce high-risk or unauthorized breaking changes. You can use our CLI or REST API to add a diff check as a required step in your deployment workflow.
Pre-Merge Checks
With the CodeRifts GitHub App, every pull request that modifies a GraphQL schema file gets an automatic check. A detailed comment is posted directly on the PR, showing a summary of the changes and a link to the full diff report. This enables developers and reviewers to understand the impact of their changes before they are merged.
API Versioning Strategy
Automated diffing is fundamental to a sound API versioning strategy. By understanding the nature of every change, you can make deliberate decisions about when to release a new minor version (for non-breaking, backward-compatible changes) versus a new major version (for breaking changes).
Schema Evolution Management
GraphQL schemas are designed to evolve, but managing these changes without impacting existing clients is crucial. CodeRifts helps you track and understand every modification, ensuring that your schema evolution is intentional and safe, preventing unexpected client-side errors.
Three Ways to Diff
In-Browser
Upload two schemas to app.coderifts.com/try and get a full report instantly. No signup required.
On Every PR
Install the GitHub App and CodeRifts automatically diffs your GraphQL schemas on every pull request. Zero config.
A diff names the change. A grant is what lets it proceed.
Every diff includes risk scoring, policy enforcement, security analysis, and an auto-generated changelog — showing you what changed and why it matters.
Risk Scoring
Get an objective risk score (0-100) for every change, helping you prioritize and manage API evolution with confidence.
Policy Enforcement
Define custom policies to automatically block or warn on specific breaking changes, ensuring compliance and consistency.
Auto-Changelog
Automatically generate a human-readable changelog from your diffs, making it easy to communicate API updates to consumers.
Frequently Asked Questions
What is a GraphQL diff?
A GraphQL diff is the result of comparing two versions of a GraphQL schema to identify all the changes between them. Unlike a simple text diff, a proper GraphQL diff tool understands the structure and semantics of the schema. It can pinpoint specific changes like a removed field, a modified type, or a new required argument, and classify them as breaking or non-breaking.
How do I compare two GraphQL schemas?
You can compare two GraphQL schemas using a specialized tool like CodeRifts. You can use our free in-browser tool by simply uploading your two schema files. For a more automated workflow, you can integrate our GitHub App to get a comparison on every pull request, or use our CLI or REST API to run a comparison in your own scripts or CI/CD pipelines.
What counts as a breaking change in GraphQL?
A breaking change in GraphQL is any modification to a schema that can cause existing client applications to fail. Common examples include removing a field from a type, adding a new required argument to a field, or changing the type of a field. CodeRifts maintains a comprehensive list of common breaking change types that it detects automatically.
Can I use this in CI/CD?
Absolutely. Integrating GraphQL diffing into your CI/CD pipeline is a best practice for preventing breaking changes from reaching production. CodeRifts provides both a CLI tool and a REST API that you can easily incorporate into your existing workflows, whether you use Jenkins, GitLab CI, CircleCI, or any other automation server. You can configure your pipeline to fail a build if a high-risk breaking change is detected.
Put contract changes behind a verifiable gate
Detecting the GraphQL diff is the first step, not the last. CodeRifts analyzes the change, issues an authorization bound to that change set, enforces it at the merge, and leaves a receipt anyone can verify offline — without an account and without asking us. A diff tells you what moved; a grant is what lets it proceed.
Install on GitHubA diff tells you what changed. It does not tell you whether it may proceed.