◇ Open Values Standardfor builders

Spec / ovs-ask-presentation-contract

Open Values Ask Presentation Contract v0.1

Suggested wording and grouping for showing Ask search results: section headings, labels for each kind of result, and what to offer when nothing matches. The data build writes it for the people building the search page. 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 app Ask UI, 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-presentation-contract"
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
resultSections requiredGroups the app can show Ask results in, such as places from the startup index and entries from the full index.list
typeCopy requiredFor each kind of result, the badge text, the action label and the route pattern.object
matchReasons requiredFor each match reason, a short label readers can understand, such as "typo match".object
emptyState requiredWhat to offer when a query finds nothing.see emptyState
qaCases requiredTest queries with the first result and matched result the app should show.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 presentation contracts define sections, copy, empty states, and QA hashes without owning app UI.

{
  "format": "ovs-ask-presentation-contract",
  "version": "0.1",
  "built": "2026-07-07",
  "source": [
    "app/data/nodes/ask-core.json",
    "app/data/nodes/ask-index.json",
    "app/data/nodes/ask-traces.json"
  ],
  "purpose": "Suggested presentation contract for app-owned Ask integration.",
  "appLaneNote": "Use as a dev contract, not a hard UI mandate.",
  "resultSections": [
    {
      "id": "places",
      "label": "Places this could mean",
      "layers": [
        "core"
      ],
      "targetTypes": [
        "category"
      ],
      "maxItems": 5
    },
    {
      "id": "entries",
      "label": "Entries",
      "layers": [
        "full"
      ],
      "targetTypes": [
        "item"
      ],
      "maxItems": 5
    }
  ],
  "typeCopy": {
    "category": {
      "badge": "Category",
      "action": "Compare options",
      "route": "#explore/<cid>"
    },
    "guide": {
      "badge": "Guide",
      "action": "Read guide",
      "route": "#guide/<slug>"
    },
    "brand": {
      "badge": "Brand",
      "action": "Open brand page",
      "route": "#n/brand/<slug>"
    },
    "company": {
      "badge": "Company",
      "action": "Open company page",
      "route": "#n/company/<slug>"
    },
    "tag": {
      "badge": "Label",
      "action": "Open label page",
      "route": "#n/tag/<slug>"
    },
    "line": {
      "badge": "Line",
      "action": "Open line page",
      "route": "#n/line/<slug>"
    },
    "errand": {
      "badge": "Errand",
      "action": "Open errand",
      "route": "#n/errand/<slug>"
    },
    "item": {
      "badge": "Entry",
      "action": "Open entry",
      "route": "#item/<cid>/<code>"
    }
  },
  "matchReasons": {
    "alias": "Alias match",
    "exact": "Exact match",
    "query-token": "Query token match",
    "fuzzy-1": "Typo-tolerant match",
    "token-containment": "Related token match"
  },
  "emptyState": {
    "primary": "#contribute/want/<query>",
    "secondary": "#browse"
  },
  "qaCases": [
    {
      "query": "best bank",
      "section": "places",
      "expectFirstHash": "#explore/banking",
      "expectMatchedHash": "#explore/banking",
      "ok": true
    }
  ]
}

A file that must be rejected

Ask presentation empty-state routes must be hash routes.

{
  "format": "ovs-ask-presentation-contract",
  "version": "0.1",
  "built": "2026-07-07",
  "source": [
    "app/data/nodes/ask-traces.json"
  ],
  "purpose": "Suggested presentation contract for app-owned Ask integration.",
  "appLaneNote": "Use as a dev contract.",
  "resultSections": [
    {
      "id": "places",
      "label": "Places",
      "layers": [
        "core"
      ],
      "targetTypes": [
        "category"
      ],
      "maxItems": 5
    },
    {
      "id": "entries",
      "label": "Entries",
      "layers": [
        "full"
      ],
      "targetTypes": [
        "item"
      ],
      "maxItems": 5
    }
  ],
  "typeCopy": {
    "category": {
      "badge": "Category",
      "action": "Compare",
      "route": "#explore/<cid>"
    },
    "guide": {
      "badge": "Guide",
      "action": "Read",
      "route": "#guide/<slug>"
    },
    "brand": {
      "badge": "Brand",
      "action": "Open",
      "route": "#n/brand/<slug>"
    },
    "company": {
      "badge": "Company",
      "action": "Open",
      "route": "#n/company/<slug>"
    },
    "tag": {
      "badge": "Label",
      "action": "Open",
      "route": "#n/tag/<slug>"
    },
    "line": {
      "badge": "Line",
      "action": "Open",
      "route": "#n/line/<slug>"
    },
    "errand": {
      "badge": "Errand",
      "action": "Open",
      "route": "#n/errand/<slug>"
    },
    "item": {
      "badge": "Entry",
      "action": "Open",
      "route": "#item/<cid>/<code>"
    }
  },
  "matchReasons": {
    "alias": "Alias",
    "exact": "Exact",
    "query-token": "Query token",
    "fuzzy-1": "Typo",
    "token-containment": "Related"
  },
  "emptyState": {
    "primary": "contribute/want/<query>",
    "secondary": "#browse"
  },
  "qaCases": [
    {
      "query": "best bank",
      "section": "places",
      "expectFirstHash": "#explore/banking",
      "expectMatchedHash": "#explore/banking",
      "ok": true
    }
  ]
}

The schema

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