Setting the file. One moment.
Skill 02 · Content Modeling Best Practices
Subchapter 2.4
references/taxonomy-classification.mdMarkdown3 KBView on GitHub
Organizing content with taxonomies enables filtering, navigation, and content relationships. Well-designed taxonomies scale; poorly designed ones become maintenance nightmares.
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' }),
]
})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)'
}),
]
})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' }] })Categories should be distinct. If items frequently belong to multiple categories, consider tags instead.
Categories: One primary classification Tags: Many optional classifications
Use terms your audience uses, not internal jargon.
Bad: “Content Assets” (internal term) Good: “Resources” or “Downloads” (user term)
Too shallow: Everything lumped together Too deep: Users can’t find anything
Rule of thumb: 3-4 levels max for hierarchies
Design for 10x growth. Will your structure work with 10,000 items?
*[_type == "product" && category._ref == $categoryId]// First get all descendant category IDs
*[_type == "product" && category._ref in
*[_type == "category" && (
_id == $categoryId ||
parent._ref == $categoryId ||
parent->parent._ref == $categoryId
)]._id
]*[_type == "category" && !defined(parent)]{
title,
slug,
"children": *[_type == "category" && parent._ref == ^._id]{
title,
slug,
"children": *[_type == "category" && parent._ref == ^._id]{
title,
slug
}
}
}Creating a category for everything results in mostly-empty categories.
Fix: Start minimal, add categories as content grows.
Some categories broad (“Technology”), others narrow (“React 18 Server Components”).
Fix: Define clear criteria for category creation.
Anyone can create taxonomy terms, leading to duplicates and inconsistency.
Fix: Limit who can create/edit taxonomy documents. Use validation.