Get help on Discord

Where to define schema for deskStructure siteSettings document type?

6 replies
Last updated: Nov 29, 2025
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.

Show original thread
6 replies

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?