Spec / open-values-register-snapshot
Open Values Register Snapshot
A record of one download from a public register: what was asked for, when, what came back, and a hash of the saved bytes so anyone can check they have not changed. The capture tool writes it, and later builds read the saved copy instead of going back to the internet.
- Files people or tools write
- Status: draft
- Version: 1.0.0
- Format name in the file:
open-values-register-snapshot
Draft. It may still change before it is called stable. A file someone writes by hand or with a tool, and keeps.
Who writes it and who reads it
Written by pipeline/registers/snapshot.py. Read by register adapters, offline register parsers, future deterministic evidence generation.
Fields
| Field | What it means | Type |
|---|---|---|
format required | Names the file format. Always open-values-register-snapshot. | always "open-values-register-snapshot" |
version required | The version of this format the file follows. Always 1.0.0. | always "1.0.0" |
snapshotId required | This snapshot's id: the capture date, then the first 12 characters of a SHA-256 hash of the rest of the manifest (leaving out format, version, snapshotId and the payload file name). The manifest and payload file names start with it, so a changed capture gets a new id. | string |
registerId required | The id of the register this was captured from. It must match a register id in content/registers.json and the folder the snapshot sits in. | string |
access required | How the bytes were fetched, copied from the register's access on the shelf: api, bulk or page. | one of "api", "bulk", "page" |
capturedAt required | When the capture was made, as a UTC date and time. | string |
request required | What was asked for, recorded so the same request can be repeated. Secret header values are never stored. | object |
response required | What came back, with the facts needed to check the saved payload has not changed. | object |
license required | The terms the register publishes its data under. | object |
parser required | The parser expected to read this payload into observations, and its version. | object |
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-snapshot-v1.schema.json. Validators can fetch it there; the file is also in the repository at app/data/standard/schemas/register-snapshot.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.