◇ Open Values Standardfor builders

Spec / ovs-ask-traces

Open Values Ask Traces v0.1

For each test search in ask-fixtures.json, the results the data build's own search gives, with scores and ranks, so the app's results can be compared against them. 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 Ask 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-ask-traces"
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
resolverModel requiredThe function that produced the traces.see nonEmptyString
traces requiredOne trace per test query in ask-fixtures.json.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

Ask traces record resolver hits with labels, reasons, scores, and route hashes.

{
  "format": "ovs-ask-traces",
  "version": "0.1",
  "built": "2026-07-07",
  "source": [
    "app/data/nodes/ask-fixtures.json"
  ],
  "purpose": "Deterministic resolver traces for app-owned integration.",
  "resolverModel": "pipeline/build_nodes.js resolveAskQuery",
  "traces": [
    {
      "query": "best bank",
      "normalized": "best bank",
      "layer": "core",
      "expectAny": [
        "ovs:cat/banking"
      ],
      "matched": "ovs:cat/banking",
      "matchedRank": 1,
      "ok": true,
      "top": [
        {
          "id": "ovs:cat/banking",
          "label": "Ethical banking",
          "type": "category",
          "route": "explore",
          "hash": "#explore/banking",
          "score": 100,
          "reason": "exact",
          "key": "banking"
        }
      ]
    }
  ]
}

A file that must be rejected

Trace hits must carry route hashes so app previews can replay them.

{
  "format": "ovs-ask-traces",
  "version": "0.1",
  "built": "2026-07-07",
  "source": [
    "app/data/nodes/ask-fixtures.json"
  ],
  "purpose": "Deterministic resolver traces for app-owned integration.",
  "resolverModel": "pipeline/build_nodes.js resolveAskQuery",
  "traces": [
    {
      "query": "best bank",
      "normalized": "best bank",
      "layer": "core",
      "expectAny": [
        "ovs:cat/banking"
      ],
      "ok": true,
      "top": [
        {
          "id": "ovs:cat/banking",
          "label": "Ethical banking",
          "type": "category",
          "route": "explore",
          "hash": "explore/banking",
          "score": 100,
          "reason": "exact",
          "key": "banking"
        }
      ]
    }
  ]
}

The schema

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