Orthing Episode Schema: Full Auditable Record Contract

The orthing-episode.schema.json is the central schema in Orthemology — it defines the complete contract for the auditable record of one concrete run of the orthing process. Every field an auditor must read to re-derive the verdict must be present and non-empty when record_mode is audit-ready.

All schemas use JSON Schema Draft 2020-12 and reference each other by $id. The episode schema references orthemma.schema.json, metaorthemma.schema.json, and handoff.schema.json via $ref.

Required Fields

Every episode record, regardless of record_mode, must carry these fields:

episode_id

string

required

Unique identifier for this run. Referenced by handoffs and audits.

record_mode

enum

required

Declared audit posture. Either "audit-ready" (triggers the full conditional contract) or "minimal" (an honest partial trace that makes no audit claim).

occurrence

object

required

The input orthemma — references orthemma.schema.json. Must include identity_key and version.

actor

string

required

α — who/what executed (human, validator, model, pipeline, institution). Populated even for mechanical executors.

analysis

object

required

The analysis governing this episode. Required sub-fields: analysis_id and version. Optional: task.

time

string

required

t — the time interval of the episode run (ISO 8601 interval recommended).

placement

object

required

p̂ — the inferred partial profile as an axis-to-value(s) map. Minimum one property.

observation

string | object

required

x = Ω_e(m) — what the episode actually saw. Either a string description or a structured object.

evidence

array

required

H — ordered typed evidence. May be empty, but must be declared. If empty in an audit-ready episode, evidence_absent_reason must be present.

warrant

string | null

required

w — who/what authorized acting, with scope. Distinct from evidence and executor identity. May be null (must be declared).

policy

string | null

required

π — the governing policy or procedure. May be null, but must be declared. If inapplicable, use policy_inapplicable_reason.

verdict_record_ref

string | null

required

Reference to the associated verdict-record.schema.json instance. May be null (must be declared).

The `audit-ready` Conditional Contract

When record_mode is "audit-ready", the schema enforces an additional set of requirements via allOf/if/then:

record_mode: "minimal" is an honest label for a record that does not support audit. It is not a licence to omit the base required fields — those are always required.

An audit-ready episode additionally requires:

actor — non-empty string
time — non-empty string
observation — non-empty (at least one property if object)
claim_ledger_ref — non-empty string referencing the claim ledger
verdict_record_ref — non-empty string
policy as a non-empty string OR policy_inapplicable_reason declared
evidence with at least one item OR evidence_absent_reason declared
placement with at least one property OR candidates with at least one property

Evidence Channels

Each item in the evidence array represents one typed, scoped, expiring evidence item:

evidence[].evidence_id

string

required

Unique identifier for this evidence item within the episode.

evidence[].channel

string

required

The evidence channel type (e.g., "instrument-reading", "record-lookup", "log-scrape").

evidence[].property_class

string

required

The property class this evidence bears on (e.g., "behavioral", "structural").

evidence[].scope

string

required

Which claims, versions, or levels this item can bear on. Mismatch between scope and claim is a EVIDENCE_SUPPORT failure.

evidence[].provenance

string

required

Which process produced this evidence item, and from which (κ, v) occurrence.

evidence[].validity

string

required

Currency conditions or expiry for this evidence item. Stale evidence triggers EVIDENCE_CURRENT failure.

Governing Configuration

governing_configuration

object

Declares which metaorthemes govern this episode and their precedence order.

Show governing_configuration properties

mu_refs

array

Array of {mu_id, mu_version} pairs identifying each governing metaortheme.

precedence

array

Array of two-element pairs [outranks, outranked] defining the strict partial order among metaorthemes. Used when governing configurations conflict.

meta_tokens

array

MetaTok(e) — the metaorthemma configuration tokens for this episode, each referencing metaorthemma.schema.json. An empty array means GOV_TOKEN_ADEQUATE is not in ReqPath(e) (zero-burden rule).

Placement and Candidates

placement

object

required

The inferred partial profile p̂ ∈ Π_A^∂ as an axis-to-value map. Each key is an axis name; values are strings or arrays.

candidates

object

Typed candidate families C⃗. Contains sub-arrays keyed by family type:

Show candidate family types

identity — candidate identity keys
profile — set of complete candidate profiles (each member is an object; never collapse to a single partial profile — that is a type error)
cause — candidate causes
route — candidate routes
warrant_state — enum values: authorized, established, both, neither

Residuals and Lineage

claim_ledger_ref

string

Reference to the claim-ledger.schema.json instance carrying the claim list, residual dispositions, and closure claim for this episode.

evidence_status

object

Per-claim evidence status map. Values: "validated", "provisional", "stale", or "absent".

handoffs_in

array

Inbound handoff packets from predecessor episodes, each a handoff.schema.json instance.

handoffs_out

array

Outbound handoff packets to successor episodes.

action

string | null

a — the action taken by the episode (e.g., "release", "hold", "escalate").

successors

array

Labeled lineage edges Succ(e) pointing to the next occurrence version(s) produced by this episode. Each item has identity_key, version, and action_label.

trace_ref

string | null

Reference to the bounded ordered trace where governance requires one. Granularity is governance-declared.

external_refs

array

Every reference an audit-ready record cites must resolve locally OR be declared here with a registry and resolution_status. resolution_status: "unresolved" is incompatible with record_mode: "audit-ready".

Minimal Example

A minimal valid episode record (non-audit-ready):

episode-minimal.json

{
  "episode_id": "ep-example-001",
  "record_mode": "minimal",
  "occurrence": {
    "identity_key": "item-42",
    "version": "v1"
  },
  "actor": "inspector-1",
  "analysis": {
    "analysis_id": "quality-check-v1",
    "version": "1.0"
  },
  "time": "2026-07-02T10:00:00Z/2026-07-02T10:30:00Z",
  "placement": {
    "quality-status": "acceptable"
  },
  "observation": "visual inspection at all four sides",
  "evidence": [],
  "warrant": "work-order-1001",
  "policy": "SOP-QC-01",
  "verdict_record_ref": null
}

For a fully worked audit-ready episode, see the Pillar Episode example.

Introduction

Core Concepts

Worked Examples

Schemas & Validation

Experiments & Terminology

Orthing Episode Schema: Full Auditable Record Contract

Required Fields

The `audit-ready` Conditional Contract

Evidence Channels

Governing Configuration

Placement and Candidates

Residuals and Lineage

Minimal Example

Build docs developers (and LLMs) love

Introduction

Core Concepts

Worked Examples

Schemas & Validation

Experiments & Terminology

Documentation Index

​Required Fields

​The audit-ready Conditional Contract

​Evidence Channels

​Governing Configuration

​Placement and Candidates

​Residuals and Lineage

​Minimal Example

Build docs developers (and LLMs) love

Required Fields

The `audit-ready` Conditional Contract

Evidence Channels

Governing Configuration

Placement and Candidates

Residuals and Lineage

Minimal Example