Diff two IDS schemas for a changelog

Summary

ts-ids schema-diff produces human-readable diffs between JSON schemas. Use ts-ids schema-diff changelog while developing an IDS to draft the field-level differences for the changelog section of the README; edit its output into changelog entries following the changelog authoring rules rather than pasting it verbatim.

This CLI is the only supported interface for this tool. The ts_ids_core.schema_diff python modules are internal and may change without notice.

changelog

ts-ids schema-diff changelog old.json new.json --output diff.md

# Omitting --output writes to stdout
ts-ids schema-diff changelog old.json new.json

# Ignore the schema keys 'definitions' and 'custom' during the diff
# (there are default values for this, see --help for more)
ts-ids schema-diff changelog old.json new.json -k definitions -k custom

This dereferences $ref pointers and sorts unordered containers so the diff isn’t sensitive to redundant information, then outputs a changelog like this:

- Add `runs[*].frequency_channels[*].full_channel`
- Add `runs[*].title`
- Update root schema: modify `$id` from `"http://ids.tetrascience.com/common/nmr-bruker/v1.0.0/schema.json"` to `"http://ids.tetrascience.com/common/nmr-bruker/v2.0.0/schema.json"`
- Update `@idsVersion` schema: modify `const` from `"v1.0.0"` to `"v2.0.0"`
- Update `methods[*].consumption.buffer_volume.unit` schema: remove `const`
- Update `runs[*].dimension.mode` schema: add `additionalProperties`: false
- Update `runs[*].dimension.mode` schema: add `type`: "object"
- Update `runs[*].frequency_channels[*]` schema: modify `my_annotation.test` from `[5]` to `{"child": 4}`
- Remove `runs[*].frequency_channels[*].channel`

By default, changelog hides description, title, and definitions changes, and addition/removal of empty required lists ("required": []), because none of these affect IDS instance validation. To see every difference, pass empty values for --ignore-key/-k and --ignore-empty/-e:

ts-ids schema-diff changelog -e '' -k '' schema-before.json schema-after.json

Run ts-ids schema-diff changelog --help for the full list of options and their defaults.

Use with git difftool

git difftool accepts a custom diff command via -x, so ts-ids schema-diff changelog can diff schema.json across commits, branches, or version folders:

# Compare schema.json across branches and version folders, from a feature branch
git difftool -x "ts-ids schema-diff changelog" development:./v1.0.0/schema.json v1.0.1/schema.json

# Compare schema.json across branches or git hashes
git difftool -x "ts-ids schema-diff changelog" development my-branch schema.json

# Compare across version folders, showing every difference
git difftool -x "ts-ids schema-diff changelog -k '' -e ''" development:./v1.0.0/schema.json v1.0.1/schema.json

norm

ts-ids schema-diff norm runs just the normalization step — dereferencing $refs and dropping the same default set of keys as changelog — without producing a diff. Use it to simplify a schema before piping it into another diff tool:

# From and to a file
ts-ids schema-diff norm schema.json -o output.json

# Using stdin and stdout
cat schema.json | ts-ids schema-diff norm

# Take a `diff` of flattened, normalized JSON schemas
diff -u <(ts-ids schema-diff norm schema-before.json | gron)  <(ts-ids schema-diff norm schema-after.json | gron)

# Take a `jd` diff of normalized JSON schemas
jd <(ts-ids schema-diff norm schema-before.json)  <(ts-ids schema-diff norm schema-after.json)

Run ts-ids schema-diff norm --help for the full list of options.