Creating schemas

Turn every binding from the previous step into a field, so editors know exactly what they can change and what's valid. A type that gets its own file is a document, a type that only lives inside another one is a fragment, and a document that only ever exists once is a singleton. See Schemas.

Do

Give every field a sensible default, so a new object is valid right away.
Keep the label short. Put guidance on how to fill a field in its description.
Give a document a title field when there are many of them. The editor uses it to name each one.
Reuse a generic schema (Link, Button) wherever the meaning is the same.
Name a type in PascalCase (LessonList), matching its component file name.
Group related values into a fragment or fragments field instead of flattening them onto the parent.
Extend a generic schema for a new use instead of renaming it to fit that one case.

Don't

Don't make near-copies of a schema with the same fields and the same meaning.
Don't add document: true or singleton: true to a type that only lives inside another one.
Don't name a type after an HTML tag, like section or nav.
Don't split text that reads as one piece over multiple fields.

FAQ

Which field type goes with a binding? Text is a string, an object like a link is a fragment, a list of sections is fragments, and other documents are a reference or references.

How does every page get the settings without picking them? A reference field left empty, and not nullable, fills itself at build time. A list does the same: an empty lessons field shows every lesson.

When do I hide a field? When editors have no reason to touch it: a value that shouldn't be configured (often also immutable), or a reference that always fills itself (empty and not nullable, like the settings).

When do I use one list field instead of separate fields? Use a list (fragments or references) when editors should be able to add, remove or reorder items, like the sections of a page. Use separate fields when each one has a fixed role.

How long should a description be? A simple, obvious field gets one short sentence. A complex schema (e.g. a page) can take a few sentences or a short list covering structure, tone, and pitfalls.

What if part of a title needs different styling? Use a richtext field and style the tags (b, i, u) inside it.

Example

# /schemas/Hero.yml
label: Hero
description: The large section at the top of a page, with its main actions.
fields:
  heading: { type: string, default: "Train like a ninja" }
  actions: { type: fragments, allow: [Link], default: [{ _type: Link, label: "See lessons", url: "/lessons" }] }