How a Sanity schema works
Schemas are registered in the Studio's root config, usually sanity.config.ts. The schema config object takes two properties: types (schema definitions) and templates (initial value templates). schema.types can be an array or a callback, which lets a project read and extend schema types added by plugins. The defineType and defineField helpers check the schema configuration and provide autocomplete for options.
Document types are standalone content collections, comparable to tables in a SQL database. A document type should not be reused as a field type; use a reference or an object instead.
The block type, placed inside an array, gives a field rich text stored as Portable Text.
Custom field types. Sanity recommends defining reusable custom field types in their own files and registering them in
schema.types.
Read more in Sanity's introduction to schemas.
Validation, deployment and change
Validation. Validation rules run only in Sanity Studio; writes through the API or client libraries are not checked against them. Failed validation errors block publishing, while rules marked warning() do not.
Deployment. Deploying a schema stores it in the dataset as system.schema documents, one per workspace. The sanity schemas commands need sanity version 3.88.0 or later. A deploy token is enough to deploy a schema from CI, with no write token needed.
Change. When a schema changes, migration tooling can transform existing content to the new structure. To move content in from another CMS, see the guides to migrating from Contentful to Sanity and WordPress to Sanity migration.
The Media Library also uses schemas, called aspects, to define metadata fields for assets.
Schema patterns Pagepro uses
On multi-brand Sanity development projects, Pagepro keeps feature flags in the schema as fields, so one code path serves every variant. Optional fields hide when empty, which lets editors control visibility without toggles. A brand-level list replaces the global list instead of merging with it.
Sources
- Introduction to schemasSanity · sanity.io
- Schemas and formsSanity · sanity.io
- Schema (schema types reference)Sanity · sanity.io
- ValidationSanity · sanity.io
- Schema deploymentSanity · sanity.io