Reference Vs Embedding · Content Modeling Best Practices · sanity-io/agent-toolkit · Skills Docs

Reference Vs Embedding · Content Modeling Best Practices · sanity-io/agent-toolkit · Skills Docs

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

// 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' })
  ]
})

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'
    }),
  ]
})