RFC 8785 (JSON Canonicalization Scheme)

Common errors

• rfc8785.CanonicalizationError: Non-string object keys are not supported.

  cause Attempting to serialize a dictionary with non-string keys (e.g., integers, tuples) directly.
  fix Convert all dictionary keys to strings before passing the data to `rfc8785.dumps` or `rfc8785.dump`.

• TypeError: Object of type X is not JSON serializable

  cause Input data contains types not supported by standard JSON, or custom objects without a defined serialization method. This is a common Python JSON serialization error, also applicable here.
  fix Ensure all data types are standard JSON-compatible (strings, numbers, booleans, null, lists, dictionaries). Custom objects or unsupported types must be converted before canonicalization.

• rfc8785.IntegerDomainError: The given integer exceeds the true integer precision of an IEEE 754 double-precision float, which is what JSON uses.

  cause An integer in the input data exceeds the maximum safe integer precision for an IEEE 754 double-precision float.
  fix For very large integers that exceed IEEE 754 precision, convert them to strings in your input data before canonicalization, as per common JSON practices for large numbers.

Warnings

• breaking As of v0.1.3, the library explicitly raises `CanonicalizationError` when encountering non-string dictionary keys, rather than attempting implicit conversion or silent failure.
  Fix: Ensure all dictionary keys in the input data are strings before passing to `rfc8785.dumps` or `rfc8785.dump`.
• gotcha All API functions (`dumps`, `dump`) produce UTF-8 encoded `bytes` objects or write to `bytes` I/O, not standard Python `str` objects. You must decode the output if a string is required.
  Fix: Call `.decode('utf-8')` on the result of `rfc8785.dumps` if a string is needed (e.g., `rfc8785.dumps(data).decode('utf-8')`).
• gotcha The library enforces strict number serialization according to ECMAScript's IEEE 754 double-precision float representation, raising `IntegerDomainError` or `FloatDomainError` for integers exceeding this precision or floats like NaN/Infinity.
  Fix: Ensure numbers adhere to IEEE 754 double-precision standards. Large integers or special float values (NaN, Inf) must be serialized as strings in the input data if they are not representable.
• gotcha rfc8785.py explicitly does not support indentation or pretty-printing. The output is always minimally encoded as required by JCS.
  Fix: Do not expect or attempt to configure `rfc8785` for human-readable output; its purpose is machine-readable canonicalization.

Install

• pip install rfc8785 Install stable version

Imports

• dumps

  import rfc8785
  canonical_json = rfc8785.dumps(...)

  The primary function for canonicalizing a Python object to bytes.
• dump

  import rfc8785
  with open('file.jcs', 'wb') as f:
      rfc8785.dump(my_data, f)

  For direct canonicalization to a bytes I/O sink.
• CanonicalizationError

  from rfc8785 import CanonicalizationError
  try:
      ...
  except CanonicalizationError as e:
      ...

  Base exception for all errors during canonicalization.

Quickstart

Demonstrates how to use `rfc8785.dumps` to get the canonical byte representation of a Python dictionary. The output is always UTF-8 encoded bytes with keys sorted lexicographically, and specific number and literal serialization as per RFC 8785.

import rfc8785

data = {
    "name": "Alice",
    "age": 30,
    "isStudent": False,
    "courses": ["Math", "Science"],
    "address": {
        "city": "New York",
        "zip": "10001"
    }
}

canonical_bytes = rfc8785.dumps(data)
print(canonical_bytes.decode('utf-8'))