Field Models are nested inside of Content Models - They define individual fields. They map the frontmatter of a markdown document and JSON/TOML/YAML data.

A field model describes the name and the type of a field, as well as its presentation and behaviour inside a CMS UI editor.

Basic Example

Take the following markdown document with 3 front matter fields.

# content/posts/my-post.md 
---
date = "2014-09-28"
title = Creating a New Theme
banner_image = images/cat.png
---

This is a post about cats.

In the stackbit.yaml we add corresponding field models.

# stackbit.yaml
...
models:
  posts: # this is a page model
    type: page
    label: Blog Posts
        folder: posts
    fields: #these are the field models
      - type: string # field model of type: string
        name: title # name maps to the field in the front matter
        label: Title
                required: true
            - type: date # a field model of type: date
                name: date 
                label: Publish Date
            - type: image # field model of type: image
                name: banner_image
                label: Main blog post image

Field Model Schema

Field NameDescriptionNotes
typeRequired
Name of any valid field type (e.g.: string, text, number, list, object)
See available field types in the Field Types table below.
nameRequired
The field key as it should appear in the content
Should contain only alphanumeric characters, underscore and a hyphen [A-Za-z0-9_]. Must start with a letter. Must not end with an underscore or a hyphen.
labelRequired
Human readable label for the field
Should be short enough as some CMS's have restrictions on its length
descriptionShort description to editors how the field is to be used
requiredDefault: false
Indicate if the field should be required
defaultThe default value for this field that will be placed inside the UI editor.This is not a fallback value that will be used if the field is not set or empty. In some CMS this is merely a UI editor feature, meaning that the default value will be set only if it is not hidden. Therefore, this field should not be used for required and hidden fields, use const field for that.
constThe constant value that should be set when the object is created.If this type of field is not supported by specific CMS, its behavior is achieved by using default + required + readOnly, or default + required + accept_only=<default>, or any other combination that will set the const value when an object with this field is created and prevent the user from changing its value.
hiddenDefault: false
Indicates if the field should be hidden from the editor.
When hiding fields, some CMS might not set field default value. Therefore, hidden should be used only with const or when the data is created outside of CMS UI (e.g.: API). For example, config data that is imported into CMS when the site is created.
readOnlyDefault: false
Indicates if the field should be readonly. This property could be used if a field value is not a constant and created outside of CMS UI (e.g.: imported via API).
For CMS not supporting this property, a combination of hidden + required can achieve the same effect.
uniqueDefault: false
Indicates if the field value should be unique
Not in use yet.
Not supported in many CMS.
widgetDefines the UI of field control (textfield, textarea, select, checkbox, etc.)Not in use yet
validationsTo be definedNot in use yet.
Currently field validations are based on their types, the required field and enum options.

Field Types

String Field

Short single-line plain text

fields:
  - type: string
    name: title
    label: Title

Text Field

Multi-line plain text field

fields:
  - type: text
    name: description
    label: A short description of the article

Markdown Field

Rich text that should be run through markdownify filter.

fields:
  - type: markdown
    name: description
    label: A short description of the article

Number Field

subtype - int (default) or float.
min - min allowed value.
max - max allowed value.
step - jump steps.

fields:
  - type: number
    name: age
    label: The employees age

Boolean Field

A boolean true or false

fields:
  - type: boolean
    name: draft
    label: Is this article a draft?

Image Field

Path to image file.

fields:
  - type: image
    name: thumbnail
    label: The thumbnail image for this blog post

File Field

Path to any file.

fields:
  - type: file
    name: whitepaper
    label: A Link to the whitepaper PDF file

Date Field

with date formatting options

fields:
  - type: date
    name: date
    label: Publish Date
---
title: "My Blog Post"
date: 2017-03-09T14:25:52-05:00

Color Field

Color value in Hex format (e.g.: #FF0000)

# stackbit.yaml
...
models:
    theme:
    type: data
    label: Theme Config
    file: theme.json
        fields:
          - type: color
            name: primary_color
            label: Primary Theme Color
            - type: color
            name: link_color
            label: Link Color
# theme.json
{
  "primary_color": #FFCC00,
    "link_color: #3eb2fd
}

Object Field

A nested object. Some CMS's support only flat models. For these CMS's any nested objects will be transformed into a standalone model. Therefore, this type of field should be used only if the nested object is not repeated in another field. Otherwise, <model_name> type should be used to minimize number of created models.

labelField - the name of a field that will be used as title when this object is embedded inside a list or in another object.
fields - list of model fields of the nested object

# stackbit.yaml
...
models:
  config:
    type: data
    label: Config
    file: config.toml
    fields:
            - type: object
        name: params
        label: Params
        description: Site parameters
        fields:
          - type: string
            name: google_analytics_id
            label: Google Analytics ID
          - type: string
            name: google_tag_manager_id
            label: Google Tag Manager ID
          - type: object
            name: logo
            label: Params Logo
            fields:
              - type: image
                name: logo
                label: Logo Image
              - type: string
                name: alt
                label: Logo Alt Text
# config.toml
...
[params]
  google_analytics_id = ""
  google_tag_manager_id = ""
  [params.logo]
    logo = "images/logo.svg"
    alt = "My Logo"

Reference Field Type

A reference to a model of any of the types specified inside models property. Only models of type object can be referenced. The data of this field required to have type property identifying its model.

models - list of models that can be set for this field.
See Reference Field Type for more info.

# stackbit.yaml
...
models:
  home:
    type: page
    label: Home
    layout: home
    singleInstance: true
    file: index.md
            fields:
      ...
          - type: reference
            name: section
            label: Section
            models: [intro, banner]
  intro:
    type: object
    label: Intro Section
    fields:
      - type: markdown
        name: intro_text
        label: Intro Text
  banner:
    type: object
    label: Banner Section
    fields:
      - type: image
        name: banner_img
        label: Banner Image

index.md

---
layout: home
title: Home
section:
  type: intro
  intro_text: "Welcome *Home*!"
---

In the example above, the home section field is a referenced object defined by intro or banner models. Each of these objects must have type field to identify the object's model. The type field could be also used to create conditions in templates as given in the following example for a home.html layout file written in Nunjucks:

<h1>{{ page.title }}</h1>

{% if page.section.type == "intro" %}
    {{ page.section.intro_text | markdownify }}
{% elif page.section.type == "banner %}
    <img src="{{ page.section.banner_img | relative_url }}"/>
{% endif %}

The reference type can be also used in lists:

stackbit.yaml

models:
  home:
    type: page
    label: Home
    layout: home
    singleInstance: true
    file: index.md
        fields:
      ...
      - type: list
        name: sections
        label: Sections
        items:
          type: reference
          models: [intro, banner]

index.md

---
layout: home
title: Home
sections:
  - type: intro
      intro_text: "Welcome *Home*!"
  - type: banner
    banner_img: "welcome_banner.png"
---

Enum Field Type

Enum field type requires specifying an options field with list of allowed values. This list can be represented in two ways:

  1. List of strings, each string is one of the allowed values.
  2. List of objects with label and value fields. The value specifies the allowed value and the label specifies the label that will be presented to the user, if the underlying CMS supports that.
fields:
  # enum with list of values
    - type: enum
      name: tag
        label: Tag
        options: [foo, bar, baz]
  # enum with list of objects
    - type: enum
        name: element
        label: Element
        options:
            - label: "Foo!"
        value: foo
            - label: My Bar
        value: bar
            - label: bazzz
        value: baz

List Field Type

The example below defines a simple list of strings

fields:
  - type: string
    name: title
    label: Title
  - type: list
    name: tags
    label: Tags
    items:
      type: string

The data represented by such list might look like this:

---
title: JavaScript
tags:
  - code
  - javascript
  - node
---

More advanced list with nested objects can be defined in the following way

fields:
  - type: string
    name: title
    label: Title
  - type: list
    name: button
    label: Buttons
    items:
      type: object
      labelField: label  # labelField specifies which field value to use as the list item label
      fields:
        - type: string
          name: url
          label: Button URL
        - type: string
          name: label
          label: Button Label

The data represented by such list might look like this:

---
title: JavaScript
buttons:
  - label: Example Site
    url: https://www.example.com
  - label: Stackbit
    url: https://www.stackbit.com
---

When using nested structures, it is recommended to reuse models to allow model reusability.

Taking the previous example, the button object can be defined as a separate model and used as a list item type while preserving the structure of the represented data:

models:
  model_a:
    ...
        fields:
          - type: string
            name: title
            label: Title
          - type: list
            name: button
            label: Buttons
            items:
              type: button
  button:
    type: object
    label: Button
    labelField: label
    fields:
      - type: string
        name: url
        label: Button URL
      - type: string
        name: label
        label: Button Label

This kind of architecture allow reusing the button model in other models and reduces amount of models created in API based CMS.

Field Model Naming Convention

  • can only contain alphanumeric and a hyphen - and an underscore _
  • must start with a letter
  • must not start or end with hyphen - or underscore _

Special Field Models

Reference Type - a special type of field that defines which Object Models might be referenced by that field. Reference type can only reference "Object Models". A reference field can be used as an item type of a list field. Thus allowing to define list of objects of multiple types. The data of the referenced objects must include the type field with value of the referenced model name. Copy of field types