Spec / open-values-proposal
Open Values Proposal v0.1
A suggested change to one data file, written down so anyone can read and check it: which file and version it changes, what it would change, why, and who wrote it. Proposals live inside the governance ledger at content/governance/proposals.json, and pipeline/build_proposals.js summarises them for the app. Nothing reads them as votes yet.
- Files people or tools write
- Status: draft
- Version: 0.1.0
- Format name in the file:
open-values-proposal
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
Written by pipeline/build_proposals.js. Read by governance ledger, generated governance index, future dumb relays.
Fields
| Field | What it means | Type |
|---|---|---|
format required | Always "open-values-proposal". Tells a reader which Open Values format this is. | always "open-values-proposal" |
version required | The version of the proposal format this record follows. Must start with 0.1.0. | string |
id required | A unique name for this proposal, in lowercase letters, numbers and hyphens, such as "proposal-asks-offers-reply-safety". Attestations point at it. | see slug |
status required | Where the proposal stands: template (an example), draft, submitted, withdrawn, superseded by another, or archived. The seed ledger holds only templates and drafts. | one of "template", "draft", "submitted", "withdrawn", "superseded", "archived" |
target required | The file the proposal would change, and the hash of that file when the proposal was written. | see target |
author required | Who wrote the proposal. | see actor |
created required | The date the proposal was first written, as YYYY-MM-DD. | see date |
updated required | The date the proposal was last changed, as YYYY-MM-DD. | see date |
rationale required | Why the change is wanted, in a sentence or two. | see nonEmptyString |
operations required | The changes the proposal would make to the target file, one entry per change. At least one. | list |
signature required | How the proposal was signed and whether that signature has been checked. | see signature |
limits | Things the proposal does not do or must not be used for, one sentence each, such as "This proposal is a template, not a vote." | 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 proposal names target, base hash, author, rationale, operations, and signature metadata.
{
"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."
]
}
A file that must be rejected
A proposal without a base hash cannot be recomputed against a target file.
{
"format": "open-values-proposal",
"version": "0.1.0",
"id": "proposal-example",
"status": "draft",
"target": {
"path": "content/example.json",
"format": "open-values-lens",
"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."
]
}
The schema
Its address is https://openvaluesstandard.org/schema/proposal-v0.1.schema.json. Validators can fetch it there; the file is also in the repository at app/data/standard/schemas/proposal.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.