Schema

A schema describes the types of documents and fields editors may author in a Sanity Studio workspace.

The top level schema configuration accepts an object with two properties: templates and types:

• The templates property accepts an array of Initial Value Template configuration objects or a callback function returning the same.
• The types property 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. Thus, you can access schema definitions and Initial Value Templates implemented by plugins.

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

All schema types are listed below or in the documentation menu.

• Requiredtype

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

• Requiredname

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

• title

  Human readable label for the field.

• hidden

  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.

• readOnly

  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.

• description

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

• deprecated

  Marks a document type or a field as deprecated. This will render the field(s) as read-only with a visual deprecation message defined by the reason property.

  If you deploy a GraphQL API schema, this property will translated into the @deprecated directive.

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 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()]
})