Spec / ovs-node-index
Open Values Node Index v0.1
A list of the things a reader can look up on the site besides single entries: brands, the companies that own them, labels such as "organic", and errands. The data build writes one file per kind (brands.json, companies.json, tags.json, errands.json), and the site's search and node pages read them.
- Files built from other files
- Status: stable
- Version: 0.1
- Format name in the file:
ovs-node-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, pipeline/build_tags.js, pipeline/build_errands.js. Read by Ask, node pages, Discover.
Fields
| Field | What it means | Type |
|---|---|---|
format required | Names this file's format. Always "ovs-node-index"; brands.json, companies.json, tags.json and errands.json all use it. | always "ovs-node-index" |
type | Which kind of node this file holds: "brand", "company", "tag" or "errand". Missing in the hand-written sample.json. | string |
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 |
minItems | The fewest entries a node needs to be listed. Brands need 2; tags take the number from content/tags.json. | integer |
source | The file or files this index was built from, as paths in the repository. | string or array |
nodes required | The nodes in this index. | list |
longTail | Brands only: how many brand names were left out because they appear on fewer than 2 entries. | integer |
longTailItems | Brands only: how many entries carry one of those left-out brand names. | integer |
descriptorItems | Brands only: how many entries have a brand field that is not a usable brand name, such as "n/a" or a value listed in content/non-brand-values.json. These entries are not grouped under any brand. | integer |
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 node index lists namespaced nodes with labels and optional runtime metadata.
{
"format": "ovs-node-index",
"type": "brand",
"version": "0.1",
"built": "2026-07-07",
"source": "Fixture",
"nodes": [
{
"id": "ovs:brand/sample",
"type": "brand",
"label": "Sample",
"aliases": [
"sample brand"
],
"items": 1,
"categories": [
"banking"
],
"ownedBy": null,
"top": [
{
"cat": "banking",
"code": "sample",
"name": "Sample",
"score": 80
}
]
}
]
}
A file that must be rejected
Node ids must be unique inside an index.
{
"format": "ovs-node-index",
"version": "0.1",
"built": "2026-07-07",
"nodes": [
{
"id": "ovs:brand/sample",
"label": "Sample"
},
{
"id": "ovs:brand/sample",
"label": "Sample duplicate"
}
]
}
The schema
Its address is https://openvaluesstandard.org/schema/node-index-v0.1.schema.json. Validators can fetch it there; the file is also in the repository at app/data/standard/schemas/node-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.