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.
- Files people or tools write
- Status: draft
- Version: 1.0.0
- Format name in the file:
open-values-taxonomy
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
| Field | What it means | Type |
|---|---|---|
format required | Always "open-values-taxonomy". Tells a reader that this file is the full map of decisions. | always "open-values-taxonomy" |
version required | The version of this file's format, as major.minor.patch, such as "1.0.0". | string |
note | A paragraph for maintainers saying what the file is, where it is written and which script checks it. | string |
levels required | The four levels of the map, from the top down, each with a one-line description of what that level holds. | list of object |
facets required | The 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 required | The external referee. Every division must be claimed by at least one realm; the audit fails otherwise. | object |
counts required | Published coverage. Recomputed from the realms by research/taxonomy_audit.js, so the file cannot misreport itself. | map of number |
byNeed | Coverage 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 |
byDivision | Coverage 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 required | The 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.