Common Sanity Schema Mistakes & Best Practices

When building content backends with Sanity, developers often fall into traps that make their schemas hard to maintain or difficult to scale. Drawing from our team's opinionated guidelines, here are the most common mistakes and what you should do instead.

Mistake 1: Modeling for Presentation

The most common error is modeling "what things look like" instead of "what things are".

Don't do this: Naming fields based on their visual appearance in a specific design.

defineField({
  name: 'bigRedButton',
  type: 'object',
  fields: [
    {name: 'text', type: 'string'},
    {name: 'url', type: 'string'}
  ]
})

Do this instead: Model the intent of the content.

defineField({
  name: 'primaryCallToAction',
  type: 'object',
  fields: [
    defineField({name: 'label', type: 'string'}),
    defineField({name: 'destination', type: 'url'})
  ]
})

By decoupling content from presentation, you can redesign your frontend without migrating your data.

Mistake 2: Ignoring Type Safety Helpers

Sanity provides helper functions to ensure your schema is valid and strictly typed.

Don't do this: Using plain objects for schema definitions.

export default {
  name: 'blog',
  type: 'document',
  fields: [...]
}

Do this instead: Always use defineType, defineField, and defineArrayMember.

import {defineType, defineField} from 'sanity'

export default defineType({
  name: 'blog',
  type: 'document',
  fields: [
    defineField({
      name: 'title',
      type: 'string'
    })
  ]
})

Mistake 3: Boolean Traps

Boolean fields are tempting for toggles, but they paint you into a corner if requirements change.

Don't do this: Using a boolean for state that might become non-binary.

defineField({
  name: 'isPublished',
  type: 'boolean'
})

Do this instead: Use a string field with a list of options. It's extensible and clearer.

defineField({
  name: 'status',
  type: 'string',
  options: {
    list: [
      {title: 'Draft', value: 'draft'},
      {title: 'Published', value: 'published'},
      {title: 'Archived', value: 'archived'}
    ],
    layout: 'radio'
  }
})

Mistake 4: Missing Context

Schemas without descriptions or validation leave editors guessing.

Do this: Include brief, useful descriptions and validation rules.

defineField({
  name: 'slug',
  title: 'URL Slug',
  description: 'The unique URL part for this page',
  type: 'slug',
  validation: (rule) => rule.required().error('A slug is required for the page to be reachable')
})

Summary

Good content modeling is about creating a structured, semantic representation of your domain. By following these practices, you ensure your content backend remains flexible, maintainable, and user-friendly for your editors.