◇ Open Values Standardfor builders

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.

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

FieldWhat it meansType
format requiredNames the file format. Always open-values-register-snapshot.always "open-values-register-snapshot"
version requiredThe version of this format the file follows. Always 1.0.0.always "1.0.0"
snapshotId requiredThis 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 requiredThe 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 requiredHow the bytes were fetched, copied from the register's access on the shelf: api, bulk or page.one of "api", "bulk", "page"
capturedAt requiredWhen the capture was made, as a UTC date and time.string
request requiredWhat was asked for, recorded so the same request can be repeated. Secret header values are never stored.object
response requiredWhat came back, with the facts needed to check the saved payload has not changed.object
license requiredThe terms the register publishes its data under.object
parser requiredThe 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.