Taxonomy Architecture
Guidance for designing taxonomy systems for content classification, including categories, tags, and faceted navigation.
When to Use This Skill
- Designing category hierarchies for content
- Implementing tagging systems
- Planning faceted search and filtering
- Creating controlled vocabularies
- Migrating taxonomy structures between CMS platforms
Taxonomy Types
Flat Taxonomy (Tags)
Best for user-generated, flexible classification.
public class Tag
{
public Guid Id { get; set; }
public string Name { get; set; } = string.Empty;
public string Slug { get; set; } = string.Empty;
public int UsageCount { get; set; }
}
public class ContentTag
{
public Guid ContentItemId { get; set; }
public Guid TagId { get; set; }
public int Order { get; set; }
}Use Cases:
- Blog post tags
- Product keywords
- User-generated labels
- Folksonomy systems
Hierarchical Taxonomy (Categories)
Best for structured, controlled classification.
public class Category
{
public Guid Id { get; set; }
public string Name { get; set; } = string.Empty;
public string Slug { get; set; } = string.Empty;
public string? Description { get; set; }
// Hierarchy
public Guid? ParentId { get; set; }
public Category? Parent { get; set; }
public List<Category> Children { get; set; } = new();
// Materialized path for efficient queries
public string Path { get; set; } = string.Empty; // e.g., "/tech/programming/csharp"
public int Depth { get; set; }
public int Order { get; set; }
}Use Cases:
- Product categories (Electronics > Phones > Smartphones)
- Document classification
- Geographic hierarchies
- Organizational structures
Multi-Taxonomy System
Support multiple independent taxonomies.
public class Taxonomy
{
public Guid Id { get; set; }
public string Name { get; set; } = string.Empty;
public string Slug { get; set; } = string.Empty;
public TaxonomyType Type { get; set; } // Flat, Hierarchical
public bool AllowMultiple { get; set; } = true;
public bool IsRequired { get; set; }
public List<string> ApplicableContentTypes { get; set; } = new();
}
public class TaxonomyTerm
{
public Guid Id { get; set; }
public Guid TaxonomyId { get; set; }
public string Name { get; set; } = string.Empty;
public string Slug { get; set; } = string.Empty;
// For hierarchical taxonomies
public Guid? ParentTermId { get; set; }
public string? Path { get; set; }
public int Depth { get; set; }
public int Order { get; set; }
// Metadata
public Dictionary<string, object?> Metadata { get; set; } = new();
}
public enum TaxonomyType
{
Flat, // Tags, keywords
Hierarchical, // Categories with parent/child
Faceted // Multi-dimensional classification
}Hierarchy Patterns
Adjacency List (Simple)
CREATE TABLE Categories (
Id UNIQUEIDENTIFIER PRIMARY KEY,
Name NVARCHAR(200) NOT NULL,
ParentId UNIQUEIDENTIFIER NULL REFERENCES Categories(Id),
[Order] INT NOT NULL DEFAULT 0
);
-- Query children (one level)
SELECT * FROM Categories WHERE ParentId = @parentId ORDER BY [Order];
-- Recursive CTE for full tree
WITH CategoryTree AS (
SELECT Id, Name, ParentId, 0 AS Depth
FROM Categories WHERE ParentId IS NULL
UNION ALL
SELECT c.Id, c.Name, c.ParentId, ct.Depth + 1
FROM Categories c
INNER JOIN CategoryTree ct ON c.ParentId = ct.Id
)
SELECT * FROM CategoryTree;Materialized Path (Fast Reads)
CREATE TABLE Categories (
Id UNIQUEIDENTIFIER PRIMARY KEY,
Name NVARCHAR(200) NOT NULL,
Path NVARCHAR(1000) NOT NULL, -- '/root/parent/child'
Depth INT NOT NULL,
[Order] INT NOT NULL
);
CREATE INDEX IX_Categories_Path ON Categories(Path);
-- Query all descendants
SELECT * FROM Categories WHERE Path LIKE '/electronics/phones/%';
-- Query ancestors
SELECT * FROM Categories
WHERE '/electronics/phones/smartphones' LIKE Path + '%'
ORDER BY Depth;Nested Set (Complex but Powerful)
CREATE TABLE Categories (
Id UNIQUEIDENTIFIER PRIMARY KEY,
Name NVARCHAR(200) NOT NULL,
Lft INT NOT NULL, -- Left boundary
Rgt INT NOT NULL, -- Right boundary
Depth INT NOT NULL
);
-- Query all descendants
SELECT * FROM Categories
WHERE Lft > @parentLft AND Rgt < @parentRgt
ORDER BY Lft;
-- Query ancestors
SELECT * FROM Categories
WHERE Lft < @childLft AND Rgt > @childRgt
ORDER BY Lft;Faceted Classification
Facet Design
public class Facet
{
public Guid Id { get; set; }
public string Name { get; set; } = string.Empty;
public string Slug { get; set; } = string.Empty;
public FacetType Type { get; set; }
public List<FacetValue> Values { get; set; } = new();
}
public class FacetValue
{
public Guid Id { get; set; }
public Guid FacetId { get; set; }
public string Value { get; set; } = string.Empty;
public string? DisplayValue { get; set; }
public int Order { get; set; }
}
public enum FacetType
{
SingleSelect, // Radio buttons
MultiSelect, // Checkboxes
Range, // Price range, date range
Boolean, // Yes/No
Hierarchy // Nested options
}
// Product with facets
public class ProductFacets
{
public List<Guid> BrandIds { get; set; } = new();
public List<Guid> ColorIds { get; set; } = new();
public decimal? PriceMin { get; set; }
public decimal? PriceMax { get; set; }
public bool? InStock { get; set; }
}Faceted Search Query
public class FacetedSearchQuery
{
public string? SearchTerm { get; set; }
public Dictionary<string, List<string>> Facets { get; set; } = new();
public int Page { get; set; } = 1;
public int PageSize { get; set; } = 20;
}
public class FacetedSearchResult<T>
{
public List<T> Items { get; set; } = new();
public int TotalCount { get; set; }
public Dictionary<string, List<FacetCount>> FacetCounts { get; set; } = new();
}
public class FacetCount
{
public string Value { get; set; } = string.Empty;
public string DisplayValue { get; set; } = string.Empty;
public int Count { get; set; }
public bool IsSelected { get; set; }
}Taxonomy API Design
REST Endpoints
GET /api/taxonomies # List all taxonomies
GET /api/taxonomies/{id} # Get taxonomy with terms
GET /api/taxonomies/{id}/terms # List terms (flat or tree)
GET /api/taxonomies/{id}/terms/{termId} # Get single term
# Hierarchical navigation
GET /api/categories # Root categories
GET /api/categories/{id}/children # Child categories
GET /api/categories/{id}/ancestors # Breadcrumb path
GET /api/categories/{id}/descendants # Full subtree
# Content by taxonomy
GET /api/articles?category={slug}
GET /api/articles?tags=tag1,tag2
GET /api/products?facets[brand]=apple&facets[color]=blackGraphQL Schema
type Taxonomy {
id: ID!
name: String!
slug: String!
type: TaxonomyType!
terms(parentId: ID): [TaxonomyTerm!]!
termTree: [TaxonomyTerm!]!
}
type TaxonomyTerm {
id: ID!
name: String!
slug: String!
path: String
depth: Int!
parent: TaxonomyTerm
children: [TaxonomyTerm!]!
contentCount: Int!
}
type Query {
taxonomies: [Taxonomy!]!
taxonomy(id: ID, slug: String): Taxonomy
categoryByPath(path: String!): TaxonomyTerm
}Best Practices
Naming Conventions
| Pattern | Example | Use For |
|---|---|---|
| Singular | Category, Tag | Entity names |
| Plural | Categories, Tags | Collection endpoints |
| Slug format | web-development | URL-safe identifiers |
| Path format | /tech/web/frontend | Hierarchical paths |
Performance Optimization
// Cache taxonomy trees (they change infrequently)
public class TaxonomyCacheService
{
private readonly IMemoryCache _cache;
private readonly TimeSpan _cacheDuration = TimeSpan.FromMinutes(30);
public async Task<List<TaxonomyTerm>> GetTermTreeAsync(Guid taxonomyId)
{
var cacheKey = $"taxonomy:tree:{taxonomyId}";
if (!_cache.TryGetValue(cacheKey, out List<TaxonomyTerm>? tree))
{
tree = await BuildTermTreeAsync(taxonomyId);
_cache.Set(cacheKey, tree, _cacheDuration);
}
return tree!;
}
public void InvalidateCache(Guid taxonomyId)
{
_cache.Remove($"taxonomy:tree:{taxonomyId}");
}
}Content Count Denormalization
// Update counts when content is published/unpublished
public class ContentPublishedHandler : INotificationHandler<ContentPublishedEvent>
{
public async Task Handle(ContentPublishedEvent notification, CancellationToken ct)
{
// Increment term counts
foreach (var termId in notification.TaxonomyTermIds)
{
await _termRepository.IncrementCountAsync(termId);
}
}
}Related Skills
content-type-modeling- Attaching taxonomies to content typescontent-relationships- Term-to-content relationshipsheadless-api-design- Taxonomy API endpoints