The dr-serialize identity contract
A reference for the terms and guarantees that bind dr-serialize.
This is the vocabulary of the identity contract dr-serialize implements: the terms, the guarantees that bind this repo, what is in and out of scope, and the mapping from each term to the names actually exported by dr_serialize.
Terms
| Term | Definition |
|---|---|
| Document | A complete serialized structure governed by a declared schema. |
| Payload | The inner data a document carries; here, always the caller-selected identity data. |
| Hash | Deterministic fixed-length value computed by a declared algorithm over exact declared input bytes; its specific role and semantics come from the qualified term. dr-serialize implements the identity hash specialization. |
| Strict JSON | A value composed only of null, booleans, strings, finite numbers, lists of strict JSON, and string-keyed objects of strict JSON, recursively. Excludes NaN and Infinity — which Python's json module accepts by default but which are not valid JSON — and every other runtime type. |
| Canonical JSON | The single deterministic UTF-8 JSON rendering of a JSON-safe value — compact, sorted keys. The same value always produces the same bytes. |
| Identity Payload | Validated strict-JSON domain data deliberately selected by the caller to contain exactly the fields that determine the object's identity, and none that are incidental runtime or storage state; dr-serialize validates the surrounding document but never selects or infers payload fields. |
| Identity Document | Complete versioned strict-JSON document that carries its own schema name and version, with exactly the shape {schema, schema_version, payload}; the caller selects the identity payload fields inside it, while dr-serialize validates the strict JSON and exact document shape. |
| Canonical Identity JSON | The canonical JSON of a validated identity document. |
| Identity Hash | The full 64-character lowercase SHA-256 hash of the canonical identity JSON of an identity document. |
| Identity Hash Prefix | Display-only leading characters of an identity hash that never establish identity, equality, storage keys, or references. |
| Diagnostic Normalized JSON | The potentially lossy, size- and depth-bounded JSON-safe value produced by the normalization lane (Serializer.to_jsonable) for diagnostics or non-identity storage; never an input to identity hash computation. |
Guarantees
Normalization vs. Identity Lanes Stay Separate. The normalization lane (
Serializer, lossy, policy-driven) and the identity lane (validate_strict_json → IdentityDocument → canonical_identity_json → identity_document_hash, strict, policy-free) never cross: diagnostic normalized JSON never feeds identity hashing.
- Validates strict JSON and the exact identity document shape
{schema, schema_version, payload}. - Rejects non-string object keys, non-finite numbers, and implicit object conversion.
- Rejects all unordered collections (sets, and every non-list/dict container) — ordering is the caller's responsibility; payloads contain only already-ordered lists.
- Renders canonical identity JSON as UTF-8 from the complete identity document, without lossy normalization.
- Computes the full identity hash — a lowercase 64-character SHA-256 value over canonical identity JSON.
- Never selects or infers payload fields — payload selection belongs to the caller.
- Identity hash prefixes are display-only and never establish identity, equality, storage keys, or references.
- Diagnostic
Serializer.to_jsonableoutput is never an identity payload nor a substitute for identity hashes; the identity path never invokes the normalization lane.
In vs. Out of Scope
| In scope | Out of scope |
|---|---|
|
|
Exported Names
Each row maps a term, or a group of supporting exports, to names in dr_serialize.__all__. Every exported name appears exactly once in the names column; there are no aliases or alternate spellings. The terms document, payload, hash, and identity payload name concepts rather than exports, so they have no row.
| Term | Exported names | Note |
|---|---|---|
| Strict JSON | validate_strict_json, StrictJsonError |
Validation returns the value unchanged; rejection raises StrictJsonError carrying the path to the first offending value. |
| Canonical JSON | canonical_json, json_hash |
General-purpose deterministic rendering and hash over already-JSON-safe values, distinct from canonical identity JSON; the lanes compose at the call site as json_hash(serializer.to_jsonable(x)). |
| Identity Document | IdentityDocument, build_identity_document, validate_identity_document, IDENTITY_DOCUMENT_FIELDS, IdentityDocumentError |
Construction itself validates: a malformed document raises IdentityDocumentError, and strict-JSON problems inside the payload raise StrictJsonError. |
| Canonical Identity JSON | canonical_identity_json |
Deterministic compact sorted-key rendering; deliberately not RFC 8785 (JCS). |
| Identity Hash | identity_document_hash, compute_identity_hash |
identity_document_hash takes a validated document; compute_identity_hash validates a raw mapping and hashes it in one call. The same operation as json_hash, restricted to validated identity documents. |
| Identity Hash Prefix | identity_hash_prefix |
Display-only projection of an already-computed identity hash. |
| Diagnostic Normalized JSON | Serializer, Jsonable, JsonableHandler, JsonableHandle, ConversionContext |
Produced by the Serializer.to_jsonable method. Handlers (JsonableHandler, returning a JsonableHandle) extend conversion; ConversionContext carries depth and path state. |
| Serialization limits | SerializationLimits, postgres_jsonb_limits, POSTGRES_JSONB_MAX_BYTES, POSTGRES_JSONB_PAYLOAD_MAX_BYTES |
Explicit size and depth bounds for the normalization lane; the postgres names are a shipped preset for Postgres JSONB storage. |
| Error diagnostics | SerializationError, JsonEncodeError, PayloadTooLargeError, MaxDepthExceededError, ModelDumpError, ObjectVarsSerializationError, ValueTransformError, JsonPath, preview_repr, detail_repr |
One typed taxonomy rooted at SerializationError; the identity-lane members StrictJsonError and IdentityDocumentError are listed with their terms above. Every error carries a JsonPath to the offending value; preview_repr and detail_repr format values for messages. ValueTransformError is the base class for consumer handler failures. |
Scope. This sheet is the authoritative statement of the identity contract dr-serialize implements. Exported names match src/dr_serialize/__init__.py.