◇ Open Values Standardfor builders

Spec / ovs-synonym-registry

Open Values Synonym Registry v0.1

A list of everyday words people search with, each pointing to the category or tag it means, such as "pop" to the soda category. Conscious Consuming keeps it.

Stable. A change that breaks existing files needs a new version. A file someone writes by hand or with a tool, and keeps.

Who writes it and who reads it

Written by pipeline/build_tags.js. Read by Ask, node search.

Fields

FieldWhat it meansType
format requiredAlways "ovs-synonym-registry". Tells a reader that this file maps everyday words to categories and tags.always "ovs-synonym-registry"
version requiredThe version of the synonym registry format this file follows, 0.1.string
updated requiredThe day the file was last changed, as YYYY-MM-DD.string
synonyms requiredWords people search with, each mapped to the category or tag it means, such as "pop" to "ovs:cat/soda". Each target is written "ovs:cat/" or "ovs:tag/" followed by an id.map 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

Synonyms map ordinary terms to category or tag targets.

{
  "format": "ovs-synonym-registry",
  "version": "0.1",
  "updated": "2026-07-07",
  "synonyms": {
    "pop": "ovs:cat/soda"
  }
}

A file that must be rejected

Synonym targets must be namespaced category or tag ids.

{
  "format": "ovs-synonym-registry",
  "version": "0.1",
  "updated": "2026-07-07",
  "synonyms": {
    "pop": "soda"
  }
}

The schema

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