Skip to main content

Schema Validation

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 Continous Integration.

Application

Using GitHub Application#

Install our GitHub Application to check Pull Requests and commits.

Using GitHub Action#

Use our GitHub Action in few steps.

Using in CI#

GraphQL Inspector offers a version of our CLI that is better suited for Continous Integrations. Learn more how to use it.

Using CLI#

Detected following changes:
❌ Field posts was removed from object type Query
❌ Field modifiedAt was removed from object type Post
✅ Field Post.id changed typed from ID to ID!
✅ Deprecation reason "No more used" on field Post.title was added
ERROR Detected 2 breaking changes!

Usage#

Run the following command:

graphql-inspector diff OLD_SCHEMA NEW_SCHEMA

Arguments

Flags

  • -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)

Output

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, process fails, otherwise it succeeds.

Examples#

Compare your local schema against a remote server:

graphql-inspector diff https://api.com/graphql 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

Rules#

In order to customize the diff's behavior, you're able to use a set of rules:

dangerousBreaking

Turns every dangerous change to be a breaking change.

graphql-inspector diff https://api.com/graphql schema.graphql --rule dangerousBreaking

suppressRemovalOfDeprecatedField

Every removal of a deprecated field is considered as 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 https://api.com/graphql schema.graphql --rule suppressRemovalOfDeprecatedField

ignoreDescriptionChanges

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

graphql-inspector diff https://api.com/graphql schema.graphql --rule ignoreDescriptionChanges

Custom rules#

It's possible to write your own rules.

First, you need a module:

// custom-rule.js
module.exports = ({changes}) => {
return changes.filter(myCustomFilter);
};

Now, you can use that module as a rule:

graphql-inspector diff https://api.com/graphql 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 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