In this section · 2 articles

Create a content schema and add its fields

Create a Single or a Collection, add fields of any of the 16 types, decide what editors fill in and what the API sends, and preview the form and the JSON before anything is published.

Applies to
Headless CMS 1.0 and later
Who can do this
Administrator
Permission
feature.hcms.schema.create
Where
Headless CMS › Content schemas
On this page

Before you start

  • You need Create (feature.hcms.schema.create) and Edit (feature.hcms.schema.edit) on content schemas. The CMS Administrator role has both.
  • Until an entry is first published, everything about a schema can change, including its key and type. After that its shape is locked. Plan the fields, and test with a draft before you publish. See How schema changes and versions keep applications working.

Steps

1. Create the schema

  1. Open Headless CMS › Content schemas.

  2. Select Create schema. On an empty list you can also choose a common one, such as Site header, Hero banners, Services, Testimonials, FAQs or Navigation menu, which fills in the name and type for you.

    The Create content schema drawer with Label set to Press releases, Key following it as press_releases, Type set to Collection, and API delivery and web address (slug) both on.
  3. In Label, type what editors will see in menus and forms, for example FAQs. You can change it at any time.

  4. Under Type, choose:

    • Single: one record per content space. Editors open it and edit it, and never add a second. For example: Site header, Contact information, Footer settings.
    • Collection: a list of records. Editors add, order, publish and remove them one by one. For example: Client logos, FAQs, Services, Testimonials.
  5. Check Key. It follows the label, for example faqs, and applications use it in the address. Use lowercase letters, numbers and underscores, starting with a letter, 2 to 64 characters. search, meta, schemas, preview and health are reserved.

  6. Optional: fill in Internal name, a name for your build team that editors don't see, and Description.

  7. For a Collection, choose whether to Give entries a web address (slug), so an application can open one entry directly at …/faqs/opening-hours. You choose which field the address is made from after adding fields.

  8. Leave Delivery through the API on. When it's off, nobody receives this schema's content, even where it's assigned and published.

  9. Select Create and add fields.

The schema is created as Active and its page opens on the Fields tab.

2. Add fields

  1. On an empty schema, select Add these 3 fields to start with Title, Description and Image, or select Add field.

  2. Choose a type. Type in Search field types to find one, for example "price" or "date". Then select Next: settings.

    The Add a field to FAQs drawer with date typed in Search field types, showing the Date and Date-time field types, and the Next: settings button highlighted.
  3. On Basics:

    • Label: what editors see. Key follows it, and is the name the API sends the value under.
    • Help text and Placeholder: guidance in the form.
    • Required: checked when a language is published, not when a draft is saved.
    • Translatable: each language has its own value. Off: one value shared by every language. Numbers, Boolean, dates and Reference are always shared.
    • Appears in: tick Editors' form, The API, or both. A field only on the form is hidden from the API, for example an internal note.
  4. On Validation, set the rules, such as Shortest and Longest, a Format such as Phone number, or Lowest and Highest for numbers. Size limits default to Headless CMS settings and can't go above their fixed ceilings.

  5. For Select and Multi-select, add the options on Choices: each has a Value, which applications match on and never changes, and a Label per language.

  6. On API, choose the API format, for example HTML or Blocks for rich text.

  7. Select Add field, or Add and add another.

    The Add a field to FAQs drawer on its Basics tab, with the label Short summary, the key short_summary, and both Editors' form and The API ticked under Appears in.

3. Order the fields and name the entries

  • Use Move up and Move down to order the fields. The form and the API follow this order.
  • Entry title from picks the field that names each entry in lists. Web address from picks the field the address is made from. Both default to the first Text field, and only an active Text field can be chosen.
The FAQs schema's Fields tab with its four fields in order, Entry title from and Web address from set to Question, and the Answer row's menu open with Move up highlighted above Move down.

4. Check the form and the JSON

The schema page shows three panes:

  • Form preview: what editors see. Select Preview form to try every control, and Fill with an example. Nothing is saved, and uploads are discarded.
  • API shape: the JSON an application will receive.
  • Example: a real published entry, once a space has one. Select Open in API explorer to run the request.
The FAQs schema page with the Form preview pane beside the API shape pane and its Shape and Example toggle, and the Preview form button highlighted next to Add field.

Field types

TypeForAPI format
TextA short line: a name, a heading, a phone number.Text
TextareaSeveral lines of plain text.Text
Rich textFormatted text with headings, lists and links. Choose Allowed features.HTML (cleaned, ready to place in a page) or Blocks (the structured document)
EmailAn email address, checked as one.Text
URLA web address, checked for safety.Text
IntegerA whole number: a count, a year, a rank.Number or Text
DecimalA number with fixed decimal places: a price, a rating.Number or Text
BooleanA switch: on or off.True / false
SelectOne choice from a list you define.Value, or Value and label
Multi-selectSeveral choices from a list you define.Values, or Values and labels
DateA calendar date, without a time.Date (YYYY-MM-DD)
Date-timeA moment in time, stored in UTC.Date-time (ISO 8601, UTC) or Timestamp
ImageA picture, with alt text and size limits.Image object (address, alt text and size) or Address only
FileA document to download: PDF, spreadsheet and the like.File object or Address only
JSONStructured data, sent as it's stored.JSON
ReferenceA link to an entry of another schema, in the same space.Entry (expanded with ?include=) or Id only

Use as a filter in the content list is offered for Select, Multi-select, Boolean, Date and Integer, so editors can filter the list by that field. SVG images are off for safety.

Manage a schema

From the schema's row or page:

  • Edit: change the label, internal name, description, position in lists and the API switch. The key and type are fixed once the shape is locked.
  • Copy as new schema: copies the fields with their rules and API format, the description, the web address setting and the API switch. Content, assignments and versions aren't copied. Use it when you need a different type or a fresh start.
  • Delivery through the API off: stops this schema's content reaching anyone, in every space, while editors keep working. It asks first and offers Undo.
  • Deactivate: stops delivery everywhere and makes the content read-only. Nothing is deleted, and Activate brings back the same addresses and content.
  • Move to trash: only once the schema is removed from every space in Assignments, and no other schema's Reference field points at it.
  • Export definitions and Import definitions: move schemas between installations as a .json file. The file holds definitions only, never content. The import shows a preview and lets you choose, for each schema, to create it, replace it, import it under a new key, or skip it. Export needs feature.hcms.schema.export, and import feature.hcms.schema.import.

A schema's key, and each field's key, are reserved for good, even after it's removed, so an application never receives different content at the same address.

What happens next

Assign the schema to a content space so editors can fill it in. See Set up a content space and deliver your first content. Once an entry is published, changes follow the version rules in How schema changes and versions keep applications working.