◇ Open Values Standardfor builders

Spec / open-values-taxonomy

Conscious Consuming Taxonomy v1

The full map of decisions the catalogue means to cover, in four levels from broad areas of life down to single decisions, with how many are built so far. It is checked against the United Nations COICOP spending categories so nothing is left out by accident. Conscious Consuming keeps it.

Draft. It may still change before it is called stable. A file someone writes by hand or with a tool, and keeps.

Who writes it and who reads it

Written by pipeline/build_taxonomy.py. Read by content planning, docs/SWARM-BRIEF.md lanes, coverage reporting.

Fields

FieldWhat it meansType
format requiredAlways "open-values-taxonomy". Tells a reader that this file is the full map of decisions.always "open-values-taxonomy"
version requiredThe version of this file's format, as major.minor.patch, such as "1.0.0".string
noteA paragraph for maintainers saying what the file is, where it is written and which script checks it.string
levels requiredThe four levels of the map, from the top down, each with a one-line description of what that level holds.list of object
facets requiredThe six ways every decision is labelled across the map (need, type, mode, cadence, actor and scope), each with its allowed values.map of object
coicop requiredThe external referee. Every division must be claimed by at least one realm; the audit fails otherwise.object
counts requiredPublished coverage. Recomputed from the realms by research/taxonomy_audit.js, so the file cannot misreport itself.map of number
byNeedCoverage for each of the eight needs, keyed by need id: how many decisions are in scope and how many have a built facts file. Decisions marked out are not counted.object
byDivisionCoverage for each COICOP division, keyed by its two-digit code: the division's title, the ids of the top-level areas that claim it, and how many of their decisions are in scope and built.object
realms requiredThe top-level areas of the map, such as "Food and drink", each holding its fields, families and decisions.list of object

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.

The schema

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