Skip to content

Record versions

An evidence bundle written today must be readable, and reproducible, by every later Mokili. A record is named by the digest of its content, so this is also a promise about digests: a record never changes, and a later Mokili never reads it as if it did.

Every record says which format it follows: "schema": "mokili.model/1". The number after the slash is the record's version. Four rules govern it.

The four rules

1. An addition that is optional, and absent when unused, stays in the same version. A new field is left out of a record that does not use it, so a record written before the field existed keeps its digest. Examples in /1: a model's sources, an FMU model's inputs, a scenario's observed_measurement, a bundle's parts.

2. Anything else is a new version. A field that is renamed or removed, becomes required, changes meaning or unit, or gains a default written into every record, makes /2. The new version is published beside the old one.

3. A stored record is never rewritten. Mokili reads every version it has published. A record in /1 stays in /1, with its digest, for as long as anyone keeps it.

4. The published formats are filed by version, and held to.

  • The JSON Schemas are in schemas/v1/ of mokili-core; a /2 goes to schemas/v2/.
  • tests/archive/v1/ of mokili-core holds one record of every kind, written when /1 was published and never rewritten. A test reads each one back and fails if it would come out different: a changed digest, a field the schema refuses.
  • The archived evidence bundle is reproduced by every test run: an old bundle gives the same result digest.

What a reader sees

A record in a version this Mokili does not read yet is refused with unknown_schema, and the message says so:

mokili.model/2 is a version this Mokili does not read (it reads mokili.model/1); a newer Mokili wrote it

Introducing a /2

When a change needs a new version:

  1. Add the new record type beside the old one; the old one stays, unchanged, and Mokili keeps reading it.
  2. Publish its schema under schemas/v2/ of mokili-core (lakisa schema ../mokili-core/schemas).
  3. Write the archive for the new version once: python tests/archive/make_archive.py in mokili-core: python tests/archive/make_archive.py v2.
  4. Give Mokili a way to carry a /1 record forward. The carried record is a new record with its own digest; it names the one it came from, and the old one remains valid evidence.

No record kind is at /2 yet, so no such carrying exists.