◇ Open Values Standardfor builders

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.

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

FieldWhat it meansType
format requiredAlways "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 requiredThe version of the citation bundle format this file follows, 0.1.string
id requiredThe bundle's id, in lower case with hyphens, such as "banking-fossil-free-green".string
title requiredThe bundle's name as shown to people.string
createdAt requiredThe day the bundle was made, as YYYY-MM-DD.string
maintainer requiredWho looks after the bundle, such as "Values Commons".string
license requiredThe licences that cover the bundle, for the data snapshot and for the explanatory text.string
purpose requiredOne or two sentences saying what question the bundle answers.string
rerunCommand requiredThe command that runs the ranking again and checks it against the expected result, such as "npm run audit:citations".string
source requiredWhere the frozen facts came from and the fingerprints that prove which version they are.see source
lensAssumptions requiredThe 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 requiredThe question put to the facts: rank the whole file and report the top entries plus a few named ones.see query
lensSnapshot requiredA 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 requiredThe 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.