dotdiff

CI crates.io clispec compliant

Semantic diff for JSON, YAML, TOML, and NDJSON. Compares two documents structurally (not line by line) and prints a path-addressed change list instead of textual noise. The sibling of dotpick: dotpick extracts fields, dotdiff tells you what changed.

Install

cargo install dotdiff

Usage

dotdiff old.json new.json          # text on a TTY, JSON when piped
dotdiff config.yaml config.json    # cross-format works
cat new.json | dotdiff old.json -  # `-` reads stdin

$ dotdiff old.json new.yaml
~ user.plan       "free" -> "pro"
- user.trialEnds  "2026-07-01"
+ user.seats      5
~ items[0].qty    1 -> 3

Output is the ~/+/- change list on a TTY, and structured JSON when piped:

$ dotdiff old.json new.json | jq .
{"identical": false, "changes": [
  {"op": "changed", "path": "user.plan", "old": "free", "new": "pro"}
]}

Paths use dotpick's dotpath vocabulary (user.plan, items[2].qty, ["quoted key"]), so you can feed a changed path straight back into dotpick to inspect it.

Matching list items by key

By default arrays compare by position, so reordering a list reports everything after the move as changed. Pass --array-key <field> to match objects in a list by an identity field instead - order-independent, and far less noise:

# Without: a reordered list looks like 4 changes.
# With --array-key id: just the one real change.
$ dotdiff old.json new.json --array-key id
~ items[id=1].qty  1 -> 3

Formats

JSON, YAML, TOML, and NDJSON are detected per file (by extension, then content); force both sides with --format. NDJSON is compared as an array of records, so --array-key matches records across two streams. Everything is loaded into one model, which is why cross-format diffing works.

Exit codes

code meaning
0 identical
1 differences found (the report is on stdout - not an error)
2 an input could not be read or parsed
3 usage error

Exit 1 is a data state, not a failure (the diff/grep convention), so dotdiff is scriptable as a gate: dotdiff a.json b.json && echo unchanged.

For agents (clispec)

dotdiff follows The CLI Spec: structured output on stdout, structured error envelopes on the last line of stderr, a schema subcommand whose development-branch output validates against the candidate clispec.dev/schema/v0.3.json (checked by the test suite), and the exit-1-on-differences contract declared as an outcome. Every command declares effects: read_only; the published release remains on frozen v0.2 until v0.3 freezes.

dotdiff schema

License

MIT

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for rvben from gravatar.com rvben

Credits

Author: Ruben J. Jongejan <ruben.jongejan@gmail.com>

License

MIT License (MIT)

Requires

Python >=3.8

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

dotdiff-0.1.1.tar.gz (36.3 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

dotdiff-0.1.1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (648.1 kB view details)

Uploaded Python 3manylinux: glibc 2.17+ x86-64

dotdiff-0.1.1-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (604.5 kB view details)

Uploaded Python 3manylinux: glibc 2.17+ ARM64

dotdiff-0.1.1-py3-none-macosx_11_0_arm64.whl (588.5 kB view details)

Uploaded Python 3macOS 11.0+ ARM64

dotdiff-0.1.1-py3-none-macosx_10_12_x86_64.whl (628.5 kB view details)

Uploaded Python 3macOS 10.12+ x86-64

File details

Details for the file dotdiff-0.1.1.tar.gz.

File metadata

  • Download URL: dotdiff-0.1.1.tar.gz
  • Upload date:
  • Size: 36.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: uv/0.12.3 {"installer":{"name":"uv","version":"0.12.3","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for dotdiff-0.1.1.tar.gz
Algorithm Hash digest
SHA256 14d4f89588f64b024891e76e1af8f5715500e69a774796562ebeb4e47cba7132
MD5 34e2537373805eea0615d2307123244f
BLAKE2b-256 bd97ba52e3bc4e1155e4fc68c934fe6f1e82ae0fd728df6a45c22fd490932f55

See more details on using hashes here.

File details

Details for the file dotdiff-0.1.1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

  • Download URL: dotdiff-0.1.1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
  • Upload date:
  • Size: 648.1 kB
  • Tags: Python 3, manylinux: glibc 2.17+ x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: uv/0.12.3 {"installer":{"name":"uv","version":"0.12.3","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for dotdiff-0.1.1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 bf75770366520b979e698346505f871d6d7587f0218455fb060921e99fd8aed7
MD5 ce6de3d345a31b16205113b707cf8d73
BLAKE2b-256 252f1b923065d8715f66af21f162042fdbaec0882f221bb5ed26905cba782750

See more details on using hashes here.

File details

Details for the file dotdiff-0.1.1-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

  • Download URL: dotdiff-0.1.1-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
  • Upload date:
  • Size: 604.5 kB
  • Tags: Python 3, manylinux: glibc 2.17+ ARM64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: uv/0.12.3 {"installer":{"name":"uv","version":"0.12.3","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for dotdiff-0.1.1-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 94e7100b53cb884a7ae20042309c0b829d4a4572b2940f76a179ae58476e134e
MD5 64c2d1578a36f475e986b3ac772ec799
BLAKE2b-256 0dc633e18864117a8f50906a3aa0bbbef5bc246960fdb3497c10b92a39f35781

See more details on using hashes here.

File details

Details for the file dotdiff-0.1.1-py3-none-macosx_11_0_arm64.whl.

File metadata

  • Download URL: dotdiff-0.1.1-py3-none-macosx_11_0_arm64.whl
  • Upload date:
  • Size: 588.5 kB
  • Tags: Python 3, macOS 11.0+ ARM64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: uv/0.12.3 {"installer":{"name":"uv","version":"0.12.3","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for dotdiff-0.1.1-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 c3cc5988d2aa5f90f1351ba130c90c1f450a75fdf4955f6c55fed00f794715c4
MD5 c1d480017539c5c137e302ac71c826cf
BLAKE2b-256 a10cbfd14594c6132dc4ed9c6e21c2053f3db6a5eef627e93404ed93b32ecf4f

See more details on using hashes here.

File details

Details for the file dotdiff-0.1.1-py3-none-macosx_10_12_x86_64.whl.

File metadata

  • Download URL: dotdiff-0.1.1-py3-none-macosx_10_12_x86_64.whl
  • Upload date:
  • Size: 628.5 kB
  • Tags: Python 3, macOS 10.12+ x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: uv/0.12.3 {"installer":{"name":"uv","version":"0.12.3","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for dotdiff-0.1.1-py3-none-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 2e007389b05a3fdc5ae0fc4613f6f3b7b11bdee77cf9e2c7dd749c6a61cd03af
MD5 4eedc0f9119e9cc7bc611f78c31c5774
BLAKE2b-256 0ad5f56d03a8c29033f020000ae237658cb849d9542340735672da809a966712

See more details on using hashes here.

Release history Release notifications | RSS feed

This release

0.1.1 This release

5 files

0.1.0

5 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page