Taxonomies

A taxonomy is a controlled vocabulary: a small set of kinds and, under each kind, the terms that belong to it. "Employee" and "Customer company" are kinds; "Hannah Taylor" is a term of the kind "Employee". A term can carry alternative labels ("Hannah"), which name the same thing, and hidden labels, which are matched but never shown as the preferred name.

Taxonomies are stored in the ontology service, so they follow its rules for clearance, history and audit. They are modelled on SKOS, which is also how you import and export them.

Kinds and terms

Every taxonomy records where it came from. Today a taxonomy is imported: loaded from a SKOS file (see Import and export SKOS). Producing taxonomies automatically from a knowledge base is not yet available. Each term also records its own source, which becomes manual once a person edits it (see Edit a term).

Browse a taxonomy

Open Ontology → Taxonomies in Analytics and pick a taxonomy from the list. The list holds only the taxonomies your clearance allows, ordered by name; use Load more when your organization has more than one page. The page then shows three things:

• Kinds — the kinds as a tree, following each kind's parent.
• Terms — a paged table of terms with their kind, labels and source.
• Publications — the revision history of the taxonomy ontology, read-only. Revisions are shared by every taxonomy in your organization, not only the one on screen.

The same list is available through the API as GET /kernel/taxonomies (taxonomies.list in the SDK). It returns a page of up to limit taxonomies (50 by default, at most 100) and a nextCursor; pass that cursor as after to fetch the next page. nextCursor is null on the last page.

You cannot roll a taxonomy back from this page. Publishing and rolling back are done by the taxonomy service itself, not by a person, so the page offers no rollback control.

Clearance

Each kind and each term has its own classification marking, and you only see what your clearance allows:

• A taxonomy, kind or term above your clearance is not listed. A hidden taxonomy is simply absent from the taxonomy list: it is not counted and does not affect paging.
• A term whose kind is above your clearance is still listed if you may see the term, but its kind is shown as Withheld. The same applies to a parent kind: a reference to a kind you may not see is left out, never shown by name. This holds in the page, the API, the SDK and the SKOS export alike.
• A taxonomy that does not exist and a taxonomy above your clearance answer the same way: "This taxonomy does not exist, or it is above your clearance."

Edit a term

Organization administrators can correct a term from the terms table (Edit term). You can change its kind and its alternative and hidden labels. The preferred label identifies the term, so it cannot change here.

• Saving records a manual edit. The term's source becomes manual, which marks it as a person's correction. Automatic updates, once available, will never overwrite a term whose last change was manual.
• The marking does not change. An edit keeps the term's classification marking. A request that tries to give an existing term a different marking is refused with a 409 (MARKING_CHANGE_REFUSED). To reclassify a term, remove it and write it again under the new marking.
• A term whose kind is withheld from you cannot be edited, because you could not see what you would be changing.
• One marking per request. A write that names no marking may only name terms that already exist and share one marking. Otherwise it is refused with a 400: MARKING_REQUIRED when a named term is new, MIXED_TERM_MARKINGS when the terms span several markings. Send one request per marking.
• Reading your own edit. A term write returns a watermark. Pass it as minSeq when you list terms (taxonomies.listTerms({ name, minSeq })) and the server waits briefly until the edit is readable. If it is still not readable, the server answers 503 PROJECTION_LAGGING instead of returning the list from before your edit. The terms table does this after every save.

Import and export SKOS

Organization administrators can import a SKOS vocabulary in Turtle format through the taxonomy import endpoint, POST /kernel/taxonomies/{name}/import (taxonomies.import in the SDK). The request names the taxonomy, carries the Turtle text, the marking to apply, and an idempotency key.

• An import creates or replaces a taxonomy whose source is imported, and never overwrites a taxonomy from any other source. Names that start with kb- are reserved for taxonomies the platform will produce from a knowledge base (not yet available), so an import cannot claim them.
• Re-importing a file replaces its kinds; terms that disappeared from the file are not removed automatically.
• An import is checked against your clearance, the same as any other write. The generic ontology import (/kernel/rdf/import) and the generic action and schema paths refuse the taxonomy ontology (TAXONOMY_ONTOLOGY_RESERVED), so there is exactly one way in.

To export, run the ontology RDF export on the taxonomy ontology, scrydon-knowledge-taxonomies. Taxonomies come out as skos:ConceptScheme, kinds and terms as skos:Concept, with skos:prefLabel, skos:altLabel, skos:hiddenLabel, skos:broader and skos:inScheme. The export is built from what you can read: hidden references are left out and a taxonomy above your clearance is not exported. Terms are exported as they are now, even when the export is pinned to an older revision.

Related

• Branches & proposals — how schema changes are versioned and published.
• Concepts — the layers of the ontology, including permissions.