◇ Open Values Standardfor builders

Spec / open-values-lines

Open Values Lines v0.2

The list of rules a person can choose to hold, such as an allergy, a diet or a company to avoid, plus the published sets of rules that are on by default. Conscious Consuming keeps it.

Stable. A change that breaks existing files needs a new version. A file someone writes by hand or with a tool, and keeps.

Who writes it and who reads it

Written by pipeline/build_lines.js. Read by app line filters, future browser extension.

Fields

FieldWhat it meansType
format requiredAlways "open-values-lines". Tells a reader that this file is the list of rules a person can hold.always "open-values-lines"
version requiredThe version of the lines format this file follows, 0.2.string
updated requiredThe day the file was last changed, as YYYY-MM-DD.string
noteA paragraph for maintainers saying what the file holds and how the app reads it.string
kinds requiredThe kinds of rule, keyed by kind id (allergy, diet, require, avoid, cap, lean), each with one sentence saying what that kind of rule does.map of string
setsPublished sets of rules that are switched on by default, such as the baseline. A person can read every rule in a set, switch a rule off for themselves, or copy the set and change it.list
lines requiredEvery rule a person can choose to hold, such as an allergy, a diet or a company to avoid. Rules are off until the person picks them.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 minimal line registry declares kinds and at least one well-shaped line.

{
  "format": "open-values-lines",
  "version": "0.2",
  "updated": "2026-07-07",
  "kinds": {
    "allergy": "Hide listed allergens."
  },
  "lines": [
    {
      "id": "allergy:nuts",
      "kind": "allergy",
      "label": "Nuts",
      "reads": "Hide anything that lists nuts.",
      "tag": "nuts"
    }
  ]
}

A shared-floor set is versioned, forkable, fold-only, bounded, and every rule carries a source receipt plus an entry-evidence gate.

{
  "format": "open-values-lines",
  "version": "0.2",
  "updated": "2026-07-14",
  "kinds": {
    "allergy": "Hide listed allergens."
  },
  "sets": [
    {
      "format": "open-values-line-set",
      "id": "floor:fixture-pilot",
      "tier": "floor",
      "label": "Fixture floor",
      "version": "0.1.0-pilot",
      "published": "2026-07-14",
      "status": "founder-signoff-pending",
      "defaultOn": true,
      "presentation": "fold",
      "unknownEvidence": "keep-visible",
      "namedConsumer": "Fixture floor chip, filter, receipt door, and fold.",
      "bounds": {
        "maximumRules": 1,
        "maximumExcludedSharePerCategory": 0.25,
        "maximumExcludedShareOverall": 0.01,
        "minimumRemainingPerCategory": 5,
        "minimumMatchesPerRule": 1
      },
      "fork": {
        "license": "CC0-1.0",
        "portableRuleIds": true,
        "localRuleOverrides": true,
        "requiredAttribution": "Keep retained receipts."
      },
      "governance": {
        "curator": "Fixture curator",
        "status": "founder-signoff-pending",
        "changePath": "Fork and propose a sourced change.",
        "noCapture": "No payment changes the rules."
      },
      "changelog": [
        {
          "version": "0.1.0-pilot",
          "date": "2026-07-14",
          "changes": "Initial fixture."
        }
      ],
      "rules": [
        {
          "id": "avoid:floor-fixture-privacy",
          "kind": "avoid",
          "tier": "floor",
          "label": "Poor sourced privacy record",
          "reads": "Fold only sourced, dated Poor-band privacy matches.",
          "effect": "fold",
          "scope": {
            "categories": [
              "fixture"
            ]
          },
          "match": {
            "type": "criterion-band",
            "criterion": "privacy",
            "band": "poor",
            "maximumExclusive": 20,
            "requiresSource": true,
            "requiresAsOf": true
          },
          "receipt": {
            "note": "Fixture policy receipt.",
            "source": "https://example.org/floor-receipt",
            "asof": "2026"
          }
        }
      ]
    }
  ],
  "lines": [
    {
      "id": "allergy:nuts",
      "kind": "allergy",
      "label": "Nuts",
      "reads": "Hide anything that lists nuts.",
      "tag": "nuts"
    }
  ]
}

A file that must be rejected

Require lines need an accept list so they can be checked.

{
  "format": "open-values-lines",
  "version": "0.2",
  "updated": "2026-07-07",
  "kinds": {
    "require": "Require a tag or property."
  },
  "lines": [
    {
      "id": "require:organic",
      "kind": "require",
      "label": "Organic",
      "reads": "Only organic options."
    }
  ]
}

A floor rule without its own source receipt cannot enter a default-on set.

{
  "format": "open-values-lines",
  "version": "0.2",
  "updated": "2026-07-14",
  "kinds": {
    "allergy": "Hide listed allergens."
  },
  "sets": [
    {
      "format": "open-values-line-set",
      "id": "floor:fixture-pilot",
      "tier": "floor",
      "label": "Fixture floor",
      "version": "0.1.0-pilot",
      "published": "2026-07-14",
      "status": "founder-signoff-pending",
      "defaultOn": true,
      "presentation": "fold",
      "unknownEvidence": "keep-visible",
      "namedConsumer": "Fixture floor chip, filter, receipt door, and fold.",
      "bounds": {
        "maximumRules": 1,
        "maximumExcludedSharePerCategory": 0.25,
        "maximumExcludedShareOverall": 0.01,
        "minimumRemainingPerCategory": 5,
        "minimumMatchesPerRule": 1
      },
      "fork": {
        "license": "CC0-1.0",
        "portableRuleIds": true,
        "localRuleOverrides": true,
        "requiredAttribution": "Keep retained receipts."
      },
      "governance": {
        "curator": "Fixture curator",
        "status": "founder-signoff-pending",
        "changePath": "Fork and propose a sourced change.",
        "noCapture": "No payment changes the rules."
      },
      "changelog": [
        {
          "version": "0.1.0-pilot",
          "date": "2026-07-14",
          "changes": "Initial fixture."
        }
      ],
      "rules": [
        {
          "id": "avoid:floor-fixture-privacy",
          "kind": "avoid",
          "tier": "floor",
          "label": "Poor sourced privacy record",
          "reads": "Fold only sourced, dated Poor-band privacy matches.",
          "effect": "fold",
          "scope": {
            "categories": [
              "fixture"
            ]
          },
          "match": {
            "type": "criterion-band",
            "criterion": "privacy",
            "band": "poor",
            "maximumExclusive": 20,
            "requiresSource": true,
            "requiresAsOf": true
          },
          "receipt": {
            "note": "A source is deliberately absent.",
            "asof": "2026"
          }
        }
      ]
    }
  ],
  "lines": [
    {
      "id": "allergy:nuts",
      "kind": "allergy",
      "label": "Nuts",
      "reads": "Hide anything that lists nuts.",
      "tag": "nuts"
    }
  ]
}

The schema

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