AutoGineer
Generated banner for Content Modeling Best Practices
Generated logo for Content Modeling Best Practices

Content Modeling Best Practices

SanityOfficialPublished by Sanity

  • Skill
  • Guidelines
  • Software development
  • MIT
  • No issues found
Download ZIP

From the author

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.
— the description by Sanity

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a framework for designing structured content models that prioritize data integrity and reusability over presentation-driven layouts. It offers guidance on core architectural decisions, such as when to use references versus embedded objects, how to implement shared components, and strategies for managing taxonomies. While applicable to any headless CMS, it includes specific implementation patterns for Sanity, helping developers build systems that are future-proof and optimized for content editors.

What it does

  • Defines principles for separating content from presentation layers.
  • Provides decision frameworks for choosing between references and embedded objects.
  • Outlines patterns for content reuse, including shared components and field sets.
  • Offers guidance on structuring taxonomies for consistent content classification.
  • Helps identify and avoid common anti-patterns like over-abstraction.
  • Supports planning for omnichannel content delivery.

When to use it

  • When starting a new project and designing the initial content model.
  • When evaluating whether content should be structured or free-form.
  • When deciding between using references or embedding content directly.
  • When planning for multi-channel content delivery requirements.
  • When refactoring existing content structures to improve maintainability.

Advantages

  • Promotes a single source of truth to reduce content duplication.
  • Improves editor experience by streamlining content management workflows.
  • Ensures content is flexible enough for future, unknown delivery channels.
  • Reduces query complexity by applying appropriate modeling patterns.
  • Provides clear, actionable implementation examples for schema design.

Usage examples

“Should I use a reference or an embedded object for author profiles in my blog?”
The agent explains that author profiles should be referenced because they are reusable, need central management, and have their own lifecycle independent of individual blog posts.
“How can I avoid repeating SEO fields across my page and post types?”
The agent provides a pattern for creating a shared field set that can be spread into multiple document types, ensuring consistency and reducing code duplication.
“What are the signs that my content model is over-abstracted?”
The agent lists indicators such as references used only once, editors needing to navigate multiple documents for a single page, and complex queries joining rarely-shared content.
“How do I handle a product that needs to be referenced but occasionally requires a custom title?”
The agent suggests a hybrid approach using an object that contains both a reference to the canonical product and an optional override field for the title.

Install

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/sanity-io/content-modeling-best-practices/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip content-modeling-best-practices.zip -d .agents/skills

Documentation by Sanity

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. Future-proof — Design for channels that don't exist yet

  4. Editor-centric — Optimize for the people creating content

References

Start with the reference that matches the modeling decision in front of you, instead of loading every topic at once. See references/ for detailed guidance on specific topics:

  • references/separation-of-concerns.md — Separating content from presentation

  • references/reference-vs-embedding.md — When to use references vs embedded objects

  • references/content-reuse.md — Content reuse patterns and the reuse spectrum

  • references/taxonomy-classification.md — Flat, hierarchical, and faceted classification

Files

references/content-reuse.md

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.

// 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.

// Shared field definition
export const seoFields = [
  defineField({ name: 'seoTitle', type: 'string' }),
  defineField({ name: 'seoDescription', type: 'text' }),
  defineField({ name: 'ogImage', type: 'image' }),
]

// Spread into multiple types
defineType({
  name: 'page',
  fields: [
    defineField({ name: 'title', type: 'string' }),
    ...seoFields
  ]
})

defineType({
  name: 'post',
  fields: [
    defineField({ name: 'title', type: 'string' }),
    ...seoFields
  ]
})

Pattern 3: Taxonomy References

Centralize classification for consistent tagging.

Use case: Categories, tags, topics that span content types.

// Central taxonomy
defineType({
  name: 'category',
  type: 'document',
  fields: [
    defineField({ name: 'title', type: 'string' }),
    defineField({ name: 'slug', type: 'slug' }),
  ]
})

// Used across content types
defineField({
  name: 'categories',
  type: 'array',
  of: [{ type: 'reference', to: [{ type: 'category' }] }]
})

Pattern 4: Content Fragments

Small, reusable pieces that combine into larger content.

Use case: Bios, addresses, contact info.

// Fragment type
defineType({
  name: 'contactInfo',
  type: 'object',
  fields: [
    defineField({ name: 'email', type: 'email' }),
    defineField({ name: 'phone', type: 'string' }),
    defineField({ name: 'address', type: 'text' }),
  ]
})

// Reused across types
defineType({
  name: 'office',
  fields: [
    defineField({ name: 'name', type: 'string' }),
    defineField({ name: 'contact', type: 'contactInfo' }),
  ]
})

Anti-Pattern: Over-Abstraction

Not everything needs to be reusable. If content is only used in one place, embedding is simpler.

Signs of over-abstraction:

  • References that are only used once

  • Editors navigating multiple documents for one page

  • Complex queries joining rarely-shared content

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by
Sanity
Publisher
Sanity (Official)
Source
sanity-io/agent-toolkit · skills/content-modeling-best-practices · commit 3ed3a14
Licence
MIT License (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Sanity or Sanity.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download content-modeling-best-practices.zip