Diff and Validate GraphQL Schemas

Detect changes to your GraphQL Schema and prevent breaking your existing applications. With GraphQL Inspector you get a list of breaking, potentially dangerous and safe changes on every Pull Request. Integrate it with GitHub, BitBucket, GitLab or any Continuous Integration.


You can choose between:

GitHub ActionUse our GitHub Action in few steps.
CIGraphQL Inspector offers a version of our CLI that is better suited for Continuous Integrations. Learn more how to use it.
CLIGraphQL Inspector CLI is a simple tool to work with GraphQL schemas.

Diff - Usage

Run the following command:

graphql-inspector diff OLD_SCHEMA NEW_SCHEMA



  • -r, --require <s> - require a module
  • -t, --token <s> - an access token
  • -h, --header <s> - set http header (`—header ‘Auth: Basic 123’)
  • --method - method on url schema pointers (default: POST)
  • --federation - Support Apollo Federation directives (default: false)
  • --aws - Support AWS Appsync directives and scalar types (default: false)


A list of all differences between two schemas. GraphQL Inspector defines three kinds of changes:

  • Non-breaking change
  • Dangerous Change
  • Breaking change

When there’s at least one breaking change, the process fails, otherwise, it succeeds.


Compare your local schema against a remote server:

graphql-inspector diff schema.graphql

Compare your local schema against a schema on a master branch (GitHub):

graphql-inspector diff github:user/repo#master:schema.graphql schema.graphql


To customize the diff’s behavior, you’re able to use a set of rules:


Turns every dangerous change to be a breaking change.

graphql-inspector diff schema.graphql --rule dangerousBreaking


Every removal of a deprecated field is considered a breaking change. With that flag, you can turn it into a dangerous change, so it won’t fail a process or a CI check.

graphql-inspector diff schema.graphql --rule suppressRemovalOfDeprecatedField

Here is an example of a breaking change:

type User {
  id: ID
  name: String
  age: Int @deprecated
type User {
  id: ID
  name: String
  • When “suppressRemovalOfDeprecatedField” rule enabled, it will not consider the removal of the age field as a breaking change.


Changes in descriptions are filtered out and are not displayed in the CLI result.

graphql-inspector diff schema.graphql --rule ignoreDescriptionChanges


Breaking changes are done on unreachable parts of the schema (non-accessible when starting from the root types) and won’t be marked as breaking.

graphql-inspector diff schema.graphql --rule safeUnreachable

Example of unreachable type:

type Query {
  me: String
User can't be requested, it's unreachable
type User {
  id: ID!


Decides if a breaking change is in fact breaking, based on real usage of schema.

graphql-inspector diff schema.graphql --rule considerUsage --onUsage check-usage.js

Example check-usage.js file:

const BREAKING = false
const NOT_BREAKING = true
module.exports = entities => {
  return Promise.all( ({ type, field, argument }) => {
      // User                   => { type: 'User' }
      //               => { type: 'Query', field: 'me' }
      // Query.users(last: 10)  => { type: 'Query', field: 'users', argument: 'last' }
      const used = await checkIfUsedInLast30Days(type, field, argument)
      return used ? BREAKING : NOT_BREAKING

Custom rules

It’s possible to write your own rules.

First, you need a module:

module.exports = ({ changes }) => {
  return changes.filter(myCustomFilter)

Now, you can use that module as a rule:

graphql-inspector diff schema.graphql --rule './custom-rule.js'

Passing different headers to multiple remote schemas

If you want to do a diff between multiple remote schemas, each with a different set of authentication headers, you can do it with --left-header and --right-header flags like so:

graphql-inspector diff http://your-schema-1/graphql http://your-schema-2/graphql --left-header 'Auth: Basic 123' --right-header 'Auth: Basic 345'

where --left-header will get passed to http://your-schema-1/graphql and --right-header will get passed to http://your-schema-2/graphql.

Note: --left-header and --right-header overrides the --header flags.

Support for Custom Directives

GraphQL Inspector offers enhanced support for custom directives, allowing users to easily detect changes in directive usage within GraphQL schemas. This feature greatly improves the capabilities of schema diffing, enabling comprehensive tracking of modifications related to custom directives across different schema versions.

How to Use

  1. Define Custom Directives: Begin by defining custom directives within your GraphQL schemas. Specify their usage on various schema elements such as types, fields, arguments, and more.
directive @customDirective on FIELD_DEFINITION
  1. Run Schema Diff: Utilize the diff command provided by GraphQL Inspector. Specify the paths or URLs to the old and new schema files. Make sure that both schemas include the custom directives you want to track.
graphql-inspector diff OLD_SCHEMA NEW_SCHEMA

Replace OLD_SCHEMA and NEW_SCHEMA with the paths or URLs pointing to your old and new schemas respectively.

  1. Review Changes: After executing the diff command, GraphQL Inspector will analyze the schemas and identify any modifications related to custom directive usage. The output will provide detailed information about the detected changes, categorized based on their impact.



input Foo {
  a: String
  b: String
directive @foo on INPUT_FIELD_DEFINITION
input Foo {
  a: String @foo
  b: String

Rules for Custom Directives

GraphQL Inspector’s support for custom directives covers various schema elements, including:

  • ENUM