Headless CMS Sanity Data Modeling - Defining the Structure of Document Content

Define the structure of the content.

Using code to define the content model is by design. It makes version control easier and enables developers to control how data structures are laid out. We made it effortless to add, change, and delete fields in the interface.

Watch a video on how Schema works , or scroll to read how it works.

your first schema

When Sanity starts, by default it looks for schema.js in the project schemas folder. Let's start by building a simple schema:

 // 首先，必须引入 schema-creator
import createSchema from "part:@sanity/base/schema-creator";

// 然后引入插件可能暴露的 Schema 类型expose them
import schemaTypes from "all:part:@sanity/base/schema-type";

// 接着创建 Schema
export default createSchema({
  // 名称
  name: "mySchema",

  // 连接文档类型，目前只需要一个
  types: schemaTypes.concat([
    {
      // 类型显示名称
      title: "Person",

      //API 标识符
      name: "person",

      // 文档类型为 `document `
      type: "document",

      // 字段声明
      fields: [
        // 该文档类型仅有一个字段
        {
          // 显示名称
          title: "Name",

          // API 标识符
          name: "name",

          // 字段类型
          type: "string",
        },
      ],
    },
  ]),
});

This schema configuration creates a document type of person 68156b28ede456bcae2255ac0d288fdb--- which contains a name field.

When fetching such a document via the API later, we get a document like this:

 {
  "_id": "45681087-46e7-42e7-80a4-65b776e19f91",
  "_type": "person",
  "name": "Ken Kesey"
}

One document references another

Now let's design a simple document describing a book. In the typed array, we add an object like this:

 {
  title: 'Book',
  name: 'book',
  type: 'document',
  fields: [
    {
      title: 'Title',
      name: 'title',
      type: 'string'
    },

    {
      title: 'Cover',
      name: 'cover',
      type: 'image'
    },

    {
      title: 'Author',
      name: 'author',
      // `reference` 类型来指向另一个文档
      type: 'reference',
      // 这个引用只允许指向 `person` 类型的文档
      // 虽然可以列举更多类型，但尽量保持精简:
      to: [{type: 'person'}]
    }
  ]
}

This schema creates a document type called book which contains three fields:

• title
• cover image
• Author (This field refers to another document, the type of document being referenced is described in the to field. A rule is listed that the type can be person )

The form looks like this:

When fetching this document via the API, we get:

 {
  _id: "d1760c53-428c-4324-9297-ac8313276c45",
  _type: "book",
  title: "One Flew Over the Cuckoos Nest",
  cover: {
    _type: "image",
    asset: {
      _ref: "image-Su3NWQ712Yg0ACas3JN9VpcS-322x450-jpg",
      _type: "reference"
    }
  },
  author: {
    _ref: "45681087-46e7-42e7-80a4-65b776e19f91",
    _type: "reference"
  }
}

As you can see, the author field does not mention Ken Kesey, but the field _ref contains the id of the Ken Kesey document. When fetching the referenced document, you can easily experience the actual content of the target document by instructing the API. You can read more about it in the Query tutorial .

A use of arrays

Let's talk about arrays: some books have more than one author. We should improve the Book document type by setting the author field to an array of references:

 {
  title: 'Authors',
  name: 'authors',
  type: 'array',
  of: [{
    type: 'reference',
    to: [{type: 'person'}]
  }]
}

The document returned from the API will look like this:

 {
  _id: "drafts.e7f370d0-f86f-4a09-96ea-12f1d9b236c4",
  _type: "book",
  title: "The Illuminatus! Trilogy",
  cover: {
    _type: "image",
    asset: {
      _ref: "image-Ov3HwbkOYkNrM2yabmBr2M8T-318x473-jpg",
      _type: "reference"
    }
  },
  authors: [
    {
      _ref: "9a8eb52c-bf37-4d6e-9321-8c4674673198",
      _type: "reference"
    },
    {
      _ref: "ee58f2ff-33ed-4273-8031-b74b5664ff5e",
      _type: "reference"
    }
  ]
}

Organization

A final note is to organize your file(s). In this example, we have stacked the definitions of both types of documents into the same JS file. This is not recommended; it can quickly get the code out of control. The recommended practice is to describe each document type in a separate file:

 // 文件： schemas/schema.js
import createSchema from 'part:@sanity/base/schema-creator'
import schemaTypes from 'all:part:@sanity/base/schema-type'
import person from './person'

export default createSchema({
  name: 'mySchema',
  types: schemaTypes.concat([
    person
  ])
})



// 文件： schemas/person.js
export default {
  title: "Person",
  name: "person",
  type: "document",
  fields: [
    {
      title: "Name",
      name: "name",
      type: "string",
    }
  ]
}

This covers the very basics, but there is so much more! Now, let's dive into best practices when modeling content with Sanity.