Spec / open-values-lens-patch
Open Values Lens Patch v0.1
A list of corrections to one facts file: changed scores and added options, each with its source. Written by fact repair (workshop/index.html) and applied by app/engine.js mergeLens, which checks the fingerprint first.
- Files people or tools write
- Status: draft
- Version: 0.1
- Format name in the file:
open-values-lens-patch
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
No writer is listed. Read by workshop/index.html, app/engine.js mergeLens.
Fields
| Field | What it means | Type |
|---|---|---|
format required | Always open-values-lens-patch, so a reader knows what the file is. | always "open-values-lens-patch" |
version required | The version of this format the file follows. | string |
target | The id of the facts file these changes are for. | string |
baseHash | The fingerprint of the facts file the changes were made against. A reader warns when it differs from the file they hold, because the changes may no longer fit. | string |
by | Whatever name or label the sender typed. It is not checked, so it is not proof of who sent it. | string |
note | The sender's reason for the changes, read first by whoever decides whether to apply them. | string |
created | When the file was saved, as an ISO date and time. | string |
ops required | The changes, in the order they were made. | list |
A reader MUST ignore fields it does not know, so a file can carry more than this list and still be read. A writer MUST NOT change what a listed field means.
The schema
Its address is https://openvaluesstandard.org/schema/lens-patch-v0.1.schema.json. Validators can fetch it there; the file is also in the repository at app/data/standard/schemas/lens-patch.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.