# Versions

Every document in the three protocols carries two version numbers. They
answer two different questions: what shape is this, and under what meaning
was it computed.

| Field | Names | Example | Changes when |
|---|---|---|---|
| `schemaVersion` | the shape of the document | `law.core.evaluation/0.2` | a field, a node or an enumeration value appears |
| `semanticVersion` | the meaning it was computed under | `0.2` | a correction changes the meaning while the shape stays |

The two numbers move independently. A document keeps its `schemaVersion`
as long as its shape is unchanged, even if a correction has changed what
the same shape means; the correction then moves `semanticVersion`. The
field definitions live on the schema pages, for example
[`schemaVersion`](/protocols/schemas/evaluation/) in the answer document.

## The six evolution rules

1. Both numbers are present in every message. A document without either
   one is not a document of the protocol.
2. A new field arrives only with a new `schemaVersion`. Documents of the
   earlier version keep their shape and their hashes byte for byte.
3. Enumerations grow only with a new version. `TRUE_ONLY`, `FALSE_ONLY`,
   `BOTH`, `NEITHER` and the evaluation statuses can be matched
   exhaustively: no new value will appear under a version already read.
4. Nothing is removed or renamed. A reader written against an earlier
   version keeps finding every field where it left it.
5. An unknown field is rejected before any computation, not silently
   skipped. A host that sends more than the known shape learns it at once.
6. Types for TypeScript and Python are generated from the schemas, never
   written by hand, so they cannot drift from what the engine accepts.

A host that follows these rules keeps working when a new version appears:
it reads the version it knows and refuses, by name, a document it does
not. The overview of what the protocols carry is on the
[Protocols](https://github.com/arxohq/law/blob/master/docs/protocols/00-overview) page.