Run Lifecycle
An OORS document is terminal by default: without a run object, the document is the authoritative record of the run that produced it — exactly the pre-v0.2.1 semantics. Producers of long-running executions (multi-step pipelines, large batch jobs) can opt in to progressive reporting by adding the run object and emitting interim snapshots while the run is still going.
Example
Interim snapshot
A pipeline that has completed step 12 of 14 reports the step's observation and marks the document as an interim snapshot of a running execution. source.runId is required so consumers can correlate the documents of one run.
apiVersion: v0.8.1
kind: ObservabilityResults
id: 1c40b98e-5a7d-4d2e-9f31-8b6c2e0a4f77
observedAt: "2026-07-07T20:15:51Z"
source:
process: imdb-silver
runId: silver-1783398037701
run:
state: running
sequence: 12
progress:
current: 12
total: 14
unit: steps
results:
- id: rows_title_alias
type: metric
name: title_alias
status: pass
dimension: volume
target:
resourceType: table
resourceIdentifier: title_alias
measure:
metric: rows_loaded
value: 58518276
unit: rows
{
"apiVersion": "v0.8.1",
"kind": "ObservabilityResults",
"id": "1c40b98e-5a7d-4d2e-9f31-8b6c2e0a4f77",
"observedAt": "2026-07-07T20:15:51Z",
"source": {
"process": "imdb-silver",
"runId": "silver-1783398037701"
},
"run": {
"state": "running",
"sequence": 12,
"progress": { "current": 12, "total": 14, "unit": "steps" }
},
"results": [
{
"id": "rows_title_alias",
"type": "metric",
"name": "title_alias",
"status": "pass",
"dimension": "volume",
"target": { "resourceType": "table", "resourceIdentifier": "title_alias" },
"measure": { "metric": "rows_loaded", "value": 58518276, "unit": "rows" }
}
]
}
Terminal document
The same run's final document — state: completed (or simply no run object at all) — carries the full summary and supersedes every interim snapshot with the same source.runId.
apiVersion: v0.8.1
kind: ObservabilityResults
id: efa58843-12ec-418b-963d-40dda853f856
observedAt: "2026-07-07T20:43:31Z"
source:
process: imdb-silver
runId: silver-1783398037701
run:
state: completed
sequence: 15
progress:
current: 14
total: 14
unit: steps
results:
- id: run
type: check
name: Silver build run
status: pass
Field Descriptions
| Key | Type | UX label | Required | Description | Example |
|---|---|---|---|---|---|
run |
object | Run | No | Run lifecycle object. Absent ⇒ the document is terminal (authoritative record of the run — the pre-v0.2.1 behavior). | |
run.state |
string | State | Yes (in run) |
running — interim snapshot, more documents will follow for this source.runId. completed — terminal, the run finished. aborted — terminal, the run ended before producing its full results. |
running |
run.startedAt |
string (ISO 8601) | Started At | No | The moment in time when the run started. Together with observedAt, it gives the duration of the run. |
2026-07-07T19:58:12Z |
run.sequence |
integer | Sequence | No | Monotonically increasing ordinal of this document within the run. Consumers SHOULD order by sequence when present, falling back to observedAt. |
12 |
run.progress |
object | Progress | No | Progress indicator for the run. | |
run.progress.current |
number | Current | Yes (in progress) |
The amount of progress made so far, e.g., steps completed. | 12 |
run.progress.total |
number | Total | No | The total amount expected, e.g., total steps. Omit when unknown. | 14 |
run.progress.unit |
string | Unit | No | The unit of progress, e.g., steps, tables, files, percent. |
steps |
Semantics
- Terminal by default. A document without a
runobject, or withrun.stateofcompletedoraborted, is terminal: the authoritative record for itssource.runId. Every pre-v0.2.1 document is therefore already valid and terminal — nothing to migrate. - Interim snapshots. A document with
run.state: runningis a partial snapshot of a run still in progress. Consumers MUST NOT treat it as the run's outcome.source.runIdis required on interim documents (enforced by the JSON schema) so they can be correlated. - Supersession. A terminal document supersedes all interim documents sharing its
source.runId. The run's outcome is the terminal document's top-levelstatus, or, when absent, derived from itsresultsby the rule in Overall status —run.statedescribes the lifecycle, not the quality outcome.abortedmeans only "no full summary is coming"; producers SHOULD still include a failingcheckdescribing why when they can. - Observations stand alone. Each result in an interim document is a real observation that individually passed or failed —
results[].statuskeeps its exact meaning. No new status values are introduced. - Ordering. Consumers SHOULD order a run's documents by
run.sequencewhen present, falling back toobservedAt. Producers SHOULD makesequencestrictly increasing perrunId.
Consumer guidance (non-normative): a run whose latest document says
runningand that has produced no new document for an implementation-defined window may be rendered as stale — the wire format deliberately carries no heartbeat or timeout.