Spec / open-values-lens
Open Values Lens v0.1
A facts file for one kind of choice, such as banking: the criteria options are scored on, and every option with its scores from 0 to 100 and the source for each score. The site that publishes it keeps it, and anyone can copy it and correct it.
- Files people or tools write
- Status: stable
- Version: none
- Format name in the file:
open-values-lens
Stable. A change that breaks existing files needs a new version. 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 app data loader, app/engine.js, verdict cards, node indexes.
Fields
| Field | What it means | Type |
|---|---|---|
format | "open-values-lens" when present. Conscious Consuming's own facts files leave it out. | always "open-values-lens" |
version | The version of the lens format this file follows, 0.1, when present. | string |
meta required | What the file covers and where its facts come from: its id, name, kind, sources, licence and starting weight settings. | see meta |
criteria required | The things each entry is scored on, such as fossil-fuel financing or fees. Every score key used by an entry must be listed here. | list |
products | The entries being compared, in Conscious Consuming's own facts files. A file has either products or resources, never both. | list |
resources | The entries being compared, in facts files written for other apps that share the format, such as Kosplora's learning resources. A file has either products or resources, never both. | list |
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 lens declares criteria and exactly one entity array.
{
"meta": {
"id": "sample-lens",
"label": "Sample lens",
"type": "Services",
"source": "Conformance fixture"
},
"criteria": [
{
"key": "environment",
"label": "Environment",
"tier": "assessed"
}
],
"products": [
{
"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
Entity score keys must be declared criteria.
{
"meta": {
"id": "sample-lens",
"label": "Sample lens",
"type": "Services",
"source": "Conformance fixture"
},
"criteria": [
{
"key": "environment",
"label": "Environment"
}
],
"products": [
{
"code": "sample-co",
"name": "Sample Co.",
"scores": {
"privacy": 82
},
"provenance": {
"privacy": "No declared criterion."
}
}
]
}
A non-null lens score must carry provenance for that criterion.
{
"meta": {
"id": "sample-lens",
"label": "Sample lens",
"type": "Services",
"source": "Conformance fixture"
},
"criteria": [
{
"key": "environment",
"label": "Environment"
}
],
"products": [
{
"code": "sample-co",
"name": "Sample Co.",
"scores": {
"environment": 82
}
}
]
}
A lens must choose products or resources, not both.
{
"meta": {
"id": "sample-lens",
"label": "Sample lens",
"type": "Services",
"source": "Conformance fixture"
},
"criteria": [
{
"key": "environment",
"label": "Environment"
}
],
"products": [],
"resources": []
}
A lens needs at least one entity in its selected entity array.
{
"meta": {
"id": "sample-lens",
"label": "Sample lens",
"type": "Services",
"source": "Conformance fixture"
},
"criteria": [
{
"key": "environment",
"label": "Environment"
}
],
"products": []
}
The schema
Its address is https://openvaluesstandard.org/schema/lens-v0.1.schema.json. Validators can fetch it there; the file is also in the repository at app/data/standard/schemas/lens.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.