Spec / open-values-citation-bundle
Open Values Citation Bundle v0.1
A frozen copy of a facts file, the weights used to rank it and the ranking that came out, so anyone can run the ranking again and check they get the same result.
- Files people or tools write
- Status: stable
- Version: 0.1
- Format name in the file:
open-values-citation-bundle
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 research/create_citation_bundle.js, pipeline/build_site.py. Read by citation pages, grant/preview evidence.
Fields
| Field | What it means | Type |
|---|---|---|
format required | Always "open-values-citation-bundle". Tells a reader that this file is a frozen ranking that can be run again. | always "open-values-citation-bundle" |
version required | The version of the citation bundle format this file follows, 0.1. | string |
id required | The bundle's id, in lower case with hyphens, such as "banking-fossil-free-green". | string |
title required | The bundle's name as shown to people. | string |
createdAt required | The day the bundle was made, as YYYY-MM-DD. | string |
maintainer required | Who looks after the bundle, such as "Values Commons". | string |
license required | The licences that cover the bundle, for the data snapshot and for the explanatory text. | string |
purpose required | One or two sentences saying what question the bundle answers. | string |
rerunCommand required | The command that runs the ranking again and checks it against the expected result, such as "npm run audit:citations". | string |
source required | Where the frozen facts came from and the fingerprints that prove which version they are. | see source |
lensAssumptions required | The settings the ranking was made with: the weights, the criteria, how ties are sorted, and the caveats a reader should keep in mind. | see lensAssumptions |
query required | The question put to the facts: rank the whole file and report the top entries plus a few named ones. | see query |
lensSnapshot required | A full copy of the facts file at the moment the bundle was made, so the ranking can be run again without the live site. | a lens-v0.1 file |
expected required | The result the ranking gave when the bundle was made. Running it again must give the same result. | see expected |
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 citation bundle freezes a lens, query, and expected ranked output.
{
"format": "open-values-citation-bundle",
"version": "0.1",
"id": "sample-bundle",
"title": "Sample citation bundle",
"createdAt": "2026-07-07",
"maintainer": "Values Commons",
"license": "ODbL-compatible fixture",
"purpose": "A minimal reproducible ranking fixture.",
"rerunCommand": "npm run audit:citations",
"source": {
"lensPath": "app/data/sample.json",
"lensId": "sample-lens",
"lensHash": "1234abcd",
"snapshotSha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"engineVersion": "0.10"
},
"lensAssumptions": {
"label": "Sample lens",
"type": "Services",
"valueFrame": "Values-relative ranking, not a universal verdict.",
"disclaimer": "Fixture only.",
"weights": {
"environment": 5
},
"criteria": [
{
"key": "environment",
"label": "Environment",
"tier": "assessed"
}
]
},
"query": {
"kind": "rank-lens",
"focus": "Rank the sample lens.",
"targetCodes": [
"sample-co"
],
"topN": 1
},
"lensSnapshot": {
"meta": {
"id": "sample-lens",
"label": "Sample lens",
"type": "Services",
"source": "Fixture"
},
"criteria": [
{
"key": "environment",
"label": "Environment",
"tier": "assessed"
}
],
"products": [
{
"code": "sample-co",
"name": "Sample Co.",
"scores": {
"environment": 80
},
"provenance": {
"environment": {
"note": "Fixture source.",
"source": "https://example.org/source",
"asof": "2026"
}
}
}
]
},
"expected": {
"engineVersion": "0.10",
"lensHash": "1234abcd",
"snapshotSha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"rankedCount": 1,
"top": [
{
"rank": 1,
"code": "sample-co",
"name": "Sample Co.",
"score": 80,
"tier": "Strong fit",
"why": [
"Environment"
],
"coverage": 1
}
],
"targets": {
"sample-co": {
"rank": 1,
"code": "sample-co",
"name": "Sample Co.",
"score": 80,
"tier": "Strong fit",
"why": [
"Environment"
],
"coverage": 1
}
}
}
}
A file that must be rejected
Citation bundle hashes must be shaped as verifiable hashes.
{
"format": "open-values-citation-bundle",
"version": "0.1",
"id": "sample-bundle",
"title": "Sample citation bundle",
"createdAt": "2026-07-07",
"maintainer": "Values Commons",
"license": "Fixture",
"purpose": "A minimal bad fixture.",
"rerunCommand": "npm run audit:citations",
"source": {
"lensPath": "app/data/sample.json",
"lensId": "sample-lens",
"lensHash": "not-a-hash",
"snapshotSha256": "bad",
"engineVersion": "0.10"
},
"lensAssumptions": {
"label": "Sample lens",
"type": "Services",
"valueFrame": "Values-relative ranking.",
"disclaimer": "Fixture only.",
"weights": {
"environment": 5
},
"criteria": [
{
"key": "environment",
"label": "Environment"
}
]
},
"query": {
"kind": "rank-lens",
"focus": "Rank the sample lens.",
"targetCodes": [],
"topN": 1
},
"lensSnapshot": {
"meta": {
"id": "sample-lens",
"label": "Sample lens",
"type": "Services",
"source": "Fixture"
},
"criteria": [
{
"key": "environment",
"label": "Environment"
}
],
"products": [
{
"code": "sample-co",
"name": "Sample Co.",
"scores": {
"environment": 80
},
"provenance": {
"environment": "Fixture source."
}
}
]
},
"expected": {
"engineVersion": "0.10",
"lensHash": "bad",
"snapshotSha256": "bad",
"rankedCount": 0,
"top": [],
"targets": {}
}
}
The schema
Its address is https://openvaluesstandard.org/schema/citation-bundle-v0.1.schema.json. Validators can fetch it there; the file is also in the repository at app/data/standard/schemas/citation-bundle.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.