Crate kanonak_codec 

kanonak-codec — the generic, ontology-independent codec runtime (Rust port).

Given a CodecSchema (the per-package metadata a generated SDK embeds) and a set of typed nodes, it builds the canonical input model and content-addresses it via kanonak-canonical (the same content-form the Python/TypeScript references and the kanonak hash CLI produce). It also (de)serializes the normalized-JSON wire form. Self-contained: carriers come from the schema’s datatype URIs, and the resolved foundation URIs are embedded by the generator, so hashing needs no runtime ontology resolution.

A node is a plain JSON object (serde_json::Map<String, serde_json::Value>) — the $-envelope plus alias-collapsed local-name fields. A generated typed model serializes to one. Note: serde_json::Value (the node field model) is distinct from kanonak_canonical::Value (the canonical-input value enum).

Structs

EnumMemberMatch

An enumeration member found by enum_member. #[non_exhaustive]: read its fields; a later 1.x release may add one.

KanonakNode

The $-envelope as data — composed into a generated struct via #[serde(flatten)], so an instance carries its own identity and serializes straight to the normalized-JSON wire form. extra holds open-world assertions outside the type-model, keyed by predicate URI; being the innermost flatten map, it also collects unknown wire fields on deserialize.

Enums

CodecError

Errors raised by the codec runtime. Fails loudly — no fallbacks.

Ref

An object property’s value: EXACTLY ONE of a reference to a named resource (its canonical URI) or an embedded node (the value itself, carried inline — derived identity, no $id). The typed twin of the wire form’s {"$ref": uri} vs embedded-node distinction; the choice between the arms is authorial and hash-relevant, so it is explicit here, never inferred.

Traits

KanonakResource

Implemented by generated typed structs (over their flattened KanonakNode) so the runtime can read/write an instance’s envelope — what lets Ref::to_resource resolve identity and Ref::embed_named carry the authored dict-key.

Functions

build_package

Build the canonical input model: a subject per node + the synthesized package-wrapper subject (raw label + Package type), exactly the subject set kanonak hash produces for the equivalent authored package.

canonical_form

The canonical form (the {subjects:[...]} JSON) of a package from nodes.

content_hash

The sha256: content hash of a package from nodes — matches kanonak hash.

deserialize

Parse normalized JSON into a typed node. $-envelope keys and fields modeled on the node’s $type stay top-level; every other key is collected into $extra so a strongly-typed consumer round-trips it losslessly. Requires $type (the one field that cannot be inferred) and a class in the schema that can read it: the exact class, or the same class at a compatible later version (runtime#28 — see type_matches for the same rule). The node keeps the $type it was WRITTEN with; the producer’s bytes are the producer’s.

enum_member

The enumeration member a {"$ref": …} names (runtime#28): the exact versioned key first, then the same member at a version that can read the written one — so a member referenced at an earlier compatible version of the package resolves against a later schema. None when this schema has no such member, which, as for enums itself, means “not mine”, never “invalid”.

serialize

Serialize a typed node to its normalized-JSON wire form. $extra entries ride as sibling fields after the modeled ones; a modeled field wins a name collision ([JsonExtensionData] semantics). No $extra key on the wire. Fallible since 0.4.0: an invalid $types envelope (at any depth) is a producer bug and fails at emit time, as does a fragment reference (runtime#6).

to_node

A typed instance’s codec node (the dictionary contract). The bridge is native serde: the instance serializes to its normalized-JSON wire form (envelope-as-data + Ref<T> values), and the wire form maps onto the node contract through the SAME split deserialize defines — one contract, not two.

type_matches

Whether a node is an instance of the class class_uri — what a generated type guard asks (runtime#28). Each of the node’s types ($types, else its $type) is resolved through the same compatible lookup deserialize uses, so a node written at an earlier compatible version satisfies the later version’s guard; it matches when that class IS class_uri or has it among its ancestors. Classes compare by versionless identity. A type this schema cannot read (unknown, newer, another major) never matches. Errors when class_uri is not a class coordinate or the schema is malformed. For a typed instance, KanonakNode::type_matches asks the same question of its envelope.

Type Aliases

Node

A node is a JSON object.