Skip to main content

Module extension

contextgraph_types

Module extension 

Source
Expand description

ExtensionValue — this crate’s own JSON value model, for the parts of the wire the reference types deliberately leave open.

§Why a value model here at all

SPEC.md §13 U1 requires a receiver to ignore members it does not recognise, and §13 U3 makes namespaced extension members (vendor:name) a first-class part of the wire. “Ignore” is not “discard”: a host that relays a record, or content-addresses one with record_hash_of, has to carry the members it does not understand through untouched, or it changes the bytes it was handed. So the reference types need somewhere to keep an unmodelled member, and keeping one requires a type that can hold any JSON value.

§Why not serde_json::Value

contextgraph-types is MIT licensed with zero dependencies beyond serde — that promise is in the crate’s Cargo.toml, its README.md, and the lib docs, and it is the reason a third party can implement CGP without adopting the rest of this repository’s dependency tree. serde_json is an optional dependency behind the record-hash feature; record compiles with no features at all. Reaching for serde_json::Value here would mean one of two bad trades:

  • make serde_json non-optional, breaking the zero-dependency promise for every consumer that only wants the wire types; or
  • feature-gate the field, so ContextRecord’s shape — and therefore what it round-trips — would depend on a Cargo feature. A type that silently drops wire members unless a feature is on is a worse version of the defect this exists to fix.

ExtensionValue is the third option: about a hundred lines of serde plumbing, no dependency, and the same shape in every build.

§Fidelity

The variants mirror the JSON data model exactly, including the distinction serde_json::Value draws between an unsigned integer, a signed integer, and a float — because that distinction is what decides whether 7 round-trips as 7 or as 7.0, and a digit that changes changes the digest. An Object is a BTreeMap, so members are held in sorted order; that is invisible to the record hash, which canonicalizes with RFC 8785 (JCS) and sorts members anyway.

Enums§

ExtensionValue
Any JSON value, modelled without a JSON dependency.