Dataset Schema Diff: Public Worked Example

Compare two versioned schema manifests — columns, types, nullability and units — and classify every difference under a declared compatibility policy. A difference it cannot classify is reported as unclassified and the run is incomplete, because "no breaking changes found" is a sentence people act on.

This walkthrough uses the tool's public README and checked-in example files. Run the command from a repository checkout with Node.js 22+.

Run the checked-in example

# A compatible change: widened types and an added nullable column.
node bin/dataset-schema-diff.mjs \
  --root examples/compatible \
  --before orders.2026-01.json \
  --after  orders.2026-04.json \
  --policy examples/compatible/policy.json
# exit 0

# A breaking change: a narrowed key, a tightened column, a changed unit and a
# reordering, judged against a policy that calls reordering breaking.
node bin/dataset-schema-diff.mjs \
  --root examples/breaking \
  --before orders.2026-04.json \
  --after  orders.2026-07.json \
  --column-order breaking
# exit 1

Read the result

To run the CLI from its public GitHub source without installing a registry package, use npm exec --yes --package=git+https://github.com/edilec/dataset-schema-diff.git -- dataset-schema-diff --help.

Scope

Each is enforced before the work it bounds, so a legal-sized input cannot exhaust memory. Exceeding one is an incomplete result with a finding naming the limit — never a silent truncation, never a pass. Every one is tested from both sides: that it fires at N+1, and that it stays silent at exactly N.