Canonical JSON

Object keys are serialized in lexicographic order based on their UTF-16 code unit values. This eliminates the non-determinism inherent in standard JSON, where key order is arbitrary.

• Keys are sorted by comparing Unicode code points
• Nested objects are recursively sorted
• Ensures {"b":2,"a":1} and {"a":1,"b":2} produce identical byte sequences

All insignificant whitespace is stripped from the output. No spaces, tabs, newlines, or carriage returns appear outside of string literals.

• No indentation or pretty-printing
• No trailing whitespace after commas or colons
• Produces the most compact valid JSON representation

String values are normalized using Unicode Normalization Form C (NFC) before serialization. This ensures that characters composed of combining marks are represented consistently.

• Prevents hash mismatches from equivalent Unicode representations
• Applies to both keys and string values
• Critical for internationalized data integrity

Numbers are serialized with no leading zeros, no trailing decimal points, and using E notation for exponents. The integer 1.0 becomes 1, and 1E+2 becomes 100.

• No exponential notation unless required for magnitude
• No + sign on positive exponents
• Ensures 1.0, 1e0, and 1 all canonicalize to 1

Characters are escaped using the minimum required escape sequence. Control characters use uppercase hex in \u notation, and the solidus / is never escaped.

• \b, \f, \n, \r, \t for standard control characters
• \u00XX for other control characters (uppercase hex)
• Double-quote and backslash always escaped

Canonical JSON is the canonicalization scheme used by RFC 8785 (JCS). It enables reliable digital signatures and content hashing where byte-level determinism is mandatory.

• Used in Verifiable Credentials and DID Documents
• Enables content-addressable storage for JSON payloads
• Foundation for tamper-evident data structures

The mathematical process that converts arbitrary data into a fixed-size digest. Canonical JSON is a prerequisite for deterministic hashing because even semantically identical JSON can produce different byte sequences. Common algorithms include SHA-256 and BLAKE3. A single whitespace change in non-canonical JSON yields a completely different hash, breaking integrity verification.

A storage paradigm where data is retrieved by its cryptographic hash rather than a mutable location. Systems like IPFS and OCI registries use this model. Canonical JSON ensures that the same logical manifest always resolves to the same content address. If serialization is non-deterministic, the address changes and the lookup fails.

A cryptographic mechanism that binds an identity to a document. The signer hashes the canonical form and encrypts the digest with a private key. Verifiers recompute the hash from the same canonical bytes. Without deterministic serialization, a verifier may compute a different hash than the signer, causing valid signatures to fail verification.

A tree data structure where each leaf node is a hash of a data block and each non-leaf node is a hash of its children. Used in blockchains and transparency logs like Rekor. Canonical JSON is critical for leaf data: if two participants serialize the same transaction differently, they compute different Merkle roots and cannot reach consensus.

A cryptographically signed statement asserting a verifiable fact about an artifact. In in-toto and SLSA frameworks, attestations are serialized as JSON. Canonicalization ensures that the predicate (the claim being made) is byte-identical across signers, verifiers, and transparency logs, preventing signature verification failures due to formatting differences.