Compare GraphQL Schemas
Project description
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 an approval along with your pull requests.
- Restricting unwanted changes
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
As a 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] [-a ALLOW_LIST] [-t] [-r] [-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 -a ALLOW_LIST, --allow-list ALLOW_LIST Path to the allowed list of changes -t, --tolerant Tolerant mode. Error out only if there's a breaking change but allow dangerous changes -r, --restrictions Restricted mode. Error out on restricted 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 # Compare schemas restricting adding new types without description schemadiff -o tests/data/simple_schema.gql -n simple_schema_new_type_without_description.gql -r add-type-without-description
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 😎
Restricting changes
You can use this library to validate whether your schema matches a set of rules.
Built-in restrictions
The library has its own built-in restrictions ready-to-use. Just append them to the -r
command in CLI
. You can
add as many as you want.
-
add-type-without-description
Restrict adding new GraphQL types without entering a non-empty description. -
remove-type-description
Restrict removing the description from an existing GraphQL type. -
add-field-without-description
Restrict adding fields without description. -
remove-field-description
Restrict removing the description from an existing GraphQL field. -
add-enum-value-without-description
Restrict adding enum value without description. -
remove-enum-value-description
Restrict adding enum value without description.
Running the following command, you could restrict type additions without entering a nice description.
# Compare schemas restricting adding new types without description
schemadiff -o tests/data/simple_schema.gql -n simple_schema_new_type_without_description.gql -r add-type-without-description
API Reference
You can also read the API Reference if you want to get a better understanding of the inner workings of the lib
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
Contributors
- @Checho3388: Added the whole
evaluate_diff
functionality. Thank you!
You can contribute reporting bugs, writing issues or pull requests for any new features!
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Filename, size | File type | Python version | Upload date | Hashes |
---|---|---|---|---|
Filename, size graphql_schema_diff-1.0.6-py3-none-any.whl (50.0 kB) | File type Wheel | Python version py3 | Upload date | Hashes View |
Filename, size graphql-schema-diff-1.0.6.tar.gz (28.4 kB) | File type Source | Python version None | Upload date | Hashes View |
Hashes for graphql_schema_diff-1.0.6-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 87e3eb9b003486ef25cc032584184344390803756c7a46e903f6b7131ff1a63a |
|
MD5 | dd016fc9e1d7a1e8d9226a72eedb5ae8 |
|
BLAKE2-256 | 99a5d987d1cff897f41526a97e52077d87bf3e62db694b3babcf7ebd584ecf5d |
Hashes for graphql-schema-diff-1.0.6.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | c09afc2147e71aeba353d15e43936830c5eab2e58efcea2636136e9b82208109 |
|
MD5 | 4e1c6444db0679ca7e6f48c9cfc5a2ad |
|
BLAKE2-256 | fdff62b4c8e55d7709b00c659882e8296d385dad5934ec2a6171d0be8a309663 |