An OCP document is one JSON object that describes one orchestration run.
Smallest valid document

​
Top-level fields

​
"0.3"
required
Protocol version. This schema validates exactly version 0.3; v0.2 documents validate against ocp-v0.2.schema.json and v0.1 documents against ocp-v0.schema.json. A v0.3 reader accepts all three.
​
Producer
required
​
Privacy
required
​
Run
required
​
Group[]
Optional named visual/organizational scopes, such as projects. Grouping is orthogonal to dependency structure.
​
Node[]
required
The units of work. A gate is a node whose kind is gate.
​
Edge[]
Directed edges over node ids. dep and fan_in edges together must form a DAG; spawn, launch and artifact edges record discovered lineage and may form cycles.
​
Attempt[]
Flat list of tries, each pointing at its node. Attempts are records, not counters; a retry is a new attempt.
​
Artifact[]
Files (or other addressable outputs) that one attempt produced and other attempts consumed. The handoff objects between attempts; the run records who wrote and who read them, never their content.
​
Event[]
Optional append-only provenance log, ascending in time.
​
Ext

​
Requirements

  • A document MUST be a JSON object (E002) whose ocp field names a supported version (E003), and it MUST validate against that version’s schema (E010).
  • nodes, edges, attempts, artifacts, events and groups MUST be arrays when present (E104).
  • Ids MUST be unique within their array: node ids (E100), attempt ids (E101), group ids (E102) and artifact ids (E103). Ids are scoped to the producer and SHOULD stay stable when the same run is written again.
  • Every timestamp MUST be an ISO 8601 / RFC 3339 date-time with an explicit offset. The schema checks the shape only, not that the date and time exist (checker limits).
  • A consumer MUST ignore fields it does not know, at every level.
  • Every entity MAY carry an ext object for producer-specific data; see Extensions.

​
Vocabularies

String vocabularies are open sets with a recommended list: a producer MAY write other values, a consumer MUST accept them, and a checker MAY warn (W200). These are closed enums, and a value outside them is an error: Free-text fields (titles, reasons, receipts, details, evidence notes) are short labels written by the producer, and the schema caps them at 500 characters. It does not cap other strings, such as task.features values, setting options and ext payloads. Under metadata_only a string MUST NOT contain prompt, completion or transcript text, whether capped or not; see Privacy.

​
Producer

The producer block names the software that wrote the document, so a consumer can group runs by where they came from and trace a bad field back to its source.
​
string
required
The emitting software (plugin or converter), e.g. my-orchestrator-ocp. loopmath’s log extractor names itself loopmath (dagr in documents written before its rename), optionally suffixed after a non-word character, e.g. loopmath/graph; that name switches on the extractor-only rule E171 (cost.basis measured).At most 200 characters.
​
string
At most 100 characters.
​
string
The orchestration framework the run executed under, e.g. my-orchestrator, claude-code, langgraph, crewai.At most 200 characters.
​
string
At most 100 characters.
​
string
Upstream native format this document was derived from, e.g. my-orchestrator/1.2.At most 200 characters.
​
Timestamp
​
object
Elements this producer can emit. A false value promises that the corresponding element is absent from this document. Unknown boolean keys are producer extensions.
​
Ext
  • capabilities says which elements the producer can write. A false value promises the element is absent from this document (E180); a missing key means unknown.
  • A producer SHOULD declare capabilities (W180). Without it, a consumer cannot tell “this tool does not record edges” from “this run had no edges”.
  • A converter SHOULD set source_contract to the native format it read, so consumers can tell converted documents from native ones.

Privacy