Studio

Document

Schema type reference for expressing documents.

Everything in Sanity Studio starts with the document. A document is what you create and edit in the studio; all the other types you define live inside documents. In the default studio configuration, document types are the ones listed in the document list of the Structure tool. See the DocumentDefinition reference for the full type definition.

Properties

  • Requiredname

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

  • Requiredtype

    Value must be set to document.

  • Requiredfields

    The fields of this object. At least one field is required. Documented here.

  • description

    Show a description to editors with context about the document type.

  • fieldsets

    A list of fieldsets that fields may belong to. Documented here.

  • groups

    Groups fields into tabs.

    On document: groups: [{name: 'seo', title: 'SEO'}],

    On field: group: 'seo',

    For details, see this reference doc.

  • initialValue

    The initial value used when creating new documents of this type. Can be a literal value, or a resolver function that returns a literal value or a promise that resolves to one.

  • liveEdit

    Turns off drafts when set to true. Changes to documents of this type are written straight to the published document and take effect immediately.

    Enable this before a type has content. If documents of this type already have drafts, the Studio makes those documents read-only rather than risk losing the draft edits, and they stay locked until the drafts are resolved.

  • orderings

    A declaration of possible ways to order documents of this type, documented here.

    Currently in beta.

  • preview

    Use this to implement an override for the default preview for this type. Documentation here.

  • title

    Human readable label for the document.

  • readOnly

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

  • components

    Lets you provide custom components to override the studio defaults in various contexts. The available keys are diff, field, input, item, and preview.

  • deprecated

    Marks a field or document type as deprecated in the studio interface and displays a user-defined message defined by the single required reason property.

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

  • __experimental_formPreviewTitle

    Set to false to hide the large document title heading in the document form pane. The heading is shown by default.

    Currently in alpha; the name may change.

  • icon

    Supply a custom icon for this field. See icons documentation for more information.

  • hidden

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

  • renderMembers

    Callback that customizes the members of the document form. It receives the resolved member array and returns a member array, which lets you add decoration members between fields instead of defining empty placeholder fields.

    Currently in beta and not part of the stable API.

  • validation

    Validation rules for the document as a whole, as a function receiving a DocumentRule builder. See Validation below.

  • options

    Options that apply to the type as a whole. DocumentOptions extends the base type options, which provide sanityCreate and canvasApp for controlling how the type appears in Sanity Create and Canvas.

Validation

The validation function receives a DocumentRule builder, which provides these methods:

  • required()

    Ensures that this field exists.

  • custom(fn)

    Creates a custom validation rule.

  • error(message)

    Sets a custom error message for the preceding validation rule.

  • warning(message)

    Sets a custom warning message for the preceding validation rule. Warnings do not prevent publishing.

  • info(message)

    Info messages are purely informational and do not prevent publishing.

  • valueOfField(path)

    Gets the value of a sibling field to use in validation. Useful for rules that depend on another field.

  • skip()

    Discards the validation rules set before it in the chain and makes the field optional. Rules chained after it still apply.

What a document is

At its core, a document is a JSON object that, in addition to the fields you define, has a unique _id, creation and update timestamps (_createdAt and _updatedAt), and a revision marker (_rev).

Timestamp truthiness

_createdAt and _updatedAt are automatically set by the system to the current time when the document is created or updated, respectively. It is possible to provide a custom value when the document is initially created via a create, createIfNotExists, or createOrReplace mutation. Since the timestamps can be set by a client, they should never be assumed to be accurate.

Only documents can be referenced from other documents or retrieved by id, and only document types are listed and creatable in the studio. Use type: 'object' for types you reuse on fields and never create standalone.

Apart from the above, documents are defined just like regular objects. See the Object type reference for how to define fields, fieldsets, and groups.

Input

import {defineField, defineType} from 'sanity'

export const movieType = defineType({
  title: 'Movie',
  name: 'movie',
  type: 'document',
  fields: [
    defineField({
      title: 'Title',
      name: 'title',
      type: 'string',
    }),
    defineField({
      title: 'Poster',
      name: 'poster',
      type: 'image',
    }),
    defineField({
      title: 'Directors',
      name: 'directors',
      type: 'array',
      of: [{type: 'string'}],
    }),
  ],
})

Response

{
  "_type": "movie",
  "_id": "2106a34f-315f-44bc-929b-bf8e9a3eba0d",
  "_createdAt": "2026-02-04T09:12:44Z",
  "_updatedAt": "2026-02-11T14:03:10Z",
  "_rev": "6xTqLmR2vNwPk9dYzB3aHc",
  "title": "Alien",
  "poster": {
    "_type": "image",
    "asset": {
      "_type": "reference",
      "_ref": "image-Tb9Ew8CXIwaY6R1kjMvI0uRR-2000x3000-jpg"
    }
  },
  "directors": ["Ridley Scott"]
}
Previous

Datetime

Next

File

Was this page helpful?