Reference tooling

Tooling · 1.0-rc

Two Python scripts. No packaging, no framework, no surprises.

These are the reference implementations of the spec's own checks. Both are single files you can read end to end, and both accept either a plain-vault directory or a .canpuff.zip (Core §8).

validate-vault.py Conformance: manifest, journal files, catalog Markdown round-trip rules, attachment content-addressing, referential integrity. download
diff-vaults.py Semantic equivalence of two vaults, at the spec's stated equivalences — the round-trip test. download

Usage · needs jsonschema and pyyaml

# Does this vault conform?
python3 validate-vault.py my-vault/
python3 validate-vault.py export.canpuff.zip

# Did the round trip lose anything?
python3 diff-vaults.py before.canpuff.zip after.canpuff.zip --verify-hashes

validate-vault.py exits 0 when the vault conforms, 1 on conformance errors, 2 on usage or environment problems. Warnings are spec-tolerated conditions worth surfacing — dangling references, unknown types — not failures.

Testing your own implementation? Point the tools at the conformance fixtures: edge-heavy valid vaults and deliberately broken ones, each with the expected verdict recorded in expected.json, plus run-fixtures.py to check a validator against all of them at once. The fixtures ship in the repository rather than on this site — some of them contain malformed YAML on purpose, which is precisely the sort of thing a site generator refuses to build.