◇ Open Values Standardfor builders

Spec / ovs-node-preview-matrix

Open Values Node Preview Matrix v0.1

A list of test scenarios for a private preview of the app, grouped and in the order to run them, with what each must show. The data build writes it for testers. It is an internal file used while building the site.

Used while building the sites. Not meant for other apps. Data kept for tests, not for use.

Who writes it and who reads it

Written by pipeline/build_nodes.js. Read by preview QA, app-lane integration.

Fields

FieldWhat it meansType
format requiredNames this file's format, so a reader can check it before reading the rest of the file.always "ovs-node-preview-matrix"
version requiredThe version of the format this file follows, such as "0.1".see version
built requiredThe date of the source data this file was built from, as YYYY-MM-DD.see date
source requiredThe script and files this file was built from, as paths in the repository.see source
purpose requiredOne sentence on what this file is for.see nonEmptyString
appLaneNote requiredA note on which choices this file leaves to the app code that reads it, such as fetching, layout and wording.see nonEmptyString
status requiredAlways "pending-app-integration": the generated data is ready, and the app work that uses it is not yet confirmed.always "pending-app-integration"
h4DrainableFromDataAlone requiredAlways false. The generated files alone can never close handoff item H4; that needs evidence from the running app.always false
groups requiredThe scenario group ids, in the order they should be run.list
runContract requiredThe order to run the groups in, the evidence each needs, and when the run is done.see runContract
scenarios requiredThe test scenarios for a private preview of the app.list
totals requiredHow many scenarios there are, overall and by group.object

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

Preview matrices keep app-owned scenarios pending and forbid data-only H4 drains.

{
  "format": "ovs-node-preview-matrix",
  "version": "0.1",
  "built": "2026-07-07",
  "source": [
    "app/data/nodes/ask-traces.json"
  ],
  "purpose": "Private-preview QA matrix.",
  "appLaneNote": "Preview QA contract only.",
  "status": "pending-app-integration",
  "h4DrainableFromDataAlone": false,
  "groups": [
    "startup-search"
  ],
  "runContract": {
    "purpose": "App-owned private-preview run contract for generated nodes.",
    "status": "pending-app-integration",
    "h4DrainableFromDataAlone": false,
    "namedConsumer": "App H4 preview QA.",
    "drainRule": "H4 drains only after app-owned preview behavior is checked.",
    "evidenceRequired": [
      "Manual QA note."
    ],
    "runOrder": [
      {
        "step": 1,
        "group": "startup-search",
        "scenarioIds": [
          "startup-best-bank"
        ],
        "passWhen": [
          "Scenario passes."
        ],
        "mustNot": [
          "Do not pass from data alone."
        ]
      }
    ],
    "exitCriteria": [
      "Every scenario is covered."
    ],
    "coverage": {
      "scenarioCount": 1,
      "groupCount": 1,
      "allScenariosCovered": true,
      "allGroupsCovered": true,
      "orderedGroups": [
        "startup-search"
      ],
      "drainScenarioId": "startup-best-bank"
    }
  },
  "scenarios": [
    {
      "id": "startup-best-bank",
      "group": "startup-search",
      "title": "Best bank query",
      "owner": "app/design",
      "sourceFiles": [
        "ask-core.json"
      ],
      "steps": [
        "Enter Ask query."
      ],
      "acceptanceCriteria": [
        "Expected result appears."
      ],
      "mustNot": [
        "Do not strip route hashes."
      ]
    }
  ],
  "totals": {
    "scenarios": 1
  }
}

A file that must be rejected

Preview matrices must not allow data generation alone to drain app-owned H4 work.

{
  "format": "ovs-node-preview-matrix",
  "version": "0.1",
  "built": "2026-07-07",
  "source": [
    "app/data/nodes/ask-traces.json"
  ],
  "purpose": "Private-preview QA matrix.",
  "appLaneNote": "Preview QA contract only.",
  "status": "pending-app-integration",
  "h4DrainableFromDataAlone": true,
  "groups": [
    "startup-search"
  ],
  "runContract": {
    "purpose": "App-owned private-preview run contract for generated nodes.",
    "status": "pending-app-integration",
    "h4DrainableFromDataAlone": false,
    "namedConsumer": "App H4 preview QA.",
    "drainRule": "H4 drains only after app-owned preview behavior is checked.",
    "evidenceRequired": [
      "Manual QA note."
    ],
    "runOrder": [
      {
        "step": 1,
        "group": "startup-search",
        "scenarioIds": [
          "startup-best-bank"
        ],
        "passWhen": [
          "Scenario passes."
        ],
        "mustNot": [
          "Do not pass from data alone."
        ]
      }
    ],
    "exitCriteria": [
      "Every scenario is covered."
    ],
    "coverage": {
      "scenarioCount": 1,
      "groupCount": 1,
      "allScenariosCovered": true,
      "allGroupsCovered": true,
      "orderedGroups": [
        "startup-search"
      ],
      "drainScenarioId": "startup-best-bank"
    }
  },
  "scenarios": [
    {
      "id": "startup-best-bank",
      "group": "startup-search",
      "title": "Best bank query",
      "owner": "app/design",
      "sourceFiles": [
        "ask-core.json"
      ],
      "steps": [
        "Enter Ask query."
      ],
      "acceptanceCriteria": [
        "Expected result appears."
      ],
      "mustNot": [
        "Do not strip route hashes."
      ]
    }
  ],
  "totals": {
    "scenarios": 1
  }
}

The schema

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