◇ Open Values Standardfor builders

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.

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

FieldWhat it meansType
format requiredNames this file's format. Always "ovs-node-index"; brands.json, companies.json, tags.json and errands.json all use it.always "ovs-node-index"
typeWhich kind of node this file holds: "brand", "company", "tag" or "errand". Missing in the hand-written sample.json.string
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
minItemsThe fewest entries a node needs to be listed. Brands need 2; tags take the number from content/tags.json.integer
sourceThe file or files this index was built from, as paths in the repository.string or array
nodes requiredThe nodes in this index.list
longTailBrands only: how many brand names were left out because they appear on fewer than 2 entries.integer
longTailItemsBrands only: how many entries carry one of those left-out brand names.integer
descriptorItemsBrands 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.