You change one value in a JSON config, run git diff, and get a wall of red and green — because a formatter reflowed the file, or the serializer reordered the keys, or the indentation shifted by two spaces. The one thing you actually changed is buried in there somewhere. Good luck finding it in review.
The problem is that git diff and diff work on lines. JSON isn't lines — it's a tree. So I built jdelta: it compares the data, ignores key order and whitespace entirely, and tells you exactly which values changed, addressed by path. Zero dependencies, no network.
What it looks like
$ jdelta config.before.json config.after.json
Added (1)
+ features.darkMode true
Changed (2)
~ auth.required true → false
~ server.port 8080 → 3000
+1 -0 ~2
auth.required flipped to false and you can see it instantly — no scrolling past 200 lines of reindented braces.
Why not git diff / diff?
Because they diff text. Run a formatter, sort your keys, change two spaces of indent, and a line differ lights up the whole file while reporting zero semantic change. jdelta parses both sides and walks the trees:
-
Object keys show as
user.profile.age; array elements asitems[2].price. Odd keys fall back to quoted brackets (["order-id"]). - A key on only one side is added / removed; a key on both with a different value is changed. A type change (
number→string,object→array) is one changed entry tagged with the kinds — not a confusing add + remove. - Reordered keys and whitespace produce nothing, because they aren't data changes.
Great for reviewing config changes, API-response snapshots, tsconfig/settings.json, lockfile-adjacent files, and test fixtures.
In scripts and CI
jdelta a.json b.json --json # machine-readable: {added, removed, changed, summary}
jdelta a.json b.json --quiet # just the +a -r ~c line
jdelta a.json b.json --exit-code # exit 1 if they differ — gate a pipeline on it
Install
npx jdelta a.json b.json # Node build (npm)
pip install jdelta # Python build — same behavior
Two builds, Node and Python, that walk the tree identically, so it fits whatever your repo already runs.
A couple of honest design notes
- Zero dependencies, both builds. stdlib only on each side — a diff tool that pulled in a dependency tree of its own would be missing the point.
- Arrays are compared by index. Simple and predictable; inserting at the front of a big array reads as "everything shifted" rather than guessing at moves. I'd rather be honest than clever here.
- Integer precision. JavaScript parses every JSON number as a 64-bit float, so the Node build can't reliably diff integers past ±2^53 (snowflake IDs, int64 DB keys). The Python build keeps integer precision exactly — reach for it when your data has big integers. (It's documented in the README rather than hidden.)
Links
- npm: https://www.npmjs.com/package/jdelta
- PyPI: https://pypi.org/project/jdelta/
- Source: https://github.com/jjdoor/jdelta
What do you reach for today when you need to diff two JSON files and git diff just won't do? And does anyone gate CI on structural config diffs — or is that still a manual eyeball step?
