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]=black

GraphQL 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 types
content-relationships - Term-to-content relationships
headless-api-design - Taxonomy API endpoints

taxonomy-architecture