Skip to main content

Compare GraphQL Schemas

Project description

Build status codecov Codacy License: GPL v3 Python 3.6+


schemadiff is a lib that shows you the difference between two GraphQL Schemas. It takes two schemas from a string or a file and gives you a list of changes between both versions. This might be useful for

  • Detecting breaking changes before they reach the api clients
  • Integrating into CI pipelines to control your api evolution
  • Document your api changes and submit them for approval along with your pull requests.


The lib requires python3.6 or greater to work. In order to install it run

$ python3 -m pip install graphql-schema-diff


You can use this package as a lib or as a cli. You can choose what better suits your needs


>>> from schemadiff import diff, diff_from_file, print_diff
>>> old_schema = """
schema {
    query: Query

type Query {
    a: Int!,
    sum(start: Float=0): Int
>>> new_schema = """
schema {
    query: Query

type Query {
    b: String,
    sum(start: Float=1): Int
>>> changes = diff(old_schema, new_schema)
>>> print_diff(changes)                   # Pretty print difference
>>> any(change.breaking or change.dangerous for change in changes)    # Check if there was any breaking or dangerous change

# You can also compare from schema files
>>> with open('old_schema.gql', 'w') as f:
...     f.write(old_schema)
>>> with open('new_schema.gql', 'w') as f:
...     f.write(new_schema)
>>> changes = diff_from_file('old_schema.gql', 'new_schema.gql')
>>> print_diff(changes)


Inside your virtualenv you can invoke the entrypoint to see its usage options

$ schemadiff -h
Usage: schemadiff [-h] -o OLD_SCHEMA -n NEW_SCHEMA [-j] [-t] [-s]

Schema comparator

optional arguments:
  -h, --help            show this help message and exit
  -o OLD_SCHEMA, --old-schema OLD_SCHEMA
                        Path to old graphql schema file
  -n NEW_SCHEMA, --new-schema NEW_SCHEMA
                        Path to new graphql schema file
  -j, --as-json         Output a detailed summary of changes in json format
  -t, --tolerant        Tolerant mode. Error out only if there's a breaking
                        change but allow dangerous changes
  -s, --strict          Strict mode. Error out on dangerous and breaking


# Compare schemas and output diff to stdout
schemadiff -o tests/data/simple_schema.gql -n tests/data/new_schema.gql`

# Pass a evaluation flag (mixing long arg name and short arg name)
schemadiff --old-schema tests/data/simple_schema.gql -n tests/data/new_schema.gql --strict`

# Print output as json with details of each change
schemadiff -o tests/data/simple_schema.gql -n tests/data/new_schema.gql --as-json

# Save output to a json file
schemadiff -o tests/data/simple_schema.gql -n tests/data/new_schema.gql --as-json > changes.json

# Compare schemas ignoring allowed changes
schemadiff -o tests/data/simple_schema.gql -n tests/data/new_schema.gql -a allowlist.json

If you run the cli and see a replacement character (�) or a square box (□) instead of the emojis run

$ sudo apt install fonts-noto-color-emoji
$ vim ~/.config/fontconfig/fonts.conf # and paste
$ fc-cache -f -v

That should install noto emoji fonts and set is as the fallback font to render emojis 😎


Implementation was heavily inspired by Marc Giroux ruby version and Kamil Kisiela js implementation.

Logo arrows were adapted from the work of Paul Verhulst @ The Noun Project


Bug reports, Feature requests or pull request are welcome!

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for graphql-schema-diff, version 1.0.0
Filename, size File type Python version Upload date Hashes
Filename, size graphql_schema_diff-1.0.0-py3-none-any.whl (46.6 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size graphql-schema-diff-1.0.0.tar.gz (29.5 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page