taxonomy-architecture

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