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
Should be copied, not linked — Historical snapshot
Simplifies editing — All fields in one form

Examples:

SEO metadata
Page-specific sections
Address information
Social links
Configuration options

Sanity Implementation

// Reference: Author is reusable
defineField({
  name: 'author',
  type: 'reference',
  to: [{ type: 'author' }]
})

// Embedded: SEO is page-specific
defineField({
  name: 'seo',
  type: 'object',
  fields: [
    defineField({ name: 'title', type: 'string' }),
    defineField({ name: 'description', type: 'text' })
  ]
})

The Hybrid Approach

Sometimes you want both: a reference for the canonical data, plus embedded overrides.

defineField({
  name: 'featuredProduct',
  type: 'object',
  fields: [
    defineField({ 
      name: 'product', 
      type: 'reference', 
      to: [{ type: 'product' }] 
    }),
    defineField({ 
      name: 'overrideTitle', 
      type: 'string',
      description: 'Optional: Override the product title for this context'
    }),
  ]
})

Query uses coalesce(overrideTitle, product->title).

2.3 KiB Raw Blame History