Deterministic Canonicalization & Hashing Specification

2.1 Lexical Key Sorting

• All keys within an object must be sorted in ascending order.
• Sorting is based on the UTF-16 code units of the keys.
• For nested objects, sorting must be applied recursively at every level of the hierarchy.

2.2 Whitespace Minimization

• All insignificant whitespace must be stripped.
• No spaces, tabs, or carriage returns are permitted between keys, values, colons, or commas.
• The output must be a single, contiguous line of text.

2.3 String and Character Escaping

• String values must be encoded in UTF-8.
• Strings MUST be valid Unicode and MUST be preserved exactly as received by the application’s JSON data model. ciaf-json-v1 applies RFC 8785 JCS and does not apply Unicode normalization. Invalid Unicode, including lone surrogate code points, MUST cause canonicalization to fail.
• Only essential control characters (such as \n, \r, \t, \", and \\) must be escaped using their standard backslash sequences.
• Forward slashes (/) must not be escaped.

2.4 Numeric Representation

• Numbers MUST be serialized using the ECMAScript-compatible IEEE 754 double-precision serialization required by RFC 8785. Implementations MUST reject NaN and Infinity. Implementations MUST NOT substitute a custom exponent format, decimal formatter, or locale-sensitive serializer.
• For the procurement or treasury scenario, do not use JSON floats for money. Use integer values for minor units (e.g. "amount_minor": 15000000) or decimal strings (e.g. "amount_decimal": "150000.00") depending on the safe integer constraints of the implementation profile.

2.5 Boolean, Null, and Omitted Optional Fields

• Booleans must be represented as lowercase literal true or false.
• Nulls must be lowercase literal null.
• Schema authors MUST specify whether optional fields are omitted or may be represented as null. Producers MUST construct the intended semantic object before canonicalization. Canonicalization MUST NOT add, remove, default, coerce, or otherwise alter fields.

3.1 Python (json standard library vs. JCS)

The default behavior of Python’s json.dumps() includes whitespace and preserves dict insertion order (or arbitrary hashing order in older versions).

import json
payload = {"status": "APPROVED", "receipt_id": "rcpt_123"}
# Yields: '{"status": "APPROVED", "receipt_id": "rcpt_123"}' (Key order preserved, includes spaces)
serialized = json.dumps(payload)

import json
import jcs # Recommended open-source library

payload = {"status": "APPROVED", "receipt_id": "rcpt_123"}
canonicalized = jcs.canonicalize(payload)

3.2 JavaScript / Node.js

Standard JSON.stringify() does not sort object keys and can vary depending on engine-specific property ordering optimization rules.

const payload = { status: "APPROVED", receipt_id: "rcpt_123" };
const serialized = JSON.stringify(payload); // Yields raw string with original property order

const canonicalize = require('canonicalize'); // RFC 8785 compliant
const payload = { status: "APPROVED", receipt_id: "rcpt_123" };
const canonical_bytes = Buffer.from(canonicalize(payload), 'utf8');

3.3 Go (Golang)

While the standard json.Marshal() sorts map keys alphabetically, it does not automatically apply UTF-8 NFC normalization or enforce the JCS float-to-string conversion algorithm.

import "encoding/json"
// Marshalling raw structs preserves struct field definition order, not lexical order!
bytes, _ := json.Marshal(payloadStruct)

import "github.com/gowebpki/jcs"

// Canonicalize directly into bytes
canonical_bytes, err := jcs.Transform(rawJSONBytes)

3.4 Database Engines (PostgreSQL jsonb Warning)

PostgreSQL jsonb stores data in a parsed binary format that strips insignificant whitespace and deduplicates keys. However, the internal database ordering of keys is based on a binary hash-key representation, which is not alphabetically sorted and differs from RFC 8785.

3.5 Platform Line-Endings

If an evidence payload includes large text blobs (such as LLM prompts, output summaries, or dataset CSV headers):

• Windows runtimes write line-endings as CRLF (\r\n).
• Unix/Linux runtimes write line-endings as LF (\n).
• For fields declared as normalized text content, producers MUST normalize CRLF and CR line endings to LF before constructing the signed payload. This transformation is an application-level semantic rule, not part of RFC 8785 canonicalization.