◇ Open Values Standardfor builders

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.

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

FieldWhat it meansType
format requiredAlways "open-values-proposal". Tells a reader which Open Values format this is.always "open-values-proposal"
version requiredThe version of the proposal format this record follows. Must start with 0.1.0.string
id requiredA 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 requiredWhere 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 requiredThe file the proposal would change, and the hash of that file when the proposal was written.see target
author requiredWho wrote the proposal.see actor
created requiredThe date the proposal was first written, as YYYY-MM-DD.see date
updated requiredThe date the proposal was last changed, as YYYY-MM-DD.see date
rationale requiredWhy the change is wanted, in a sentence or two.see nonEmptyString
operations requiredThe changes the proposal would make to the target file, one entry per change. At least one.list
signature requiredHow the proposal was signed and whether that signature has been checked.see signature
limitsThings 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.