◇ Open Values Standardfor builders

Spec / ovs-synonym-index

Open Values Synonym Index v0.1

A lookup from everyday words people type, such as "oat milk", to the category or label on the site they mean. The data build writes it from content/synonyms.json, and Ask search reads it.

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_tags.js. Read by Ask, node 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-synonym-index"
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 file the synonyms come from, content/synonyms.json.string
aliases requiredA map from each everyday term, as written in content/synonyms.json, to the category or tag id it means, such as "oat milk" to "ovs:cat/plant-based-milk".see targetMap
normalized requiredThe same map, keyed by each term after normalization, for matching what people type.see targetMap
targets requiredA map from each category or tag id to the terms that point at it.map of list of string

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 generated synonym index maps aliases and normalized aliases to category or tag targets.

{
  "format": "ovs-synonym-index",
  "version": "0.1",
  "built": "2026-07-07",
  "source": "content/synonyms.json",
  "aliases": {
    "bank": "ovs:cat/banking"
  },
  "normalized": {
    "bank": "ovs:cat/banking"
  },
  "targets": {
    "ovs:cat/banking": [
      "bank"
    ]
  }
}

A file that must be rejected

Generated synonym targets must remain namespaced category or tag ids.

{
  "format": "ovs-synonym-index",
  "version": "0.1",
  "built": "2026-07-07",
  "source": "content/synonyms.json",
  "aliases": {
    "bank": "banking"
  },
  "normalized": {
    "bank": "ovs:cat/banking"
  },
  "targets": {
    "ovs:cat/banking": [
      "bank"
    ]
  }
}

The schema

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