Get changes between two GraphQL schemas πŸ€–
Clone or download
xuorig Merge pull request #19 from danpalmer/patch-1
Bundler is required for `schema_comparator` to run
Latest commit decfb59 Aug 28, 2018
Failed to load latest commit information.
bin improved CLI Dec 2, 2017
lib/graphql Add reason for TypeKindChanged May 24, 2018
test Better test coverage Feb 26, 2018
.gitignore gitignore Nov 14, 2017
.travis.yml Update travis.yml Aug 18, 2017 0.6.0 Feb 28, 2018 First Jul 22, 2017
Gemfile First Jul 22, 2017
LICENSE.txt First Jul 22, 2017 Update Mar 29, 2018
Rakefile Add Result tests Jul 23, 2017
graphql-schema_comparator.gemspec Bundler is required for `schema_comparator` to run Aug 9, 2018
schema.graphql CLI Jul 23, 2017


Build Status

GraphQL::SchemaComparator is a GraphQL Schema comparator. What does that mean? GraphQL::SchemaComparator takes two GraphQL schemas and outputs a list of changes between versions. This is useful for many things:

  • Breaking Change detection
  • Applying custom rules to schema changes
  • Building automated tools like linters


Add this line to your application's Gemfile:

gem 'graphql-schema_comparator'

And then execute:

$ bundle

Or install it yourself as:

$ gem install graphql-schema_comparator


GraphQL::SchemaComparator comes with a handy CLI to help compare two schemas using the command line.

After a gem install graphql-schema_comparator, use the CLI this way:

  schema_comparator compare OLD_SCHEMA NEW_SCHEMA  # Compares OLD_SCHEMA with NEW_SCHEMA and returns a list of changes
  schema_comparator help [COMMAND]                 # Describe available commands or one specific command

Where OLD_SCHEMA and NEW_SCHEMA can be a string containing a schema IDL or a filename where that IDL is located.


$ ./bin/schema_comparator compare "type Query { a: A } type A { a: String } enum B { A_VALUE }" "type Query { a: A } type A { b: String } enum B { A_VALUE ANOTHER_VALUE }"
⏳  Checking for changes...
πŸŽ‰  Done! Result:

Detected the following changes between schemas:

πŸ›‘  Field `a` was removed from object type `A`
⚠️  Enum value `ANOTHER_VALUE` was added to enum `B`
βœ…  Field `b` was added to object type `A`


GraphQL::SchemaComparator, provides a simple api for Ruby applications to use.


The compare method takes two arguments, old_schema and new_schema, the two schemas to compare.

You may provide schema IDL as strings, or provide instances of GraphQL::Schema.

The result of compare returns a SchemaComparator::Result object, from which you can access information on the changes between the two schemas.

  • result.breaking? returns true if any breaking changes were found between the two schemas
  • result.identical? returns true if the two schemas were identical
  • result.breaking_changes returns the list of breaking changes found between schemas.
  • result.non_breaking_changes returns the list of non-breaking changes found between schemas.
  • result.dangerous_changes returns the list of dangerous changes found between schemas.
  • result.changes returns the full list of change objects.

Change Objects

GraphQL::SchemaComparator returns a list of change objects. These change objects all inherit from Changes::AbstractChange

Possible changes are all found in changes.rb.

Change Criticality

Each change object has a #criticality method which returns a Changes::Criticality object. This objects defines how dangerous a change is to a schema.

The different levels of criticality (non_breaking, dangerous, breaking) are explained here:

The gem is available as open source under the terms of the MIT License.