Canonical JSON (PCJ-1)¶
All hashes are computed over canonical bytes, so the same data hashes the same in every language and on every platform.
Rules¶
- UTF-8, no byte-order mark, no whitespace between tokens, no trailing newline in the hashed bytes.
- Object keys are unique and sorted by Unicode code point. Duplicate keys in input are an error.
- Allowed values: object, array, string, boolean, null, and integers in [-(2^53 - 1), 2^53 - 1].
- No floats. Write decimals as strings (
"0.001").-0is the integer0. - Strings may contain any Unicode except lone surrogates. Escapes are only
\",\\,\b,\f,\n,\r,\tand\u00XXfor other control characters below U+0020; everything else is written literally. - Nesting depth is at most 64 (the top-level container counts as 1).
sha256(x) is the lowercase 64-character hex SHA-256 of the canonical bytes of x.
What it means for your files¶
Your protocol.json and record.json may be pretty-printed. They are parsed strictly (a byte-order mark,
duplicate keys, floats or numbers beyond the integer range are errors) and re-serialised canonically before
hashing and storing.
| Input | Result |
|---|---|
{"b":1,"a":2} |
stored as {"a":2,"b":1} |
{"t": 0.5} |
rejected, FLOAT_NOT_ALLOWED |
{"a":1,"a":2} |
rejected, DUPLICATE_KEY |
| file starting with a byte-order mark | rejected, BAD_JSON |
Specification and vectors¶
The normative text is section 2 of the core specification. Language-neutral test cases
are in spec/vectors/canonical.json; see conformance vectors.
In Python: protocolith.core.encode, decode and sha256_hex.