◇ Open Values Standardfor builders

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.

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

FieldWhat it meansType
key requiredThe 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 requiredThe name shown to people for this criterion in this file, such as "Fossil-fuel financing".string
tierHow 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"
sourceWhere 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
descriptionA 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.