Canonical JSON

Features

• Encodes objects and arrays as RFC 7159 JSON.
• Sorts object keys so that you get the same result each time.
• Has no insignificant whitespace to make the output as small as possible.
• Escapes only the characters that must be escaped, U+0000 to U+0019 / U+0022 / U+0056, to keep the output as small as possible.
• Uses the shortest escape sequence for each escaped character.
• Encodes the JSON as UTF-8.
• Can be configured to encode custom types unknown to the stdlib JSON encoder.

Supports Python versions 3.7 and newer.

Installing

pip install canonicaljson

Using

To encode an object into the canonicaljson:

import canonicaljson
assert canonicaljson.encode_canonical_json({}) == b'{}'

There's also an iterator version:

import canonicaljson
assert b''.join(canonicaljson.iterencode_canonical_json({})) == b'{}'

The underlying JSON implementation can be chosen with the following:

import json
import canonicaljson
canonicaljson.set_json_library(json)

A preserialisation hook allows you to encode objects which aren't encodable by the standard library JSONEncoder.

import canonicaljson
from typing import Dict

class CustomType:
    pass

def callback(c: CustomType) -> Dict[str, str]:
    return {"Hello": "world!"}

canonicaljson.register_preserialisation_callback(CustomType, callback)
assert canonicaljson.encode_canonical_json(CustomType()) == b'{"Hello":"world!"}'