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:

Diff - Usage

Run the following command:

graphql-inspector diff OLD_SCHEMA NEW_SCHEMA

Arguments

• OLD_SCHEMA - point to an old schema
• NEW_SCHEMA - point to a new schema

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, the 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

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

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.

ignoreDescriptionChanges

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

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

safeUnreachable

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 https://api.com/graphql schema.graphql --rule safeUnreachable

Example of unreachable type:

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

considerUsage

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

graphql-inspector diff https://api.com/graphql 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(
    entities.map(async ({ type, field, argument }) => {
      // User                   => { type: 'User' }
      // Query.id               => { 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 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 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.