◇ Open Values Standardfor builders

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.

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

FieldWhat it meansType
format requiredAlways "open-values-governance-ledger". Tells a reader which Open Values format this is.always "open-values-governance-ledger"
version requiredThe version of the ledger format this file follows. Must start with 0.1.0.string
standard requiredAlways "open-values-standard", the standard this format belongs to.always "open-values-standard"
updated requiredThe date the ledger was last changed, as YYYY-MM-DD.see date
purpose requiredA sentence or two saying what this ledger is for.see nonEmptyString
principles requiredThe rules the ledger follows, one short sentence each, such as "a relay may move files but must not become the authority".list
publication requiredHow the ledger is published: storage, relays, identity, and whether voting or ratification is open.see publication
kAnonymity requiredThe rules for when attestations may count and how small a group may be reported.see kAnonymity
proposals requiredEvery proposal in the ledger, each a full open-values-proposal record. At least one.list
attestations requiredEvery 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.