◇ Open Values Standardfor builders

Spec / open-values-governance-index

Open Values Governance Index v0.1

A summary of the governance ledger for the app to show: each proposal with whether its target file has changed since it was written, a tally of responses, and totals. pipeline/build_proposals.js builds it from content/governance/proposals.json into app/data/proposals.json; change the ledger, not this file.

Draft. It may still change before it is called stable. A file a build step makes from other files. Change the sources, not this file.

Who writes it and who reads it

Written by pipeline/build_proposals.js. Read by future app governance surface, audit:governance.

Fields

FieldWhat it meansType
format requiredAlways "open-values-governance-index". Tells a reader which Open Values format this is.always "open-values-governance-index"
version requiredThe version of the index 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"
built requiredThe date of the ledger this index was built from, copied from the ledger's updated field, as YYYY-MM-DD.see date
purpose requiredA sentence saying what this index is for.see nonEmptyString
generatedFrom requiredThe ledger file this index was built from, its date, and its hash, so anyone can check the index against it.see generatedFrom
publication requiredCopied unchanged from the ledger: how it is published and whether voting or ratification is open.see publication
kAnonymity requiredCopied unchanged from the ledger: the rules for when attestations may count.see kAnonymity
counts requiredTotals across the ledger: proposals, attestations, targets, and how many there are of each status and stance.see counts
filters requiredThe distinct values an app can offer as filters, each list sorted alphabetically.see filters
principles requiredCopied unchanged from the ledger: the rules it follows, one short sentence each.list
proposals requiredA summary of every proposal in the ledger, in ledger order, with a check of whether its target file has changed and a tally of its attestations.list
attestations requiredA summary of every attestation in the ledger, in ledger order.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

The generated governance index summarizes proposals, attestations, counts, and no-live publication policy.

{
  "format": "open-values-governance-index",
  "version": "0.1.0",
  "standard": "open-values-standard",
  "built": "2026-07-08",
  "purpose": "Show a generated governance index.",
  "generatedFrom": {
    "path": "content/governance/proposals.json",
    "updated": "2026-07-08",
    "sha256": "abcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcd"
  },
  "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."
  },
  "counts": {
    "proposals": 1,
    "attestations": 1,
    "countedAttestations": 0,
    "targets": 1,
    "targetFormats": 1,
    "proposalStatuses": {
      "draft": 1
    },
    "attestationStatuses": {
      "template": 1
    },
    "stances": {
      "support": 1
    }
  },
  "filters": {
    "proposalStatuses": [
      "draft"
    ],
    "attestationStatuses": [
      "template"
    ],
    "stances": [
      "support"
    ],
    "targets": [
      "content/example.json"
    ],
    "targetFormats": [
      "open-values-lens"
    ]
  },
  "principles": [
    "files first"
  ],
  "proposals": [
    {
      "id": "proposal-example",
      "status": "draft",
      "target": {
        "path": "content/example.json",
        "format": "open-values-lens",
        "baseSha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
        "baseHash": "01234567",
        "currentSha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
        "currentHash": "01234567",
        "matchesCurrent": true
      },
      "author": {
        "type": "pseudonymous",
        "id": "example-author",
        "display": "Example author"
      },
      "created": "2026-07-08",
      "updated": "2026-07-08",
      "rationale": "Show the generated proposal summary shape.",
      "operations": [
        {
          "op": "note",
          "path": "/meta/governance",
          "summary": "Add a governance note.",
          "impact": "Makes review explicit.",
          "risk": "Could be mistaken for live voting."
        }
      ],
      "operationCount": 1,
      "signature": {
        "method": "none-template",
        "verified": false
      },
      "attestations": {
        "total": 1,
        "counted": 0,
        "stances": {
          "support": 1
        }
      },
      "limits": [
        "Not a vote."
      ]
    }
  ],
  "attestations": [
    {
      "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

Generated governance index counts must match summarized attestations.

{
  "format": "open-values-governance-index",
  "version": "0.1.0",
  "standard": "open-values-standard",
  "built": "2026-07-08",
  "purpose": "Show a bad generated governance index.",
  "generatedFrom": {
    "path": "content/governance/proposals.json",
    "updated": "2026-07-08",
    "sha256": "abcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcd"
  },
  "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."
  },
  "counts": {
    "proposals": 1,
    "attestations": 2,
    "countedAttestations": 0,
    "targets": 1,
    "targetFormats": 1,
    "proposalStatuses": {
      "draft": 1
    },
    "attestationStatuses": {
      "template": 1
    },
    "stances": {
      "support": 1
    }
  },
  "filters": {
    "proposalStatuses": [
      "draft"
    ],
    "attestationStatuses": [
      "template"
    ],
    "stances": [
      "support"
    ],
    "targets": [
      "content/example.json"
    ],
    "targetFormats": [
      "open-values-lens"
    ]
  },
  "principles": [
    "files first"
  ],
  "proposals": [
    {
      "id": "proposal-example",
      "status": "draft",
      "target": {
        "path": "content/example.json",
        "format": "open-values-lens",
        "baseSha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
        "baseHash": "01234567",
        "currentSha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
        "currentHash": "01234567",
        "matchesCurrent": true
      },
      "author": {
        "type": "pseudonymous",
        "id": "example-author",
        "display": "Example author"
      },
      "created": "2026-07-08",
      "updated": "2026-07-08",
      "rationale": "Show the generated proposal summary shape.",
      "operations": [
        {
          "op": "note",
          "path": "/meta/governance",
          "summary": "Add a governance note.",
          "impact": "Makes review explicit.",
          "risk": "Could be mistaken for live voting."
        }
      ],
      "operationCount": 1,
      "signature": {
        "method": "none-template",
        "verified": false
      },
      "attestations": {
        "total": 1,
        "counted": 0,
        "stances": {
          "support": 1
        }
      },
      "limits": [
        "Not a vote."
      ]
    }
  ],
  "attestations": [
    {
      "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-index-v0.1.schema.json. Validators can fetch it there; the file is also in the repository at app/data/standard/schemas/governance-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.