Spec / open-values-governance-ledger
Open Values Governance Ledger v0.1
The file that holds every proposed change to the project's data and every public response to those proposals, kept at content/governance/proposals.json. People write it by hand; pipeline/build_proposals.js reads it to build the governance index, and the governance audit checks it. It runs no live votes.
- Files people or tools write
- Status: draft
- Version: 0.1.0
- Format name in the file:
open-values-governance-ledger
Draft. It may still change before it is called stable. A file someone writes by hand or with a tool, and keeps.
Who writes it and who reads it
No writer is listed. Read by audit:governance, generated governance index, future governance relay.
Fields
| Field | What it means | Type |
|---|---|---|
format required | Always "open-values-governance-ledger". Tells a reader which Open Values format this is. | always "open-values-governance-ledger" |
version required | The version of the ledger format this file follows. Must start with 0.1.0. | string |
standard required | Always "open-values-standard", the standard this format belongs to. | always "open-values-standard" |
updated required | The date the ledger was last changed, as YYYY-MM-DD. | see date |
purpose required | A sentence or two saying what this ledger is for. | see nonEmptyString |
principles required | The rules the ledger follows, one short sentence each, such as "a relay may move files but must not become the authority". | list |
publication required | How the ledger is published: storage, relays, identity, and whether voting or ratification is open. | see publication |
kAnonymity required | The rules for when attestations may count and how small a group may be reported. | see kAnonymity |
proposals required | Every proposal in the ledger, each a full open-values-proposal record. At least one. | list |
attestations required | Every attestation in the ledger, each a full open-values-attestation record pointing at a proposal by id. | 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 governance ledger contains publication limits, k-anonymity policy, proposals, and attestations.
{
"format": "open-values-governance-ledger",
"version": "0.1.0",
"standard": "open-values-standard",
"updated": "2026-07-08",
"purpose": "Show a file-based governance ledger.",
"principles": [
"files first"
],
"publication": {
"status": "format-seed",
"storage": "single-json-file",
"relay": "dumb relay",
"identity": "pseudonymous",
"liveVoting": false,
"contactGated": true,
"ratification": "No live ratification.",
"privacy": "No private contact details."
},
"kAnonymity": {
"minimumGroupSize": 5,
"countedStatuses": [
"submitted"
],
"uncountedStatuses": [
"template",
"draft"
],
"countedOnlyWhen": [
"signature.verified === true",
"attestation.counted === true"
],
"note": "Seed records do not count."
},
"proposals": [
{
"format": "open-values-proposal",
"version": "0.1.0",
"id": "proposal-example",
"status": "draft",
"target": {
"path": "content/example.json",
"format": "open-values-lens",
"baseSha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
"baseHash": "01234567"
},
"author": {
"type": "pseudonymous",
"id": "example-author",
"display": "Example author"
},
"created": "2026-07-08",
"updated": "2026-07-08",
"rationale": "Show the portable proposal patch shape.",
"operations": [
{
"op": "note",
"path": "/meta/governance",
"summary": "Add a governance note.",
"impact": "Makes review explicit.",
"risk": "Could be mistaken for live voting."
}
],
"signature": {
"method": "none-template",
"verified": false
},
"limits": [
"Not a vote."
]
}
],
"attestations": [
{
"format": "open-values-attestation",
"version": "0.1.0",
"id": "attestation-example",
"status": "template",
"proposal": "proposal-example",
"stance": "support",
"attester": {
"type": "pseudonymous",
"id": "example-attester",
"display": "Example attester"
},
"created": "2026-07-08",
"publicComment": "This is a non-counted template support record.",
"signature": {
"method": "none-template",
"verified": false
},
"counted": false,
"privacy": "Contains no private contact details."
}
]
}
A file that must be rejected
The seed governance ledger must not activate live voting.
{
"format": "open-values-governance-ledger",
"version": "0.1.0",
"standard": "open-values-standard",
"updated": "2026-07-08",
"purpose": "Show a bad governance ledger.",
"principles": [
"files first"
],
"publication": {
"status": "format-seed",
"storage": "single-json-file",
"relay": "dumb relay",
"identity": "pseudonymous",
"liveVoting": true,
"contactGated": true,
"ratification": "No live ratification.",
"privacy": "No private contact details."
},
"kAnonymity": {
"minimumGroupSize": 5,
"countedStatuses": [
"submitted"
],
"uncountedStatuses": [
"template",
"draft"
],
"countedOnlyWhen": [
"signature.verified === true",
"attestation.counted === true"
],
"note": "Seed records do not count."
},
"proposals": [
{
"format": "open-values-proposal",
"version": "0.1.0",
"id": "proposal-example",
"status": "draft",
"target": {
"path": "content/example.json",
"format": "open-values-lens",
"baseSha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
"baseHash": "01234567"
},
"author": {
"type": "pseudonymous",
"id": "example-author",
"display": "Example author"
},
"created": "2026-07-08",
"updated": "2026-07-08",
"rationale": "Show the portable proposal patch shape.",
"operations": [
{
"op": "note",
"path": "/meta/governance",
"summary": "Add a governance note.",
"impact": "Makes review explicit.",
"risk": "Could be mistaken for live voting."
}
],
"signature": {
"method": "none-template",
"verified": false
},
"limits": [
"Not a vote."
]
}
],
"attestations": [
{
"format": "open-values-attestation",
"version": "0.1.0",
"id": "attestation-example",
"status": "template",
"proposal": "proposal-example",
"stance": "support",
"attester": {
"type": "pseudonymous",
"id": "example-attester",
"display": "Example attester"
},
"created": "2026-07-08",
"publicComment": "This is a non-counted template support record.",
"signature": {
"method": "none-template",
"verified": false
},
"counted": false,
"privacy": "Contains no private contact details."
}
]
}
The schema
Its address is https://openvaluesstandard.org/schema/governance-ledger-v0.1.schema.json. Validators can fetch it there; the file is also in the repository at app/data/standard/schemas/governance-ledger.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.