◇ Open Values Standardfor builders

Spec / open-values-door

Open Values Door v0.1

The file a site publishes at /.well-known/open-values.json to say what it offers: which version of the standard it follows, its privacy promises, its licences, and every facts file it publishes with a hash to check it against. 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, federation/discovery clients.

Fields

FieldWhat it meansType
format requiredAlways "open-values-door". Tells a reader that this file is a site's public list of what it publishes.always "open-values-door"
version requiredThe version of the door format this file follows, 0.1.string
generatedAt requiredWhen the site build wrote this file, as an ISO 8601 date and time in UTC, such as "2026-10-13T09:00:00Z".string
self requiredThe address this file is served at, normally the site's /.well-known/open-values.json.see url
publisher requiredWho publishes the site: a name and a web address.see namedUrl
standard requiredWhich version of the Open Values Standard the site follows, and where to read it.object
instance requiredThe app on this site that uses the standard: its name, its role and where its data lives.object
licenses requiredThe licences that cover the site, as web addresses keyed by what they cover, such as code, data, and guides and docs.object
privacy requiredWhat the site does and does not do with the people who use it. Each answer is true or false.object
trustArtifacts requiredAddresses of public records a reader can check, keyed by name, such as the funding ledger and the citation bundles.object
stacks requiredWhere to find fixed copies of each facts file, named by their SHA-256 hash, so a copy can be checked after download.object
agentsOptional. How an AI agent should read this commons: a plain-language summary, and a read-only Model Context Protocol server.object
lenses requiredEvery facts file the site publishes, with where to get it and the hash to check it against.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 well-known door exposes instance, privacy, stack, and lens discovery metadata.

{
  "format": "open-values-door",
  "version": "0.1",
  "generatedAt": "2026-07-07T00:00:00Z",
  "self": "https://valuescommons.org/.well-known/open-values.json",
  "publisher": {
    "name": "Values Commons",
    "url": "https://valuescommons.org/"
  },
  "standard": {
    "name": "Open Values Standard",
    "version": "0.1",
    "url": "https://valuescommons.org/standard/"
  },
  "instance": {
    "name": "Conscious Consuming",
    "role": "reference-instance",
    "url": "https://valuescommons.org/app/",
    "index": "https://valuescommons.org/app/data/index.json"
  },
  "licenses": {
    "data": "https://opendatacommons.org/licenses/odbl/1-0/"
  },
  "privacy": {
    "accounts": false,
    "tracking": false,
    "ads": false,
    "payToRank": false
  },
  "trustArtifacts": {
    "citationBundles": "https://valuescommons.org/citation-bundles/"
  },
  "stacks": {
    "index": "https://valuescommons.org/stacks/index.json",
    "pattern": "https://valuescommons.org/stacks/lens/{id}/{sha256}.json",
    "hash": "sha256"
  },
  "lenses": [
    {
      "id": "banking",
      "title": "Ethical banking",
      "type": "Services",
      "domain": "Money",
      "entries": 25,
      "criteria": [
        "environment"
      ],
      "url": "https://valuescommons.org/app/#explore/banking",
      "data": "https://valuescommons.org/app/data/banking.json",
      "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "integrity": "sha256-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "stack": "https://valuescommons.org/stacks/lens/banking/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json",
      "license": "https://opendatacommons.org/licenses/odbl/1-0/",
      "source": "Fixture",
      "attribution": "Fixture attribution"
    }
  ]
}

A file that must be rejected

Door lens integrity must match the sha256 digest.

{
  "format": "open-values-door",
  "version": "0.1",
  "generatedAt": "2026-07-07T00:00:00Z",
  "self": "https://valuescommons.org/.well-known/open-values.json",
  "publisher": {
    "name": "Values Commons",
    "url": "https://valuescommons.org/"
  },
  "standard": {
    "name": "Open Values Standard",
    "version": "0.1",
    "url": "https://valuescommons.org/standard/"
  },
  "instance": {
    "name": "Conscious Consuming",
    "role": "reference-instance",
    "url": "https://valuescommons.org/app/",
    "index": "https://valuescommons.org/app/data/index.json"
  },
  "licenses": {},
  "privacy": {
    "accounts": false,
    "tracking": false,
    "ads": false,
    "payToRank": false
  },
  "trustArtifacts": {},
  "stacks": {
    "index": "https://valuescommons.org/stacks/index.json",
    "pattern": "https://valuescommons.org/stacks/lens/{id}/{sha256}.json",
    "hash": "sha256"
  },
  "lenses": [
    {
      "id": "banking",
      "title": "Ethical banking",
      "type": "Services",
      "domain": "Money",
      "entries": 25,
      "criteria": [],
      "url": "https://valuescommons.org/app/#explore/banking",
      "data": "https://valuescommons.org/app/data/banking.json",
      "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "integrity": "sha256-bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
      "stack": "https://valuescommons.org/stacks/lens/banking/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json",
      "license": "https://opendatacommons.org/licenses/odbl/1-0/",
      "source": "Fixture",
      "attribution": "Fixture attribution"
    }
  ]
}

The schema

Its address is https://openvaluesstandard.org/schema/door-v0.1.schema.json. Validators can fetch it there; the file is also in the repository at app/data/standard/schemas/door.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.