◇ Open Values Standardfor builders

Spec / open-values-entity

Open Values Entity v0.1

One option inside a facts file, such as a bank or a shampoo: its name, its scores from 0 to 100 on the file's criteria, and the source for each score. A score that is missing is unknown, not 0.

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-dataset.

Fields

FieldWhat it meansType
code requiredThe entry's id, unique inside its facts file and stable over time, so other files can point at it. For food and beauty items it is the product barcode.string
name requiredThe name shown to people, such as "Triodos Bank".string
brandThe brand or maker, or a short kind label where there is no brand, such as "ethical bank".string
descriptionOne or two plain sentences saying what the entry is.string
scores requiredThe entry's score on each criterion of the facts file, from 0 to 100, keyed by the criterion's key. A criterion that is missing is unknown, not 0. Every key must be declared in the file's criteria.map of a rating-v0.1 file
provenanceHow each score is known, keyed by the same criterion keys as scores. Each value is either a short note or a citation with note, source link and date.map of a source-v0.1 file
linksLinks about the entry, such as its own website, each with a label and a URL.list
regionWhere the entry is available: US, UK, EU, or global. The app's region filter keeps entries for the chosen region plus the global ones.list of string
focusesPlain labels the entry carries, such as "Vegan", "Fair Trade" or "B Corp". The app matches them against the diet and preference rules a person has set, and searches them.list of string
allergensAllergen tags the product contains or may carry traces of, such as "milk" or "gluten". They come from the product's source data and, where that has none, from a keyword scan of the ingredients. An empty list does not mean the product is free of allergens.list of string
allergensDeclaredTrue when the product's source data declares its allergens. False means there was no declared allergen data, so the allergens list may be incomplete and a reader should check the label.boolean

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

A minimal entity has code, name, sparse scores, and optional provenance.

{
  "code": "sample-co",
  "name": "Sample Co.",
  "scores": {
    "environment": 82
  },
  "provenance": {
    "environment": {
      "note": "Public impact report.",
      "source": "https://example.org/impact",
      "asof": "2026"
    }
  }
}

A file that must be rejected

Entities need a scores object, even when sparse.

{
  "code": "sample-co",
  "name": "Sample Co."
}

The schema

Its address is https://openvaluesstandard.org/schema/entity-v0.1.schema.json. Validators can fetch it there; the file is also in the repository at app/data/standard/schemas/entity.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.