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