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:
Products | Description |
---|---|
GitHub Application | Install our GitHub Application to check Pull Requests and commits. |
GitHub Action | Use our GitHub Action in few steps. |
CI | GraphQL Inspector offers a version of our CLI that is better suited for Continuous Integrations. Learn more how to use it. |
CLI | GraphQL Inspector CLI is a simple tool to work with GraphQL schemas. |
Diff - Usage
Run the following command:
graphql-inspector diff OLD_SCHEMA NEW_SCHEMA
Arguments
OLD_SCHEMA
- point to an old schemaNEW_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
.
--left-header
and --right-header
overrides the --header
flags.