Skip to content
Watch a live product demo 👀 See how Sanity powers richer commerce experiences

Schema

The schema describes the types of documents editors may author in Sanity Studio.

The top level schema configuration accepts an object with two properties: templates and types. templates accepts an array of initial value template objects, or a callback function returning the same. types accepts an array of schema definition objects, or a callback function returning the same. In both cases, the callback function is called with the current value as the first argument and a context object as the second.

  • templatesarray | function

    An array of initial value templates, or a callback function that resolves to the same.

  • typesarray | function

    An array of schema definitions, or a callback function that resolves to the same.

The templates property is discussed in greater detail in this article and a reference article can be found here. The rest of this article will deal with the default set of schema types supported in the Sanity Studio.

A list of all schema types is available below or in the documentation menu.

Properties

  • REQUIREDtypestring

    Name of any valid schema type. This will be the type of the value in the data record.

  • REQUIREDnamestring

    Required. The field name. This will be the key in the data record.

  • titlestring

    Human readable label for the field.

  • hiddenboolean | function

    Takes a static or a callback function that resolves to a boolean value (truthy or falsy) and hides the given field based on it. You can use this property for conditional fields.

  • readOnlyboolean | function

    If set to true, this field will not be editable in the content studio. You can also return a callback function to use it as a conditional field.

  • descriptionstring

    Short description to editors how the field is to be used.

Note: The properties listed above are common for all data types. For a more thorough description of how to use them, have a look at the Object Type.

The studio loads all schemas defined under schema.types in studio.config.js.

//sanity.config.js
import {defineConfig} from 'sanity'

export default defineConfig({
  /* ... */
  schema: {
    types: [
      {
        title: "My Example Document Type",
        name: "exampleDocumentType",
        type: "document",
        fields: [
          {
            title: "Greeting",
            name: "greeting",
            type: "string"
          }
        ]
      }  
    ]
  }
})

To keep things organized, consider keeping the types array in a separate file and import it into studio.config.js. 

//schemaTypes.js
export const schemaTypes = [
  {
    title: "My Example Document Type",
    name: "exampleDocumentType",
    type: "document",
    fields: [
      {
        title: "Greeting",
        name: "greeting",
        type: "string"
      }
    ]
  }  
]

//sanity.config.js
import {defineConfig} from 'sanity'
import {schemaTypes} from './schemaTypes'

export default defineConfig({
  /* ... */
  schema: {
    types: schemaTypes
  }
})

You should also consider using the defineType, defineField and defineArrayMember helper functions when working with schemas. These will give you better IDE auto-suggestions and provide type-safety when used in TypeScript files. Using these functions is completely optional.

import {defineType, defineField, defineArrayMember} from 'sanity'

export const someDocumentType = defineType({
  title: "Some Document Type",
  name: "exampleDocumentType",
  type: "document",
  fields: [
    defineField({
      title: "String array",
      name: "strings",
      type: "array",
      of: [
        defineArrayMember({ type: "string" })  
      ]
    })
  ]
})

Plugins

Plugins may also provide types. They will be available in the studio exactly like studio configured types.

Using plugins to organize your code can be helpful as the studio codebase grows.

// pluginWithSchema.js
import {definePlugin, defineType, defineField} from 'sanity'

export const pluginWithSchema = definePlugin({
  name: 'plugin-with-schema',
  schema: {
    types: [
      defineType({
        title: "Plugin object",
        name: "exampleObject",
        type: "document",
        fields: [
          defineField({
            title: "Title",
            name: "title",
            type: "string"
          })
        ]
      })    
    ]
  }
})

//sanity.config.js
import {defineConfig} from 'sanity'
import {pluginWithSchema} from './pluginWithSchema'

export default defineConfig({
  /* ... */
  plugins: [pluginWithSchema()]
})

Updated on December 9, 2022

Was this article helpful?