◇ Open Values Standardfor builders

Spec / open-values-decision-contracts

Open Values Decision Contracts v0.2

For each product or service category on Conscious Consuming, the setup of its decision page: the one-line summary of what to compare, up to three dials a reader can move, whether a budget answer can be shown, and which computed answers to show. pipeline/build_decisions.js writes it to content/decisions.json, and the dataset build copies each contract into its category file for the app to read.

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_decisions.js. Read by Round 4 decision-page header, Round 4 practical dials, Round 4 computed answer recipes, Round 6 shared-floor interface, Round 9 category-wide decision-page rollout, pipeline/build_datasets.py.

Fields

FieldWhat it meansType
format requiredAlways "open-values-decision-contracts". Tells a reader which Open Values format this is.always "open-values-decision-contracts"
version requiredThe version of the decision contracts format this file follows. Must start with 0.2.0.string
published requiredThe date this set of contracts was published, as YYYY-MM-DD.string
status requiredWhether the founder has approved the contracts (founder-approved) or not yet (founder-signoff-pending).one of "founder-signoff-pending", "founder-approved"
consumer requiredNotes naming the part of the site that reads each part of a contract.see consumer
contracts requiredOne contract per category, each saying how that category's decision page works.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 decision contract names its consumers and carries a signed short read, practical mapped axes, honest budget posture, and applicable answer slots.

{
  "format": "open-values-decision-contracts",
  "version": "0.2.0",
  "published": "2026-07-14",
  "status": "founder-signoff-pending",
  "consumer": {
    "reads": "Round 4 header.",
    "axes": "Round 4 dials.",
    "budget": "Round 4 budget eligibility.",
    "archetypes": "Round 4 answer recipes.",
    "page": "Round 5 primary route."
  },
  "contracts": [
    {
      "category": "fixture-category",
      "reads": {
        "text": "Choices differ most in repairability and support life.",
        "basis": [
          {
            "criterion": "repairability",
            "readsAs": "repairability"
          },
          {
            "criterion": "longevity",
            "readsAs": "support life"
          }
        ],
        "signature": {
          "by": "Fixture maintainer",
          "on": "2026-07-14",
          "status": "pilot"
        }
      },
      "axes": [
        {
          "id": "keep-it-longer",
          "kind": "criterion",
          "label": "Keep it longer",
          "question": "How much should support life lead?",
          "criteria": [
            "longevity"
          ],
          "poles": [
            "Flexible",
            "Longer support"
          ],
          "default": 50
        }
      ],
      "budget": {
        "available": false,
        "mode": "none"
      },
      "archetypes": [
        "best-for-most",
        "strictest-match"
      ],
      "page": {
        "stage": "founder-review",
        "primaryRoute": true
      }
    }
  ]
}

A file that must be rejected

Budget, honest cannot be offered when the category declares no usable budget data.

{
  "format": "open-values-decision-contracts",
  "version": "0.2.0",
  "published": "2026-07-14",
  "status": "founder-signoff-pending",
  "consumer": {
    "reads": "Round 4 header.",
    "axes": "Round 4 dials.",
    "budget": "Round 4 budget eligibility.",
    "archetypes": "Round 4 answer recipes.",
    "page": "Round 5 primary route."
  },
  "contracts": [
    {
      "category": "fixture-category",
      "reads": {
        "text": "Choices differ most in repairability and support life.",
        "basis": [
          {
            "criterion": "repairability",
            "readsAs": "repairability"
          },
          {
            "criterion": "longevity",
            "readsAs": "support life"
          }
        ],
        "signature": {
          "by": "Fixture maintainer",
          "on": "2026-07-14",
          "status": "pilot"
        }
      },
      "axes": [
        {
          "id": "keep-it-longer",
          "kind": "criterion",
          "label": "Keep it longer",
          "question": "How much should support life lead?",
          "criteria": [
            "longevity"
          ],
          "poles": [
            "Flexible",
            "Longer support"
          ],
          "default": 50
        }
      ],
      "budget": {
        "available": false,
        "mode": "none"
      },
      "archetypes": [
        "best-for-most",
        "strictest-match",
        "budget-honest"
      ],
      "page": {
        "stage": "founder-review",
        "primaryRoute": true
      }
    }
  ]
}

The schema

Its address is https://openvaluesstandard.org/schema/decision-contracts-v0.2.schema.json. Validators can fetch it there; the file is also in the repository at app/data/standard/schemas/decision-contracts.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.