25. Normative implementation profile and primitive contracts
v1.4 precedence: Standard 1.4 does not relabel or redigest RecordCore 1.3. Exact v1.4 operational profiles in Sections 33–44, Section 55, and Appendices N–Q supersede conflicting illustrative persistence, proof, receipt, event, cursor, control, and command…
Concept & directionLNK
v1.4 precedence: Standard 1.4 does not relabel or redigest RecordCore 1.3. Exact v1.4 operational profiles in Sections 33–44, Section 55, and Appendices N–Q supersede conflicting illustrative persistence, proof, receipt, event, cursor, control, and command shapes. Appendix D MUST be read through the v1.4 profile and MUST NOT define an alternative contract.
Sections 1–24 define what the substrate means. Sections 25–32 define how a conforming implementation writes, validates, stores, replays and serves that meaning. The contract is technology-neutral but not behavior-neutral: two implementations may choose different databases or programming languages only if canonical bytes, validation outcomes, temporal answers, authorization decisions and receipts remain interoperable.
Normative language
MUST and MUST NOT are conformance requirements. SHOULD identifies a strong default whose deviation requires a recorded rationale. MAY identifies an optional behavior whose presence cannot weaken a MUST. Examples are non-normative unless a fixture says otherwise.#25.1 Contract layers
| Layer | Owns | Must never own |
|---|---|---|
| Semantic kernel | Identity, typed records, time, provenance, correction, evidence, grants and receipts | UI labels, database joins, vendor identifiers or inferred authorization |
| Wire profile | Canonical JSON object shape, exact scalar grammar, media type and digest input | Domain truth beyond the referenced schema and vocabulary lock |
| Graph profile | Subject/object typing, topology, effectivity, cardinality and cross-record invariants | Physical control execution or policy decisions |
| Policy profile | Current principal, action, resource, purpose, audience, context, duties and revocation | Rewriting records or treating ontology inference as permission |
| Persistence profile | Atomic append, idempotency, ordering, outbox and rebuild checkpoints | Product semantics hidden in database triggers |
| Projection profile | Deterministic, versioned read models for a declared audience and as-of time | Authoritative mutation or silent conflict resolution |
| Transport profile | HTTP/event framing, authentication, rate limits, correlation and retry contract | Replacing the canonical record envelope |
#25.2 Primitive scalar profile
| Primitive | Canonical form | Forbidden shortcut |
|---|---|---|
| OpaqueId | lowercase UUID textual form or equivalent 128-bit opaque value | Never contains VIN, serial, tenant, time-zone or vehicle class semantics |
| TermRef | absolute namespaced identifier plus vocabulary version/digest | Human label is presentation metadata, not the stored term |
| SchemaRef | immutable schema identifier, semantic version and content digest | A mutable latest URL is not valid for historical records |
| Timestamp | UTC instant with explicit offset and bounded fractional precision | Leap/clock uncertainty recorded separately; no local time without zone |
| TimeInterval | half-open [start, end) with open end allowed | End precedes start; adjacent intervals do not overlap |
| DecimalString | canonical sign, digits, optional fraction; scale declared by schema | Binary floating-point for money, exact quantity or digest input |
| IntegerString | canonical base-10 integer when range exceeds safe JSON integer | Leading plus or ambiguous leading zeros |
| Money | currency term, exact amount, minor-unit policy and rounding context | Generic price field or currency inference from locale |
| QuantityValue | quantity kind, original value/unit, optional canonical value/unit and uncertainty | Unitless numeric value unless the quantity kind is dimensionless |
| Digest | algorithm identifier plus lowercase encoded digest bytes | Digest alone as proof of identity, truth or authority |
| LanguageString | text, BCP-47 language tag and optional direction | Machine translation overwriting the source string |
| GeoValue | coordinate reference system, axes/order, datum, epoch, uncertainty and privacy class | Bare latitude/longitude pair with assumed frame |
#25.3 Presence and knowledge states
Omission is reserved for a field that is inapplicable to the selected schema branch. A field whose value is relevant but unknown must carry an explicit knowledge state. This prevents missing telemetry, withheld ownership, unsupported adapters and zero-valued measurements from collapsing into null.
| State | Meaning | Projection rule |
|---|---|---|
| known | A value is present and valid under the referenced schema | Return value subject to policy |
| unknown | The question is meaningful but no value is currently established | Return unknown; do not invent default |
| not_observed | Observation could have occurred but did not | Distinguish from sensor failure and zero |
| not_measured | A measurement procedure was not performed | Do not calculate from absent input unless a derivation says so |
| unavailable | Source or service could not provide a value | Expose availability state and retry/freshness metadata |
| withheld | Value exists but policy suppresses it | Return non-leaking withheld marker if audience may know that |
| redacted | Value was removed from this projection or export | Include redaction policy/receipt when allowed |
| disputed | Conflicting evidence remains unresolved | Return conflict set or declared policy choice with explanation |
| unsupported | Adapter or implementation cannot interpret the value | Preserve original bytes and schema reference |
| not_applicable | The question does not apply in this schema/context | Never treat as false, zero or unknown |
#25.4 Canonical serialization and digest boundary
- Reject malformed Unicode, duplicate object keys, non-finite numbers, negative zero and values outside schema limits before normalization.
- Resolve the exact local schema and semantic context by immutable identifier and digest; runtime network resolution is disabled.
- Normalize identifiers, timestamps, decimal lexical forms, term references and unordered-set fields according to the selected schema version.
- Sort object member names according to the canonical JSON profile; preserve array order unless the schema explicitly declares set semantics and a canonical key.
- Encode canonical UTF-8 bytes with no insignificant whitespace and compute recordDigest over the canonical record body, excluding transport headers and mutable signature containers.
- Bind signatures to the digest, schema lock, signer identity, signing purpose, algorithm suite, creation/expiry and key epoch.
- Store original received bytes and media type when required for evidentiary or import fidelity; original bytes and canonical bytes are different artifacts.
Hash equality is narrow
Equal canonical digests prove equal canonical bytes under one profile. They do not prove that two physical assets, claims, photographs or events are the same, true, lawful or authorized.#25.5 Compatibility classes
| Change | Compatibility | Required handling |
|---|---|---|
| Add optional field with explicit default-absence semantics | backward compatible | New writer may emit; old reader preserves extension or ignores only if schema permits |
| Add required field | breaking | New major schema or deterministic upcast with supplied provenance |
| Narrow allowed value/range | breaking for existing data | Corpus scan, exception policy and migration receipt |
| Broaden allowed value/range | reader-forward risk | Declare minimum reader; fixtures for unsupported values |
| Rename term or field | semantic mapping | Stable old identifier, replacement relation and lossless transform |
| Change unit or numeric scale | potentially lossy | Exact conversion rule, rounding method and loss manifest |
| Change truth lane, authority or privacy meaning | never silent | New concept/schema; no aliasing across boundaries |
| Change canonicalization profile | digest-breaking | New profile ID; preserve old digests and dual verification |