Spec / open-values-stack-index
Open Values Stack Index v0.1
A list of fixed copies of a site's facts files, each named by the SHA-256 hash of its contents, so a copy can be checked after download. The site's build writes it.
- Published bundles
- Status: stable
- Version: 0.1
- Format name in the file:
open-values-stack-index
Stable. A change that breaks existing files needs a new version. A file published for others to download and use.
Who writes it and who reads it
Written by pipeline/build_site.py. Read by mirrors, citation clients, federation/discovery clients.
Fields
| Field | What it means | Type |
|---|---|---|
format required | Always "open-values-stack-index". Tells a reader that this file lists fixed copies of facts files. | always "open-values-stack-index" |
version required | The version of the stack index format this file follows, 0.1. | string |
generatedAt required | When the site build wrote this file, as an ISO 8601 date and time in UTC. | string |
sourceDoor required | The address of the site's door file (/.well-known/open-values.json) that points to this index. | string |
hash required | Always "sha256": the hash used to name and check each copy. | always "sha256" |
description required | A sentence for readers saying what the index holds and that each copy's hash should be checked before it is trusted. | string |
lenses required | One row for each fixed copy of a facts file. | 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 stack index lists content-addressed lens copies.
{
"format": "open-values-stack-index",
"version": "0.1",
"generatedAt": "2026-07-07T00:00:00Z",
"sourceDoor": "https://valuescommons.org/.well-known/open-values.json",
"hash": "sha256",
"description": "Content-addressed Open Values lens copies.",
"lenses": [
{
"id": "banking",
"sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"integrity": "sha256-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"path": "/stacks/lens/banking/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json",
"url": "https://valuescommons.org/stacks/lens/banking/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json",
"canonicalData": "https://valuescommons.org/app/data/banking.json",
"license": "https://opendatacommons.org/licenses/odbl/1-0/"
}
]
}
A file that must be rejected
Stack paths must be content-addressed by lens id and sha256.
{
"format": "open-values-stack-index",
"version": "0.1",
"generatedAt": "2026-07-07T00:00:00Z",
"sourceDoor": "https://valuescommons.org/.well-known/open-values.json",
"hash": "sha256",
"description": "Content-addressed Open Values lens copies.",
"lenses": [
{
"id": "banking",
"sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"integrity": "sha256-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"path": "/stacks/lens/other/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json",
"url": "https://valuescommons.org/stacks/lens/banking/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json",
"canonicalData": "https://valuescommons.org/app/data/banking.json",
"license": "https://opendatacommons.org/licenses/odbl/1-0/"
}
]
}
The schema
Its address is https://openvaluesstandard.org/schema/stack-index-v0.1.schema.json. Validators can fetch it there; the file is also in the repository at app/data/standard/schemas/stack-index.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.