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.
- Parts of other formats
- Status: stable
- Version: 0.1.0
- Format name in the file:
open-values-entity
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
| Field | What it means | Type |
|---|---|---|
code required | The 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 required | The name shown to people, such as "Triodos Bank". | string |
brand | The brand or maker, or a short kind label where there is no brand, such as "ethical bank". | string |
description | One or two plain sentences saying what the entry is. | string |
scores required | The 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 |
provenance | How 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 |
links | Links about the entry, such as its own website, each with a label and a URL. | list |
region | Where 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 |
focuses | Plain 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 |
allergens | Allergen 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 |
allergensDeclared | True 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.