@instruments/taxonomy

The canonical, data-only interiors and architecture terminology corpus.

Version one contract

The package root exports the governed corpus and its release metadata:

• TAXONOMY_BASE_URI - the authority used for every canonical concept URI.
• KNOWLEDGE_GRAPH - normalized axis, facet, and concept nodes plus typed, bidirectional edges.
• LEXICAL_ENTRIES - exhaustive declarative equivalent, ambiguous, and declined records for every canonical or observed authored spelling.
• TAXONOMY_CORPUS_METADATA - deterministic node, edge, and lexical counts with the corpus revision, snapshot, and package version.
• TAXONOMY_CORPUS_REVISION, TAXONOMY_SNAPSHOT, and TAXONOMY_VERSION - the exact content fingerprint, source snapshot, and package release identifiers.

It also exports the TypeScript types for those values. It does not export a resolver, matcher, ranker, search route, local IDs, semantic IDs, or legacy aliases. Consumers build policy on top of the same data; the repository's private HTTP adapter is one such consumer.

Every public identity is a permanent HTTPS URI with lowercase kebab-case path segments:

https://taxonomy.materialinstruments.com/id/axis/material
https://taxonomy.materialinstruments.com/id/facet/palette/hue
https://taxonomy.materialinstruments.com/id/material/walnut

ColorScope remains authoritative for colour concepts. Taxonomy does not mint graph nodes or URIs for ColorScope-governed terms; lexical records reference ColorScope identifiers without merging them into Taxonomy hierarchy. For example, walnut has a governed primary material reading and a secondary ColorScope reading. Two more phrases carry an ordered reading between two material concepts: quartz (engineered quartz before the mineral) and melamine (melamine-faced board before the resin).

Install and consume

pnpm add @instruments/taxonomy

import {
  KNOWLEDGE_GRAPH,
  LEXICAL_ENTRIES,
  TAXONOMY_CORPUS_METADATA,
} from "@instruments/taxonomy";

const walnut = KNOWLEDGE_GRAPH.nodes.find(
  (node) =>
    node.kind === "concept" &&
    node.uri === "https://taxonomy.materialinstruments.com/id/material/walnut"
);

const walnutReadings = LEXICAL_ENTRIES.find(
  (entry) => entry.phrase === "walnut"
);

Changes to canonical meaning or identity are governed corpus changes. There is deliberately no backward-compatibility layer in V1; consumers migrate to the canonical URI.

Pin the exact package version and compare TAXONOMY_CORPUS_REVISION when a deployment needs to detect content drift. The revision is computed from the normalized graph and lexical entries, so it changes when governed corpus content changes even if the V1 API shape does not.