Skip to main content

Compare GraphQL Schemas

Project description

Build status codecov Codacy License: GPL v3 Python 3.6+

schemadiff

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.

Installation

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

$ python3 -m pip install graphql-schema-diff

Usage

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

Lib

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

CLI

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

Examples

# 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 https://gist.github.com/Ambro17/80bce76d07a6eb74323db2ca9b887263
$ fc-cache -f -v

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

Credits

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

Contributions

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