Spec / ovs-ask-index
Open Values Ask Index v0.1
The full search index for Ask, the site's search box. It maps words and names to everything on the site, including single entries by name or barcode. The data build writes it, and the app loads it only when a search needs product names or barcodes.
- Files built from other files
- Status: stable
- Version: 0.1
- Format name in the file:
ovs-ask-index
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 product search.
Fields
| Field | What it means | Type |
|---|---|---|
format required | Names this file's format, so a reader can check it before reading the rest of the file. | always "ovs-ask-index" |
version required | The version of the format this file follows, such as "0.1". | string |
built required | The date of the source data this file was built from, as YYYY-MM-DD. | string |
source required | The files this index was built from, as paths in the repository. | see sourceList |
loadHint required | Always "lazy-product-search": the app loads this file only when a search needs product names or barcodes. | always "lazy-product-search" |
budget required | The size limit for this file and how it is measured. | see budget |
shards required | Whether the index is split across several files, and which. | see shards |
tokens required | A map from each normalized word or phrase to the ids it can find, at most 24 per key. Covers categories, entries, brands, companies, tags, errands, lines and guides. | see tokenMap |
aliases required | A map from each normalized name to the one id it names exactly, such as "7up" to "ovs:brand/7up". | see aliasMap |
stats required | Counts by name, such as "tokens", "aliases", "items" (entries) and "barcodeLikeItems" (entries whose code looks like a barcode). | 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 full Ask index maps search tokens and aliases to Open Values targets.
{
"format": "ovs-ask-index",
"version": "0.1",
"built": "2026-07-07",
"source": [
"app/data/index.json"
],
"tokens": {
"bank": [
"ovs:cat/banking"
],
"sample product": [
"ovs:item/banking/sample"
]
},
"aliases": {
"best bank": "ovs:cat/banking"
},
"stats": {
"tokens": 2,
"aliases": 1
},
"loadHint": "lazy-product-search",
"budget": {
"maxBytes": 6000000,
"currentBytes": 1000,
"withinBudget": true,
"measurement": "UTF-8 bytes of the generated pretty JSON file",
"actionWhenExceeded": "Shard the token and alias tables before app-owned code treats this as a single lazy fetch."
},
"shards": {
"status": "not-needed",
"count": 1,
"files": [
"ask-index.json"
],
"hint": "Single lazy file is allowed while currentBytes stays under maxBytes; add shard files only after the budget is exceeded."
}
}
A file that must be rejected
Ask token values must be non-empty target arrays.
{
"format": "ovs-ask-index",
"version": "0.1",
"built": "2026-07-07",
"source": [
"app/data/index.json"
],
"tokens": {
"bank": []
},
"aliases": {},
"stats": {
"tokens": 1
},
"loadHint": "lazy-product-search",
"budget": {
"maxBytes": 6000000,
"currentBytes": 1000,
"withinBudget": true,
"measurement": "UTF-8 bytes of the generated pretty JSON file",
"actionWhenExceeded": "Shard the token and alias tables before app-owned code treats this as a single lazy fetch."
},
"shards": {
"status": "not-needed",
"count": 1,
"files": [
"ask-index.json"
],
"hint": "Single lazy file is allowed while currentBytes stays under maxBytes; add shard files only after the budget is exceeded."
}
}
The schema
Its address is https://openvaluesstandard.org/schema/ask-index-v0.1.schema.json. Validators can fetch it there; the file is also in the repository at app/data/standard/schemas/ask-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.