Sublime schemas

The defineType and defineField helper functions should always be used when creating schema types. Functionally, they're optional. However, they provide autocomplete suggestions thanks to TypeScript and may unlock future functionality.

Defining fields in a schema type only requires two keys: name and type:

defineField({ name: 'name', type: 'string' }),
defineField({ name: 'url', type: 'url' }),
defineField({ name: 'linkedin', type: 'url' })

When omitted, the title value for these fields will be automatically generated. However, it will not account for special casing like acronyms or "PascalCase" brand names.

• name becomes Name, which is fine
• url becomes Url, when it should be URL
• linkedin becomes Linkedin, when it should be LinkedIn

defineField({ name: 'name', type: 'string' }),
defineField({ name: 'url', title: 'URL', type: 'seo' }),
defineField({ name: 'linkedin', title: 'LinkedIn', type: 'url' })

Another useful key for a schema field is its description. Adding a little context to why this field is required can help authors understand the content’s intention.

defineField({ 
  name: 'url',
  title: 'URL',
  description: 'Canonical URL for the Googlebot crawler to index this content',
  type: 'url' 
})

If you need to add basic formatting to your descriptions, this key will accept JSX! Note: You will need to update your schema type's file to use a .jsx or .tsx file extension for this to work.

description: (
  <details>
    <summary>Why is this important?</summary>
    The Googlebot is an indexer of...
  </details>
)

This example code creates a collapsible <details> element to hide away longer-form descriptions.

Open to enlarge image

The simplest way to mark a field as invalid and block the publishing of the document is shown in the example below, implementing the required rule.

defineField({
  name: 'slug',
  type: 'slug',
  validation: rule => rule.required()
})

However, the error message in the Studio will only say "Required" and not give the author any additional information.

Open to enlarge image

Adding the error method will give extra context to the author about why it has been marked invalid and what must be done to resolve it.

defineField({
  name: 'slug',
  type: 'slug',
  validation: rule => 
    rule
      .required()
      .error(`Required to generate a page on the website`)
})

Open to enlarge image

This appears not only on the invalid field but also in the summary of validation errors in the document inspector.

Open to enlarge image

Validation warnings are useful to inform the author that while the document can be published in its current form – it falls short of a desired editorial standard.

defineField({
  name: 'summary',
  type: 'string',
  validation: rule => 
    rule
      .min(100)
      .max(200)
      .warning('For consistency, this summary should be between 100-200 characters')
})

One more validation level is an info popup. This is useful for general information about a field, especially when the text is too long to place in the description field key.

Note, this currently will only display if required is also used.

defineField({
  name: 'definition',
  type: 'string',
  validation: rule => 
    rule.required().info('This field is important for...')
})

The order of your fields in a schema is important. Good form design usually includes putting the "simplest" fields higher. Followed by, in descending order, less important or more complicated fields.

You might even use the hidden attribute to hide these more complex fields entirely until the simpler fields have values.

The schema of a document can use a fieldsets key to visually arrange fields together, without effecting how they are nested in the data.

A configuration like this:

export default defineType({
  name: 'article',
  title: 'Article',
  type: 'document',
  fieldsets: [
    {name: 'dates', title: 'Dates', options: {columns: 2}},
  ],
  fields: [
    defineField({name: 'publishedAt', type: 'datetime', fieldset: 'dates'}),
    defineField({name: 'updatedAt', type: 'datetime', fieldset: 'dates'}),
    // ...and the rest

Will render these two fields side-by-side at the root of the document.

object schema types can use the same options for fields in the object.

Once grouped, a fieldset can be collapsible – and collapsed by default – to tidy up the appearance. It can also declare columns so that fields are rendered side-by-side.

Open to enlarge image