What does cake have to do with content operations? 🍰 👀 Find out in our Spring Release... →

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.

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.

  • deprecated{ reason: String }

    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

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 February 13, 2024

Was this article helpful?

Sanity