CANONICALJSON(3) Library Functions Manual CANONICALJSON(3)

CanonicalJsonAn extension of JSON that produces the Matrix spec's canonical JSON.

#include <CanonicalJson.h>

CanonicalJsonEncode(HashMap *, FILE *);

char *
CanonicalJsonEncodeToString(HashMap *);

CanonicalJson is an extension of Json(3) that is specifically designed to produce the Matrix specification's "canonical" JSON.

Canonical JSON is defined as JSON that:

The regular JSON encoder has no such rules, because normally they are not needed. However, Canonical JSON is needed to consistently sign JSON objects.

() encodes a JSON object following the rules of Canonical Json. See the documentation for (), documented in Json(3) for more details on how JSON encoding operates. This function exists as an alternative to JsonEncode(), but should not be preferred to it in most circumstances. It is a lot more costly, as it must lexicographically sort all keys and strip out float values. If at all possible, use JsonEncode() because it is much cheaper both in terms of memory and CPU time.

() encodes a JSON object to a string. Json(3) doesn't have any way to send JSON to a string, because there's absolutely no reason to handle JSON strings in most cases. However, the sole reason Canonical JSON exists is so that JSON objects can be signed in a consistent way. Thus, you need a string to pass to the signing function.

CanonicalJsonEncode() returns whether or not the JSON encoding operation was sucessful. This function will fail only if NULL was given for any parameter. Otherwise, if an invalid pointer is given, undefined behavior results.

CanonicalJsonEncodeToString() returns a C string containing the canonical JSON representation of the given object, or NULL if the encoding failed.


November 30, 2022 Telodendria Project