graphql-schema-diff 1.0.0

Compare GraphQL Schemas

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!