content-modeling-best-practices — Content, an agent skill published by sanity-io/agent-toolkit

# Content Reuse Patterns

Effective content models maximize reuse while minimizing duplication. Here are patterns for achieving both.

## The Content Reuse Spectrum

```
Full Duplication ←————————————————→ Full Reference
(Copy everything)                    (Link to one source)
```

Most real-world content sits somewhere in between.

## Pattern 1: Shared Components

Create reusable content blocks that can be embedded anywhere.

**Use case:** Testimonials, FAQs, CTAs that appear on multiple pages.

```typescript
// Standalone testimonial documents
defineType({
  name: 'testimonial',
  type: 'document',
  fields: [
    defineField({ name: 'quote', type: 'text' }),
    defineField({ name: 'author', type: 'string' }),
    defineField({ name: 'company', type: 'string' }),
  ]
})

// Reference in page builders
defineField({
  name: 'pageBuilder',
  type: 'array',
  of: [
    { type: 'reference', to: [{ type: 'testimonial' }] }
  ]
})
```

## Pattern 2: Shared Field Sets

Extract common fields into reusable definitions.

**Use case:** SEO fields, social metadata, common dates.

```typescript
// Shared field definition
export const seoFields = [
  defineField({ name: 'seoTitle', type: 'str

# Reference vs Embedding Content

When should content be linked (referenced) vs copied (embedded)? This decision affects reusability, query complexity, and editing workflows.

## The Trade-offs

| Aspect | Reference | Embedded Object |
|--------|-----------|-----------------|
| Reusability | ✅ Shared across documents | ❌ Copied per document |
| Single source | ✅ Update once, reflects everywhere | ❌ Must update each copy |
| Query complexity | Requires joins/expansion | Inline, simpler queries |
| Editing UX | Separate editing interface | All fields in one place |
| Independence | Can exist on its own | Only exists within parent |

## When to Reference

Use references when content:
- **Is reusable** — Same author across many articles
- **Needs central management** — Update product info once
- **Has its own lifecycle** — Published/draft independent of parent
- **Should stay in sync** — Price changes reflect everywhere

**Examples:**
- Author profiles
- Product catalog items
- Shared testimonials
- Category taxonomy
- Reusable CTAs

## When to Embed

Use embedded objects when content:
- **Is unique to this document** — Page-specific hero
- **Doesn't make sense alone** — SEO metadata
-

# Separation of Content and Presentation

The most important principle in structured content: **separate what content IS from how it LOOKS**.

## The Problem

When content is tied to presentation:
- Redesigns require content migration
- Content can't be reused across channels (web, mobile, voice)
- Editors make design decisions instead of content decisions
- A/B testing requires duplicate content

## The Principle

Model content based on **meaning and purpose**, not visual appearance.

### Bad: Presentation-Focused

```
BigHeroText       → What if we want small heroes?
RedButton         → What if brand colors change?
ThreeColumnLayout → What if mobile needs one column?
LeftSidebar       → Position is a frontend concern
MobileImage       → Device-specific content is fragile
```

### Good: Meaning-Focused

```
Headline          → The main message (render however)
CallToAction      → An action we want users to take
Features          → A list of things (columns decided by frontend)
RelatedContent    → Content relationships (position by context)
Image             → One image with responsive crops
```

## Testing Your Model

Ask: "If we completely redesigned the site, would these field n

# 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"

```typescript
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

```typescript
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 filteri

---
name: content-modeling-best-practices
description: Structured content modeling guidance for schema design, content architecture, content reuse, references versus embedded objects, separation of concerns, and taxonomies across Sanity and other headless CMSes. Use this skill when designing or refactoring content types, deciding field shapes, debating reusable versus nested content, planning omnichannel content models, or reviewing whether a schema is too page-shaped or presentation-driven.
---

# Content Modeling Best Practices

Principles for designing structured content that's flexible, reusable, and maintainable. These concepts apply to any headless CMS but include Sanity-specific implementation notes.

## When to Apply

Reference these guidelines when:
- Starting a new project and designing the content model
- Evaluating whether content should be structured or free-form
- Deciding between references and embedded content
- Planning for multi-channel content delivery
- Refactoring existing content structures

## Core Principles

1. **Content is data, not pages** — Structure content for meaning, not presentation
2. **Single source of truth** — Avoid content duplication
3. **Futu