Skip to main content

Developer Payload Schema Reference

Metadata​

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

Purpose​

  • Developer reference for how canonical payload schemas are declared, loaded, and enforced.
  • Governance authority remains in contracts/governance/event-sourcing.json.

Machine contracts​

  • contracts/canonical-payload-schema-v1.json
  • contracts/canonical-event-envelope-v1.json
  • contracts/governance/event-sourcing.json
  • contracts/canonical-source-precision-v1.json

Runtime/code anchors​

  • Registry loader: origo/events/payload_schema.py
  • Runtime validation and audit bridge: origo/events/payload_schema_validation.py
  • Shared writer enforcement: origo/events/writer.py
  • Runtime-audit rejection event: origo/events/runtime_audit.py
  • Exchange direct insert callers:
    • control-plane/origo_control_plane/utils/binance_canonical_event_ingest.py
    • control-plane/origo_control_plane/utils/okx_canonical_event_ingest.py
    • control-plane/origo_control_plane/utils/bybit_canonical_event_ingest.py

Key rules​

  • The schema key is (source_id, stream_id, schema_version).
  • domain_event_type remains taxonomy only.
  • Validation runs on the final canonical payload_json string that would be appended.
  • Precision and raw-fidelity remain adjacent contracts.
  • Any live write path that appends canonical rows must validate against the same registry before append.
  • Projector payload assumptions are consumer proof surfaces, not schema authority.
  • Pre-S39 rows with null schema metadata are explicit legacy debt and must not be treated as already covered by the S48 guarantee.