◇ Open Values Standardfor builders

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.

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

FieldWhat it meansType
format requiredAlways "open-values-stack-index". Tells a reader that this file lists fixed copies of facts files.always "open-values-stack-index"
version requiredThe version of the stack index format this file follows, 0.1.string
generatedAt requiredWhen the site build wrote this file, as an ISO 8601 date and time in UTC.string
sourceDoor requiredThe address of the site's door file (/.well-known/open-values.json) that points to this index.string
hash requiredAlways "sha256": the hash used to name and check each copy.always "sha256"
description requiredA sentence for readers saying what the index holds and that each copy's hash should be checked before it is trusted.string
lenses requiredOne 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.