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
| Rule | Why |
|---|---|
| Only characteristics can be tagged on a game | Categories are for grouping and for weighting similarity |
| A characteristic must sit inside a category | Keeps every tag explainable by its path |
| A single-value category allows one of its characteristics per game | Volatility cannot be both Low and High |
| A node's type never changes | Changing 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 itself | Keeps the tree a tree |
| A category with children, or a characteristic used by games, cannot be deleted | Merge instead, so no tag is lost |
Every change bumps taxonomy_state.Version | Consumers (snapshot, similarity fingerprint) can tell the tree moved |
| Import adds, never deletes; max 5,000 nodes | Safe to re-import an export from another environment |
| Merge moves games to the target and keeps the old name as a synonym | Nothing is lost when duplicates are cleaned up |
Operations
| Operation | Endpoint | MCP tool |
|---|---|---|
| Read the tree with game counts | GET /taxonomy/tree | get_taxonomy_tree |
| Find by name, synonym or path suffix | (client-side) | find_characteristics |
| Create | POST /taxonomy/nodes | create_taxonomy_node |
| Rename, move, synonyms, single-value | PUT /taxonomy/nodes/{id} | update_taxonomy_node |
| Merge | POST /taxonomy/nodes/{id}/merge | merge_taxonomy_nodes |
| Delete | DELETE /taxonomy/nodes/{id} (409 when it has children or games) | not exposed |
| Export | GET /taxonomy/snapshot | not exposed |
| Import | POST /taxonomy/import | not 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:
- Unknown ids, categories, or two values in a single-value category give
400with the reason. - Tags not in the new set are removed.
- AI-suggested (
Inferred) tags that are still selected becomeManualwith confidence 1: saving the editor counts as review. - 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.