# Versions in practice

> Which version to write, how readers handle older documents, and how to migrate.

The `ocp` field names the version a document follows. The current version is **0.3**.

## Write the latest, read them all

- **Producers** write the latest version. 0.3 is a strict superset of 0.2: every field 0.3 adds is optional, so a 0.2 writer becomes a 0.3 writer by changing the `ocp` field, unless it writes a name that 0.3 defines as a field of its own (for example a string in `run.task`, which 0.3 defines as an object). 0.2 is not a superset of 0.1: 0.2 requires `tier` on every edge.
- **Consumers** read every published version (0.1, 0.2 and 0.3), each by the schema and rules of the version it declares, and ignore fields they do not know.

## Migrate older documents

`loopmath ocp migrate` upgrades 0.1 and 0.2 documents to 0.3. It writes the 0.3 form, never changes its input, and returns its input unchanged when run on its own output. A 0.1 document needs it: raising only its `ocp` value fails on edges without a `tier`.

```bash
loopmath ocp migrate old-run.ocp.json --out migrated/
```

```text Output
PASS  old-run.ocp.json -> /work/migrated/old-run.ocp.json  (from 0.1; 0 errors, 1 warning)
```

A migration only adds fields that are absent: a tier on untiered 0.1 edges, a task inferred from run labels, provenance `logged`, and a configuration with `source: habit`, plus the workflow when loopmath can infer one. It records where the document came from in `run.ext["dev.loopmath.migration"]`. See [Migration](https://orchestrationcontextprotocol.io/specification/0.3/versioning#migration).

## Deprecation

A field is removed only after a deprecation notice that names its replacement and stays in the specification for at least two minor versions. The one deprecation today is loopmath's pre-rename extension namespace `dev.dagr.`, read with warning [W182](https://orchestrationcontextprotocol.io/specification/0.3/conformance#w182) through 0.4.

## Tracking changes

The [changelog](https://orchestrationcontextprotocol.io/specification/0.3/changelog) lists what each version added. This site holds the 0.3 text, and `/specification/latest` points to it. The schemas for 0.1 and 0.2 are in the repository: [ocp-v0.schema.json](https://github.com/loopmath/loopmath/blob/main/spec/ocp-v0.schema.json) and [ocp-v0.2.schema.json](https://github.com/loopmath/loopmath/blob/main/spec/ocp-v0.2.schema.json).