tallipoika

A stable son (Finnish: tallipoika) — a JSON Canonicalization Scheme (JCS) implementation conforming to RFC 8785.

Requires Python 3.11 or later.

Install

pip install tallipoika

For a faster JSON parser on large input (msgspec-backed; parsing only, canonicalization is unaffected), install the fast-parse extra:

pip install 'tallipoika[fast-parse]'

Manual

The man page provides the CLI reference (man tallipoika after placing the file on your MANPATH):

mkdir -p ~/.local/share/man/man1
cp docs/man/tallipoika.1 ~/.local/share/man/man1/

Quickstart

Run tallipoika with no arguments for a usage summary, or tallipoika --version to check the installed version.

The library function for canonical JSON is canonicalize:

from tallipoika.api import canonicalize

result = canonicalize({"b": 2, "a": 1})
# b'{"a":2,"b":1}'

To serialize without key sorting, use serialize:

from tallipoika.api import serialize

result = serialize({"b": 2, "a": 1})
# b'{"b":2,"a":1}'

The command line tool reads JSON from a file or stdin and writes to a file or stdout:

tallipoika --in-path input.json --out-path output.json
echo '{"b":2,"a":1}' | tallipoika
# {"a":2,"b":1}

RFC 8785 compliance

tallipoika implements the JSON Canonicalization Scheme (JCS) defined by RFC 8785:

• UTF-8 output: all output is UTF-8 encoded bytes.
• No whitespace: no indentation, no spaces around : or ,.
• Key sort by UTF-16BE byte order: object keys are sorted by their UTF-16BE encoding, which matches the ES6 String.prototype.localeCompare ordering used by JCS-compliant implementations.
• ES6 §7.1.12.1 number serialization: floats are serialized using the shortest representation that round-trips through the ES6 number parsing algorithm.
• NaN and Infinity rejected: allow_nan=False by default per RFC 8785 §3.2.2.3.
• Control character escaping: code points U+0000–U+001F are escaped as \uXXXX.
• Unicode passthrough: non-ASCII characters above U+001F pass through verbatim (ensure_ascii=False by default).

API

canonicalize(obj, utf8=True) -> bytes

Produce RFC 8785 JCS-canonical JSON for obj. Raises ValueError for NaN or Infinity float values. Raises TypeError for non-serializable objects.

serialize(obj, utf8=True) -> bytes

Produce JSON without key sorting; all other RFC 8785 rules (number format, control-character escaping, no whitespace) still apply.

JSONEncoder

The underlying encoder class with JCS defaults:

from tallipoika.api import JSONEncoder

encoder = JSONEncoder(sort_keys=True)
output = encoder.encode({"b": 2, "a": 1})
# '{"a":2,"b":1}'

Constructor keyword arguments and their JCS defaults:

Argument	JCS default	Description
skipkeys	False	Skip non-string keys instead of raising TypeError
ensure_ascii	False	Escape non-ASCII; disabled for Unicode passthrough
check_circular	True	Raise ValueError on circular references
allow_nan	False	Reject NaN/Infinity per RFC 8785 §3.2.2.3
sort_keys	True	Sort object keys by UTF-16BE byte order
indent	None	No indentation
separators	(',', ':')	No whitespace around , or :
default	None	Custom serializer for non-standard types

CLI

tallipoika [--in-path PATH] [--out-path PATH] [--serialize-only] [--no-fast-parse] [--version]

Option	Default	Description
--in-path PATH	stdin	Input JSON file; also accepted as positional argument
--out-path PATH	stdout	Output path; writes bytes when path given, text to stdout
--serialize-only	off	Serialize only — do not sort keys
--no-fast-parse	off	Disable the msgspec fast parser (if installed); use json instead
--version, -V	—	Print version string and exit

Design and requirements

Document	Identifier	File
Software Requirements Specification	TAL-SRS-001	docs/requirements/srs/
Software Design Description	TAL-SDD-001	docs/design/sdd/

Both documents follow the MIL-STD-498 DID structure.

Bug Tracker

Any feature requests or bug reports shall go to the todos of tallipoika.

Primary Source repository

The main source of tallipoika is on a mountain in Central Switzerland under configuration control (fossil).

Contributions

If you like to share small changes under the repositories license please kindly do so by sending a patchset. You can send such a patchset per email using git send-email.

Support

Please kindly submit issues at https://todo.sr.ht/~sthagen/tallipoika or write plain text email to ~sthagen/tallipoika@lists.sr.ht to support. Thanks.

Security Policy

See SECURITY.md for the security policy.

Changes

See docs/releases/ for release summaries and docs/releases/changes/ for the detailed change log.

Coverage

The test suite maintains high branch coverage (≥97%). The HTML report (if generated) is in site/coverage/.

SBOM

Runtime dependency information is published in docs/sbom/ in SPDX 3.0 (JSON-LD) and CycloneDX 1.6 (JSON) formats. See docs/sbom/README.md for the component inventory and validation guide.