Spec / open-values-criterion
Open Values Criterion v0.1
One thing the options in a facts file are scored on, such as fossil-fuel financing or fees, with a key, a name and a note on how its scores were made.
- Parts of other formats
- Status: stable
- Version: 0.1.0
- Format name in the file:
open-values-criterion
Stable. A change that breaks existing files needs a new version. Not a file on its own: a shape used inside other formats.
Who writes it and who reads it
No writer is listed. Read by open-values-lens, open-values-category-index.
Fields
| Field | What it means | Type |
|---|---|---|
key required | The criterion's id, in lower case with _ between words, such as "environment". Entries use it as the key in their scores and provenance. Reusing a key that other files use joins this criterion to the same value across the site. | string |
label required | The name shown to people for this criterion in this file, such as "Fossil-fuel financing". | string |
tier | How the scores on this criterion were made. "measured" is an open-data fact such as a price or a Nutri-Score, shown exactly. "certified" is a third-party certification such as B Corp. "assessed" is a researched judgement, shown as a band rather than an exact number, and each score should cite its source. Missing is read as "assessed". | one of "measured", "certified", "assessed" |
source | Where the scores on this criterion come from as a whole, either a short label for scores researched by hand or the name of an open database. | string |
description | A sentence saying what this criterion measures. | string |
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.
A file that passes
Criterion keys are stable snake-case ids with labels.
{
"key": "environment",
"label": "Environmental impact",
"tier": "assessed",
"source": "curated"
}
A file that must be rejected
Criterion keys cannot start uppercase or contain spaces.
{
"key": "Bad Key",
"label": "Bad key"
}
The schema
Its address is https://openvaluesstandard.org/schema/criterion-v0.1.schema.json. Validators can fetch it there; the file is also in the repository at app/data/standard/schemas/criterion.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.