Spec / open-values-register-evidence-bundle
Open Values Register Evidence Bundle
Citations ready to go into the catalogue, built from one register download, its matched options and its parsed facts, plus a sample of entries a person must check by hand. The evidence builder writes it, and reviewers and the promotion step read it.
- Files built from other files
- Status: draft
- Version: 1.0.0
- Format name in the file:
open-values-register-evidence-bundle
Draft. It may still change before it is called stable. A file a build step makes from other files. Change the sources, not this file.
Who writes it and who reads it
Written by pipeline/registers/build_evidence.py. Read by register evidence review, future lens promotion.
Fields
| Field | What it means | Type |
|---|---|---|
format required | Names the file format. Always open-values-register-evidence-bundle. | always "open-values-register-evidence-bundle" |
version required | The version of this format the file follows. Always 1.0.0. | always "1.0.0" |
registerId required | The id of the register the evidence comes from, from content/registers.json. | string |
criterion required | The criterion key these entries would fill in a lens, copied from the register's provenanceKey on the shelf. | string |
snapshot required | The verified snapshot the evidence was read from. | object |
generatedFrom required | The input files, each with the SHA-256 hash of its bytes, and the generator version. Any change to an input changes a hash and means the bundle must be rebuilt and reviewed again. | object |
counts required | Totals for the bundle. | object |
reviewRequirement required | The entries a person must check by hand before the bundle can be approved. | object |
entries required | One entry per catalogue option the snapshot covers, sorted by cid then entityCode. | list |
This format allows no fields beyond the list above. A writer MUST NOT add any.
The schema
Its address is https://openvaluesstandard.org/schema/register-evidence-bundle-v1.schema.json. Validators can fetch it there; the file is also in the repository at app/data/standard/schemas/register-evidence-bundle.schema.json.
The key words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY are used as described in RFC 2119 and RFC 8174 when, and only when, they appear in capitals.
Whether this format fits your app is your call. The spec says what a file MUST hold. Which formats you read and write, and what your app does with them, is yours to decide.