Why deterministic serialization matters
When two systems produce different bytes for the same JSON value, signatures break, content-addressed storage diverges, and reproducible builds aren't reproducible. Deterministic serialization is a harder problem than it appears — and the infrastructure that depends on it deserves more than the tests pass as proof.
json-canon is a Go implementation of RFC 8785 JSON Canonicalization Scheme built to that standard. These articles document what it took: the algorithms, the parser, the architectural decisions, and the evidence-based release process that proves the output is actually deterministic.
Each article is self-contained, but together they trace the full arc from specification compliance to provable correctness.
Four articles covering the full engineering arc, from IEEE 754 formatting to evidence-gated releases.
The Burger-Dybvig algorithm in Go — finding the shortest decimal string that round-trips to the original IEEE 754 binary value, with ECMA-262 tie-breaking rules, validated against 286,362 oracle test vectors.
809 lines of Go that enforce every constraint in RFC 8259. Surrogate pair validation, noncharacter detection, duplicate key rejection after escape decoding, and seven independent resource bounds — everything encoding/json silently accepts.
UTF-16 code-unit key sorting, a thirteen-class failure taxonomy with stable exit codes, and machine-readable ABI contracts. The marginal decisions that define whether downstream systems can depend on you without reservations.
Unit tests don't prove determinism. An offline replay harness that runs canonical operations across distributions and architectures, captures cryptographic evidence, and gates releases on byte-identical output.
Lattice Substrate builds foundational infrastructure libraries where correctness is the product. We focus on deterministic data processing, standards-grade conformance tooling, and engineering practices that produce evidence of correctness — not just confidence. github.com/lattice-substrate
json-canon is open source at github.com/lattice-substrate/json-canon. Pure Go, zero external dependencies, 286,362 oracle test vectors, and an offline replay harness that proves byte-identical output across distributions and architectures before every release.