Skip to main content

Canonical Payload Schema Reference

Metadata​

  • Owner: Origo Engineering
  • Last updated: 2026-04-14
  • Slice/version reference: S48

Purpose and scope​

  • User-facing and operator-facing reference for canonical payload-schema authority at the write boundary.
  • Scope covers stream-scoped payload-schema declarations, schema-version immutability, write-time validation, and the legacy pre-S39 boundary.

Authoritative surfaces​

  • Registry: contracts/canonical-payload-schema-v1.json
  • Envelope metadata source: contracts/canonical-event-envelope-v1.json
  • Runtime enforcement: origo/events/writer.py
  • Validation helper for direct insert paths: origo/events/payload_schema_validation.py

Key rules​

  • Payload schema authority is keyed by (source_id, stream_id, schema_version).
  • domain_event_type is taxonomy only and is not the schema key.
  • JSON Schema is the schema format.
  • The validation target is canonical post-precision payload_json.
  • Raw-fidelity and precision validation remain separate gates and are not replaced by schema validation.
  • Invalid payloads fail before canonical append.
  • Writer-mediated paths and direct fast/staged insert paths must use the same schema gate.
  • Pre-S39 rows with null domain_event_type or null schema_version are legacy rows and are outside the new universal guarantee until replayed.

Operator meaning​

  • A schema rejection is a hard pre-append failure.
  • Runtime-audit emits canonical_payload_schema_rejection for schema-gate failures.
  • Schema-version freeze means a registered schema version is never mutated in place; changes require a new version.