jcs

Overview ¶

Package jcs implements RFC 8785 (JSON Canonicalization Scheme) using only the Go standard library.

Canonical JSON is the invariant byte sequence cryptographic operations (signing, hashing) need: whitespace-free, keys recursively sorted by UTF-16 code unit, the minimal ECMAScript escape set for strings, and IEEE 754 numbers serialized exactly as ECMAScript's Number::toString would (1e21 → "1e+21", 1e-7 → "1e-7", -0 → "0").

Two entry points:

• CanonicalizeJSON canonicalizes raw JSON bytes. Parsing is strict beyond RFC 8259 where JCS requires it: duplicate object keys, unpaired surrogate escapes, invalid UTF-8, control characters in string literals, and literals that overflow to ±Infinity are all errors. Use this on untrusted input (a verifier canonicalizing a received document).
• Canonicalize canonicalizes an in-memory Go value (maps, slices, structs, strings, numbers) by round-tripping it through encoding/json first. It inherits encoding/json's behavior of silently replacing invalid UTF-8 in strings with U+FFFD; for untrusted strings, parse with CanonicalizeJSON instead. NaN and ±Infinity are rejected.

Numbers follow the I-JSON subset (RFC 7493): every JSON number is parsed to an IEEE 754 double and re-serialized. An integer beyond 2^53 therefore rounds like any other double (RFC 8785 Appendix D recommends carrying such values as strings instead). Integers that underflow the double range (1e-400) canonicalize to 0; literals that overflow to ±Infinity (1e999) are rejected, as JCS does not permit Infinity in JSON.

The output is deterministic for equal input values: object keys are collected and sorted before anything is written, never emitted in map-iteration order.