◇ Open Values Standardfor builders

Spec / ovs-ask-core-index

Open Values Ask Core Index v0.1

The small search index the app loads at startup for Ask, the site's search box. It covers categories, brands, companies, labels, guides, errands and lines, but not single entries. The data build writes it, and the app reads it on every visit.

Stable. A change that breaks existing files needs a new version. A file a build step makes from other files. Change the sources, not this file.

Who writes it and who reads it

Written by pipeline/build_nodes.js. Read by Ask startup search.

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-core-index"
type requiredAlways "ask-core".always "ask-core"
version requiredThe version of the format this file follows, such as "0.1".string
built requiredThe date of the source data this file was built from, as YYYY-MM-DD.string
source requiredThe files this index was built from, as paths in the repository.see sourceList
strategy requiredA short note on how the index is meant to be used.string
targetFields requiredThe fields each record in targets carries.list of string
startupContract requiredWhat the app can count on when it loads this index at startup: size, coverage, matching rules, and what to do when nothing matches.see startupContract
tokens requiredA map from each normalized word or phrase to the ids it can find. The same as in ask-index.json, without entries (items), so it is small enough to load at startup.see tokenMap
aliases requiredA map from each normalized name to the one id it names exactly.see aliasMap
targets requiredA map from each id to its type, name and route, so results can be shown without loading other files.map of see target
stats requiredCounts by name, such as "tokens", "aliases", "targets", and the matching counts in the full index.see stats

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 compact Ask core index carries target metadata for startup search results.

{
  "format": "ovs-ask-core-index",
  "type": "ask-core",
  "version": "0.1",
  "built": "2026-07-07",
  "source": [
    "app/data/nodes/ask-index.json"
  ],
  "strategy": "Startup-friendly search over non-item targets.",
  "targetFields": [
    "type",
    "label",
    "hash"
  ],
  "startupContract": {
    "purpose": "App-owned startup Ask contract for ask-core.json; full product and barcode search stays lazy.",
    "appLaneNote": "Data contract only; app-owned code chooses input behavior and result presentation.",
    "loadHint": "eager-search",
    "budget": {
      "maxBytes": 780000,
      "currentBytes": 1000,
      "minimumHeadroomBytes": 50000,
      "headroomBytes": 699000,
      "withinBudget": true,
      "hasMinimumHeadroom": true,
      "measurement": "UTF-8 bytes of the generated pretty JSON file."
    },
    "covers": {
      "layer": "core",
      "targetTypes": [
        "category"
      ],
      "deferredTargetTypes": [
        "item"
      ],
      "targetFields": [
        "type",
        "label",
        "hash"
      ]
    },
    "resolver": {
      "normalization": "lowercase, strip accents, remove punctuation, collapse spaces",
      "stopWords": [
        "best"
      ],
      "rankOrder": [
        "alias",
        "exact",
        "query-token",
        "fuzzy-1",
        "token-containment",
        "type-priority"
      ],
      "maxStartupResults": 5
    },
    "lazyBoundary": {
      "file": "ask-index.json",
      "loadHint": "lazy-product-search",
      "use": "Product-name and barcode results only.",
      "trigger": "Product-name search, barcode lookup, or explicit deeper-results action.",
      "keepCoreIfLazyFails": true,
      "failureMode": "Keep core results visible."
    },
    "emptyState": {
      "when": "No core candidates survive normalization and ranking.",
      "primary": "#contribute/want/<query>",
      "secondary": "#browse",
      "mustNot": "Do not invent a target."
    },
    "goldenQueries": [
      {
        "query": "best bank",
        "normalized": "best bank",
        "intent": "plain category question",
        "expectAny": [
          "ovs:cat/banking"
        ],
        "expectOneInTop": 5,
        "matched": "ovs:cat/banking",
        "matchedRank": 1,
        "expectFirstHash": "#explore/banking",
        "expectMatchedHash": "#explore/banking",
        "ok": true,
        "top": [
          {
            "id": "ovs:cat/banking",
            "label": "Ethical banking",
            "type": "category",
            "hash": "#explore/banking",
            "score": 100,
            "reason": "alias",
            "key": "best bank"
          }
        ]
      }
    ]
  },
  "tokens": {
    "bank": [
      "ovs:cat/banking"
    ]
  },
  "aliases": {
    "best bank": "ovs:cat/banking"
  },
  "targets": {
    "ovs:cat/banking": {
      "type": "category",
      "label": "Ethical banking",
      "hash": "#explore/banking"
    }
  },
  "stats": {
    "tokens": 1,
    "targets": 1
  }
}

A file that must be rejected

Ask core target metadata must include a route hash.

{
  "format": "ovs-ask-core-index",
  "type": "ask-core",
  "version": "0.1",
  "built": "2026-07-07",
  "source": [
    "app/data/nodes/ask-index.json"
  ],
  "strategy": "Startup-friendly search over non-item targets.",
  "targetFields": [
    "type",
    "label",
    "hash"
  ],
  "startupContract": {
    "purpose": "App-owned startup Ask contract for ask-core.json; full product and barcode search stays lazy.",
    "appLaneNote": "Data contract only; app-owned code chooses input behavior and result presentation.",
    "loadHint": "eager-search",
    "budget": {
      "maxBytes": 780000,
      "currentBytes": 1000,
      "minimumHeadroomBytes": 50000,
      "headroomBytes": 699000,
      "withinBudget": true,
      "hasMinimumHeadroom": true,
      "measurement": "UTF-8 bytes of the generated pretty JSON file."
    },
    "covers": {
      "layer": "core",
      "targetTypes": [
        "category"
      ],
      "deferredTargetTypes": [
        "item"
      ],
      "targetFields": [
        "type",
        "label",
        "hash"
      ]
    },
    "resolver": {
      "normalization": "lowercase, strip accents, remove punctuation, collapse spaces",
      "stopWords": [
        "best"
      ],
      "rankOrder": [
        "alias",
        "exact",
        "query-token",
        "fuzzy-1",
        "token-containment",
        "type-priority"
      ],
      "maxStartupResults": 5
    },
    "lazyBoundary": {
      "file": "ask-index.json",
      "loadHint": "lazy-product-search",
      "use": "Product-name and barcode results only.",
      "trigger": "Product-name search, barcode lookup, or explicit deeper-results action.",
      "keepCoreIfLazyFails": true,
      "failureMode": "Keep core results visible."
    },
    "emptyState": {
      "when": "No core candidates survive normalization and ranking.",
      "primary": "#contribute/want/<query>",
      "secondary": "#browse",
      "mustNot": "Do not invent a target."
    },
    "goldenQueries": [
      {
        "query": "best bank",
        "normalized": "best bank",
        "intent": "plain category question",
        "expectAny": [
          "ovs:cat/banking"
        ],
        "expectOneInTop": 5,
        "matched": "ovs:cat/banking",
        "matchedRank": 1,
        "expectFirstHash": "#explore/banking",
        "expectMatchedHash": "#explore/banking",
        "ok": true,
        "top": [
          {
            "id": "ovs:cat/banking",
            "label": "Ethical banking",
            "type": "category",
            "hash": "#explore/banking",
            "score": 100,
            "reason": "alias",
            "key": "best bank"
          }
        ]
      }
    ]
  },
  "tokens": {
    "bank": [
      "ovs:cat/banking"
    ]
  },
  "aliases": {},
  "targets": {
    "ovs:cat/banking": {
      "type": "category",
      "label": "Ethical banking",
      "hash": "explore/banking"
    }
  },
  "stats": {
    "tokens": 1,
    "targets": 1
  }
}

The schema

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