Skip to main content

Taxonomy management

The taxonomy is a tree. Categories group things (Theme, Features, Volatility); characteristics are the leaves a game can be tagged with (Fantasy, Free spins, High). Every rule about the tree lives in TaxonomyService (src/Kaleido.Taxonomy.Infrastructure/TaxonomyService.cs), so the REST endpoints, the MCP tools and the importers all behave the same.

Rules​

RuleWhy
Only characteristics can be tagged on a gameCategories are for grouping and for weighting similarity
A characteristic must sit inside a categoryKeeps every tag explainable by its path
A single-value category allows one of its characteristics per gameVolatility cannot be both Low and High
A node's type never changesChanging a tagged characteristic into a category would orphan tags
Names cannot contain /, and siblings cannot share a name/ separates path segments (Theme / Fantasy)
Only categories can contain nodes; a node cannot move inside itselfKeeps the tree a tree
A category with children, or a characteristic used by games, cannot be deletedMerge instead, so no tag is lost
Every change bumps taxonomy_state.VersionConsumers (snapshot, similarity fingerprint) can tell the tree moved
Import adds, never deletes; max 5,000 nodesSafe to re-import an export from another environment
Merge moves games to the target and keeps the old name as a synonymNothing is lost when duplicates are cleaned up

Operations​

OperationEndpointMCP tool
Read the tree with game countsGET /taxonomy/treeget_taxonomy_tree
Find by name, synonym or path suffix(client-side)find_characteristics
CreatePOST /taxonomy/nodescreate_taxonomy_node
Rename, move, synonyms, single-valuePUT /taxonomy/nodes/{id}update_taxonomy_node
MergePOST /taxonomy/nodes/{id}/mergemerge_taxonomy_nodes
DeleteDELETE /taxonomy/nodes/{id} (409 when it has children or games)not exposed
ExportGET /taxonomy/snapshotnot exposed
ImportPOST /taxonomy/importnot exposed

Snapshot format​

The export matches the internal taxonomy model, with PascalCase names and empty Children omitted. Import accepts a snapshot, a { Game, TaxonomySnapshot } envelope, or a bare Tree array.

{
"Version": "2026-11-15T10:20:43Z",
"Tree": [
{ "Name": "Theme", "Type": "Category", "Children": [
{ "Name": "Fantasy", "Type": "Characteristic" }
]}
]
}

GET /games/{id}/snapshot returns one game with only its own characteristics and their ancestors (?full=true for the whole tree).

Tagging a game by hand​

PUT /games/{id}/characteristics replaces the whole set:

  1. Unknown ids, categories, or two values in a single-value category give 400 with the reason.
  2. Tags not in the new set are removed.
  3. AI-suggested (Inferred) tags that are still selected become Manual with confidence 1: saving the editor counts as review.
  4. New tags are added as Manual.

CSV import (POST /games/import) accepts a pipe-separated characteristics column with names, or paths when a name is ambiguous.