RFC 8785: JSON Canonicalization Scheme (JCS)

The Problem: Non-Deterministic Serialisation

JSON objects have no defined key order. Two JSON libraries serialising the same in-memory data structure can produce different byte sequences:

// Library A
{"name":"Alice","age":30}

// Library B
{"age":30,"name":"Alice"}

Both are valid JSON. Both represent the same data. But their SHA-256 hashes are different. If you sign the output of Library A and a recipient verifies with Library B, the signature check fails — even though the data is identical. For cryptographic operations over JSON documents, you need exactly one canonical form.

How JCS Works

RFC 8785 specifies a two-step transformation that converts any JSON value into a canonical byte sequence:

1. Serialise the JSON value according to the JCS rules (key sorting, number normalisation, standard string escaping, no extra whitespace).
2. Encode the resulting string as UTF-8 bytes with no BOM.

The output is a valid JSON document. Applying JCS to the output of JCS produces the identical bytes — it is idempotent. Any JSON parser can read JCS output; it just looks like ordinary compact JSON with alphabetically ordered keys.

Number Normalisation and Key Sorting

Key sorting uses Unicode code point order for key strings, matching ECMAScript's built-in string comparison. Numeric keys sort before alphabetic ones; uppercase before lowercase. The sort is applied recursively to all nested objects.

Number normalisation converts all JSON numbers to their shortest round-trip IEEE 754 double-precision representation. This is the same format used by JSON.stringify in modern JavaScript engines. Consequences:

• 1.0 becomes 1
• 1.0e3 becomes 1000
• 1.5e-4 becomes 0.00015

Infinity, -Infinity, and NaN are not valid JSON and are rejected by JCS.

Applications: Signatures and Hashing

The primary use case for JCS is digital signatures over JSON documents. By canonicalising before signing, both signer and verifier produce the same byte sequence regardless of which library or language they use.

Notable adoption:

• W3C Verifiable Credentials uses JCS as a canonicalization option for JSON-LD documents
• Several European e-signature frameworks reference JCS for JSON-based qualified signatures
• JOSE (JSON Object Signing and Encryption) toolkits include JCS as a payload hashing step

JCS is also useful outside of cryptography anywhere a stable hash of a JSON document is needed — cache keys, content-addressable storage, or change detection in configuration management. For a practical look at comparing JSON documents semantically (with key-order normalisation), see How to Compare Two JSON Files.