/content-modeling-best-practices

Taxonomy and Classification

Organizing content with taxonomies enables filtering, navigation, and content relationships. Well-designed taxonomies scale; poorly designed ones become maintenance nightmares.

Types of Classification

Flat Taxonomy

Simple list of terms with no hierarchy.

Use for: Tags, simple categories Example: Blog tags: "javascript", "react", "tutorial"

defineType({
  name: 'tag',
  type: 'document',
  fields: [
    defineField({ name: 'title', type: 'string' }),
    defineField({ name: 'slug', type: 'slug' }),
  ]
})

Hierarchical Taxonomy

Terms with parent-child relationships.

Use for: Product categories, content sections Example: Electronics > Phones > Smartphones

defineType({
  name: 'category',
  type: 'document',
  fields: [
    defineField({ name: 'title', type: 'string' }),
    defineField({ name: 'slug', type: 'slug' }),
    defineField({ 
      name: 'parent', 
      type: 'reference', 
      to: [{ type: 'category' }],
      description: 'Parent category (leave empty for top-level)'
    }),
  ]
})

Faceted Classification

Multiple independent dimensions.

Use for: Complex filtering (e-commerce) Example: Filter by color AND size AND price range

// Multiple taxonomy types
defineField({ name: 'color', type: 'reference', to: [{ type: 'color' }] })
defineField({ name: 'size', type: 'reference', to: [{ type: 'size' }] })
defineField({ name: 'material', type: 'reference', to: [{ type: 'material' }] })

Design Principles

1. Mutual Exclusivity (When Appropriate)

Categories should be distinct. If items frequently belong to multiple categories, consider tags instead.

Categories: One primary classification Tags: Many optional classifications

2. User-Centric Naming

Use terms your audience uses, not internal jargon.

Bad: "Content Assets" (internal term) Good: "Resources" or "Downloads" (user term)

3. Balanced Depth

Too shallow: Everything lumped together Too deep: Users can't find anything

Rule of thumb: 3-4 levels max for hierarchies

4. Scalable Structure

Design for 10x growth. Will your structure work with 10,000 items?

Querying Taxonomies

Get all items in a category

*[_type == "product" && category._ref == $categoryId]

Get items in category OR children

// First get all descendant category IDs
*[_type == "product" && category._ref in 
  *[_type == "category" && (
    _id == $categoryId || 
    parent._ref == $categoryId ||
    parent->parent._ref == $categoryId
  )]._id
]

Get category tree

*[_type == "category" && !defined(parent)]{
  title,
  slug,
  "children": *[_type == "category" && parent._ref == ^._id]{
    title,
    slug,
    "children": *[_type == "category" && parent._ref == ^._id]{
      title,
      slug
    }
  }
}

Common Mistakes

Over-categorization

Creating a category for everything results in mostly-empty categories.

Fix: Start minimal, add categories as content grows.

Inconsistent Granularity

Some categories broad ("Technology"), others narrow ("React 18 Server Components").

Fix: Define clear criteria for category creation.

No Governance

Anyone can create taxonomy terms, leading to duplicates and inconsistency.

Fix: Limit who can create/edit taxonomy documents. Use validation.