Spec / open-values-value-editorial
Open Values Value Editorial v0.4
The sourced explanations shown on each value's page, such as Organic or Repairability: what the value requires, who checks it, where it stops and how the site uses it in scores. Conscious Consuming keeps it.
- Files people or tools write
- Status: draft
- Version: 0.4.0
- Format name in the file:
open-values-value-editorial
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/build_datasets.py. Read by #value/<key>, app-design handoff H22.
Fields
| Field | What it means | Type |
|---|---|---|
format required | Always "open-values-value-editorial". Tells a reader that this file holds the explanations shown on value pages. | always "open-values-value-editorial" |
version required | The version of this file's format, 0.4.0. | string |
updated required | The day the file was last changed, as YYYY-MM-DD. | string |
state required | Which batch of writing the file holds. Always "environmental-durability-batch" in this version. | always "environmental-durability-batch" |
purpose required | One or two sentences saying what the file is for. | see nonEmptyString |
renderRule required | The rule the app follows when showing entries: which entries may be shown, and what to show for a value that has none. | see nonEmptyString |
requiredValues required | The keys of the fifteen values that have a page in the app, in the app's order. Every one must have an entry. | list |
pilotValues required | The keys of the five values that were written first. They must stay in entries. | list |
entries required | One explanation for each value, keyed by the value's key, such as "organic". | map of see entry |
This format allows no fields beyond the list above. A writer MUST NOT add any.
The schema
Its address is https://openvaluesstandard.org/schema/value-editorial-v0.4.schema.json. Validators can fetch it there; the file is also in the repository at app/data/standard/schemas/value-editorial.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.