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.
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.
boolean | function
Takes a static or a callback function that resolves to a boolean value (
truthy
orfalsy
) 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 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()]
})