A pure Elixir implementation of RFC 8785: JSON Canonicalization Scheme (JCS).

JCS assigns every I-JSON-compatible value a single canonical byte representation, so logically equivalent valid inputs hash and sign identically. Schemes that sign JSON by value depend on this property, among them the JCS cryptosuites of W3C Data Integrity (eddsa-jcs-2022, ecdsa-jcs-2019).

iex> RFC8785.encode!(%{"b" => 100.0, "a" => "hello\tworld"})
~S({"a":"hello\tworld","b":100})

iex> RFC8785.encode!(%{"numbers" => [1.0e21, 1.0e-7, 0.000001]})
~S({"numbers":[1e+21,1e-7,0.000001]})

Canonical form

Output follows RFC 8785, Section 3.2:

• Numbers serialize exactly as ECMAScript's Number::toString (Section 3.2.2.3). The shortest round-tripping digits come from Erlang/OTP's Ryu implementation; the ECMA-262 NumberToString rules determine the notation.
• Strings use the escapes \b, \t, \n, \f, \r, lowercase \u00hh for the remaining C0 controls, \", and \\ (Section 3.2.2.2). All other permitted code points, including U+007F and non-ASCII, appear unescaped in UTF-8. Unicode noncharacters are rejected as required by I-JSON.
• Object names sort by UTF-16 code units (Section 3.2.3), which orders names containing surrogate pairs correctly.
• The output contains no whitespace (Section 3.2.1).

Input mapping

Atoms

Atoms other than nil, true, and false encode as their name string. Note the consequence for :null: OTP's :json.decode/1 yields that atom for JSON null by default, and it encodes here as the string "null" — not the null literal. Decode with decode!/1 (or any decoder that maps null to nil) before re-encoding.

Integers

RFC 8785 represents every number as an IEEE-754 double. Integers within ±2^53 serialize as their exact digits, which is identical to their serialization through a double. A larger integer is accepted only when the canonical form of its nearest double reproduces the integer's decimal digits. Integers parsed from canonical JCS output always satisfy this, so decoding a canonical document and re-canonicalizing it reproduces the same bytes. An integer that fails the check, such as 9007199254740993 (nearest double: 9007199254740992), raises RFC8785.EncodeError; convert it to a float first if the altered digits are acceptable, or encode it as a string to keep them.

Rejected input

Structs, tuples, non-UTF-8 binaries, strings containing Unicode noncharacters, map keys that are neither strings nor atoms, improper lists, and maps whose keys collide after atom-to-string coercion raise RFC8785.EncodeError. The error message names the offending value's location in JSONPath style, such as $.credential.amounts[3].

NaN and Infinity need no handling: Erlang floats cannot represent them.

JSON text input

canonicalize!/1 accepts a JSON text instead of Elixir terms, as when verifying a hash or signature over a received document. It decodes with OTP's :json parser and enforces I-JSON on the way in: duplicate object names and Unicode noncharacters raise RFC8785.DecodeError rather than being silently accepted or altered. Number tokens that decode to IEEE-754 negative zero are also rejected, following RFC 8785 erratum

7920. A programmatically supplied -0.0 float still encodes as 0, as required by ECMAScript Number::toString.

Number tokens with a fraction or exponent are decoded to IEEE-754 doubles, as required by RFC 8785. Canonicalization preserves their numeric double value rather than their original spelling or every decimal digit.

iex> RFC8785.canonicalize!(~S({"b": 2.50, "a": "\u20ac"}))
~S({"a":"€","b":2.5})

When the document must be modified between parsing and canonicalizing — the W3C Data Integrity JCS cryptosuites, for instance, remove the proof member before hashing the rest — decode with decode!/1, which applies the same parser-side strictness, and re-encode the modified terms:

iex> doc = RFC8785.decode!(~S({"claim": null, "proof": {"v": "..."}}))
iex> doc |> Map.delete("proof") |> RFC8785.encode!()
~S({"claim":null})

A parser is a safe substitute here only if its term mapping and validation preserve the same data. OTP's :json.decode/1, for example, yields the atom :null for JSON null, which encode!/1 then encodes as the string "null"; it also silently keeps the first of two duplicate object names. Successful decoding does not guarantee that the resulting term can be encoded: encode!/1 still applies term-side checks such as the digit-preserving integer rule.

Resource limits

When canonicalizing JSON text, an integer token with more than 21 magnitude digits is rejected before constructing a bignum, because it cannot preserve those integer digits in canonical JCS output. decode!/1 remains a general decoding API and does materialize such tokens as arbitrary-precision integers.

The library does not impose an overall document byte, nesting-depth, or member-count limit. Callers handling untrusted documents must enforce application-appropriate input limits, as advised by RFC 8785, Section 5.

Requirements

Erlang/OTP 29 or later, checked at compile time, and Elixir 1.20.2 or later.