graphql-inspector diff: Detect Breaking Schema Changes
graphql-inspector diff compares an old and new GraphQL schema and classifies each change as breaking, dangerous, or non-breaking, exiting non-zero on breaking changes.
For GraphQL APIs, removing a field or changing a type can break clients. graphql-inspector diff is the equivalent of oasdiff for GraphQL and slots straight into a PR gate.
What it does
The diff command loads two schema sources (SDL files, URLs, or git refs) and reports every change with a criticality level: Breaking, Dangerous, or Non-Breaking. It exits with a non-zero code when a breaking change is detected.
Common usage
graphql-inspector diff old.graphql new.graphql
# compare the schema against the committed version in main
graphql-inspector diff "git:origin/main:schema.graphql" schema.graphqlOptions
| Flag | What it does |
|---|---|
| <old> <new> | Two schema pointers (file, URL, or git:ref:path) |
| --rule <name> | Apply a rule, e.g. suppressRemovalOfDeprecatedField |
| --onComplete <script> | Run a script to control the exit behavior |
| -r, --require <module> | Preload a module (e.g. for URL headers) |
| --headers <k=v> | Headers when loading a schema over HTTP |
In CI
Compare the PR schema against git:origin/main:schema.graphql so the baseline is always the merged schema, no separate artifact needed. The git: loader makes this a one-command gate. Use --rule suppressRemovalOfDeprecatedField if your policy allows removing fields that were deprecated long enough.
Common errors in CI
Breaking changes print like ✖ Breaking changes detected with lines such as Field 'User.email' was removed and the command exits non-zero. "Couldn't find any GraphQL type definitions" means an empty or wrong schema path. "Unable to download schema from remote" means the introspection endpoint failed; pass --headers for auth or use an SDL file.