spec/OCP.md also says:
- The JSON Schema (draft 2020-12) for the document’s version, including the meaning its description strings give each field. The schema reference renders them.
- The numbered rules JSON Schema cannot express, listed on Conformance and in section 6 of
spec/OCP.md. Each has a code, and each 0.3 rule has a pass file and a fail file among the examples.
loopmath ocp validate, tests a document against both. A checker is not the authority either: where it disagrees with the schema or the rules, the checker is wrong. A requirement stated only in prose is normative too, but no checker tests every one, so a clean result does not prove that a document meets them all; see what the reference checker does not test.
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this specification are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
Status
OCP is in its 0.x line. 0.3 is a strict superset of 0.2: every field 0.3 adds is optional. 0.2 is not a superset of 0.1, because 0.2 requires
tier on every edge, so 0.1 documents need loopmath ocp migrate. See the versioning promise.
Roles
- A producer is software that writes OCP documents: an orchestrator, an agent harness, an exporter plugin, or a converter from another log format.
- A consumer is software that reads them: a cost analysis, a dashboard, a run comparison, or a learner such as loopmath.
Conformance
- A conforming document validates against the schema of the version its
ocpfield names, and breaks none of the error rules in Conformance. - A conforming producer writes only conforming documents, declares its privacy profile truthfully, and never labels evidence stronger than it has (see evidence tiers).
- A conforming consumer accepts every conforming 0.1, 0.2 and 0.3 document, ignores fields and extension namespaces it does not know, and applies the readings this specification gives for absent fields. It reads each document by the schema and rules of the version the document declares.
Design
File based. A run is one JSON document at a path, complete at rest. There is no daemon, endpoint or database. Attempts, edges, artifacts and events are flat top-level arrays rather than structures nested in nodes, so a producer extends a run by appending records. A small required core. Five things are required: the version, the producer’s name, the privacy profile, the run id and the node list. Everything else is optional and typed when present, so a tool that knows only “these steps ran with these models and these tokens” can write a valid document on day one and add the rest later. Evidence, not assertion. Every edge and every inferred label carries an evidence tier that says how it is known; an outcome may say how it is known, and one that does not is treated as asserted. A producer never raises a tier without new mechanical evidence. Costs say whether they were measured for the attempt or allocated from a coarser total. Private by default. Every document declares a privacy profile, and themetadata_only profile, which forbids prompt, completion and transcript text, is the one most producers use.
Producer agnostic. Node ids are stable and never runtime locators. Model labels keep the producer’s raw string, and mapping them to canonical ids is the consumer’s job.