What Is JSON Canonicalization?
JSON documents representing the same logical data can be serialised in many different ways. Object keys may appear in any order. Numbers may be formatted as 1.0, 1, or 1.0e0. Whitespace is optional. For most applications this flexibility is a feature, but it becomes a problem when you need to hash or digitally sign a JSON document: two semantically equivalent JSON strings produce different hash values.
JSON canonicalization solves this by defining a single deterministic serialisation for any JSON value. Given the same input data, every conforming implementation produces the identical byte sequence — making cryptographic operations reproducible and verifiable.
RFC 8785 in Brief
Published by the IETF in September 2020, RFC 8785 (the JSON Canonicalization Scheme, JCS) specifies two main rules:
- Key sorting: Object keys are sorted in ascending Unicode code point order (lexicographic by UTF-16 code units, matching ECMAScript's string comparison).
- Number normalisation: Numbers are serialised using the shortest round-trip IEEE 754 double-precision representation, matching how modern JavaScript engines (V8, SpiderMonkey) serialise floats.
Arrays preserve their order. Strings are serialised using standard JSON escaping. The output is always UTF-8 with no BOM and no trailing newline.
Growing Adoption in 2023
Three years after publication, a 2023 survey of package registries found RFC 8785 implementations in over 15 languages including JavaScript, Python, Java, Go, Rust, C#, Ruby, Swift, Kotlin, and PHP. Several were published as official libraries by the RFC's authors; others emerged independently from the open-source community.
Notable adopters include digital credential systems (W3C Verifiable Credentials use JCS as one of their canonicalization options), JOSE (JSON Object Signing and Encryption) toolkits, and select government e-signature frameworks in Europe where deterministic JSON signing is required by regulation.
The growing implementation surface is an indicator of maturity — the standard is sufficiently stable and useful that independent teams are investing in supporting it.
Implementing JCS
For most use cases you should reach for an existing library rather than implementing JCS from scratch. The number normalisation algorithm in particular (IEEE 754 shortest round-trip) is subtle and has corner cases around -0, Infinity (which JCS prohibits), and very large or very small doubles.
If you need to implement JCS yourself, the reference implementation in JavaScript at cyberphone/json-canonicalization includes annotated source and a conformance test suite. The test suite is the best resource for verifying correctness of a new implementation.