Get help on Discord

How to define schema for site settings in Sanity Studio

6 replies
Last updated: May 17, 2020
Hi everyone.I'm following the guide
https://www.sanity.io/guides/getting-started-with-structure-builder I've added Site settings and restarted/recompiled the studio.
import S from '@sanity/desk-tool/structure-builder';

export default () =>
    S.list()
        .title(`Content`)
        .items([
            S.listItem()
                .title(`Site settings`)
                .child(
                    S.editor()
                        .schemaType(`siteSettings`)
                        .documentId(`siteSettings`)
                ),
            // Add visual divider
            S.divider(),
            ...S.documentTypeListItems()
                    .filter( listItem => ![`siteSettings`].includes(listItem.getId() ))
        ])
However, when I click on the 'Site Settings' I get the following error:


Unknown schema type
This document has the schema type 
siteSettings
, which is not defined as a type in the local content studio schema.
Where do I define the schema for the deskStructure?
AI Update

The error you're seeing happens because you've created a Structure Builder configuration that references a siteSettings schema type, but you haven't actually defined that schema type in your Sanity Studio configuration yet. The Structure Builder is just organizing how documents appear in your Studio interface—it doesn't create the schema itself.

You need to define the siteSettings schema type separately in your sanity.config.js (or .ts) file. Here's how to fix this:

Step 1: Create your schema type

First, create a schema file for your site settings. In your schema folder (typically schemas/ or schemaTypes/), create a file like siteSettings.js:

export default {
  name: 'siteSettings',
  title: 'Site Settings',
  type: 'document',
  fields: [
    {
      name: 'title',
      title: 'Site Title',
      type: 'string'
    },
    {
      name: 'description',
      title: 'Site Description',
      type: 'text'
    }
    // Add whatever fields you need
  ]
}

Step 2: Register it in your sanity.config.js

Then, import and register this schema in your sanity.config.js:

import { defineConfig } from 'sanity'
import { structureTool } from 'sanity/structure' // Note: it's now structureTool, not desk-tool
import siteSettings from './schemas/siteSettings'

export default defineConfig({
  // your projectId and dataset
  projectId: 'your-project-id',
  dataset: 'production',
  
  plugins: [
    structureTool({
      structure: (S) =>
        S.list()
          .title('Content')
          .items([
            S.listItem()
              .title('Site Settings')
              .child(
                S.editor()
                  .schemaType('siteSettings')
                  .documentId('siteSettings')
              ),
            S.divider(),
            ...S.documentTypeListItems()
              .filter(listItem => !['siteSettings'].includes(listItem.getId()))
          ])
    })
  ],
  
  schema: {
    types: [siteSettings] // Register your schema here
  }
})

Important note: The guide you're following uses older syntax (@sanity/desk-tool/structure-builder). In modern Sanity Studio (v3+), this has been renamed to structureTool and the structure configuration is passed directly to the plugin.

Once you've added the schema type to your configuration and restarted your dev server, the "Unknown schema type" error should disappear, and you'll be able to edit your Site Settings document.

Hi Jan, have you defined the schema itself for 
siteSettings
? Depending on your folder structure, you might have a 
siteSettings.js
file in your 
/schemas/documents/
folder with the the appropriate contents. Once this file is in place, you will have to add it to your 
schema.js
file:
...
import siteSettings from './documents/siteSettings'
...
export default createSchema({
  types: schemaTypes.concat([
    ...
    siteSettings,
    ...
  ])
})
Full examples here:
•
https://github.com/sanity-io/sanity-template-gatsby-blog/blob/master/template/studio/schemas/documents/siteSettings.js •
https://github.com/sanity-io/sanity-template-gatsby-blog/blob/master/template/studio/schemas/schema.js
Hi Jan, have you defined the schema itself for 
siteSettings
? Depending on your folder structure, you might have a 
siteSettings.js
file in your 
/schemas/documents/
folder with the the appropriate contents. Once this file is in place, you will have to add it to your 
schema.js
file:
...
import siteSettings from './documents/siteSettings'
...
export default createSchema({
  types: schemaTypes.concat([
    ...
    siteSettings,
    ...
  ])
})
Full examples here:
•
https://github.com/sanity-io/sanity-template-gatsby-blog/blob/master/template/studio/schemas/documents/siteSettings.js •
https://github.com/sanity-io/sanity-template-gatsby-blog/blob/master/template/studio/schemas/schema.js
Hey, thanks for giving me hints. No, I didn't make the schema, but I wasn't quite sure, how to go about it. I shall read through the links you sent me. Cheers.
Yep, that did the trick! I sort of knew, I needed to define the schema, but I didn't work out how, where to add it, etc. Now it makes so much more sense and it seems obvious. One could even say… sane! (pun intended). Thank you.
Glad no sanity was lost in the process 😄 If you’re interested, there’s some more information on schemas in this guide for example: https://www.sanity.io/docs/content-modelling
Thanks, yes this mini series of short vids is really good. That's what actually got me started in the first place.

Sanity – Build the way you think, not the way your CMS thinks

Sanity is the developer-first content operating system that gives you complete control. Schema-as-code, GROQ queries, and real-time APIs mean no more workarounds or waiting for deployments. Free to start, scale as you grow.

Get started for freeExplore the demo

Was this answer helpful?