Field Models are defined inside of Content Models - They define individual fields.

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

A field model is an array of objects defining the names, types, labels, descriptions, etc. of the content models fields. Fields can have different types (string, boolean, list, object, name of an object model, and etc.), can be required or optional, hidden, can have default values and etc.

Field Model Schema

Field NameOptionsDefaultDescriptionNotes
typerequiredName of any valid type (e.g.: string, text, number, list, object, reference, a name of another object model, etc.)
namerequiredThe field key as it should appear in the contentShould 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.
labelrequiredHuman readable label for the fieldShould be short enough as some CMS's have restrictions on its length
descriptionoptionalShort description to editors how the field is to be used
requiredoptionalfalseDefines if the field should be required
defaultoptionalThe 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's this is only a UI editor feature, meaning that the default value will be set only if it is not hidden. Therefore this field must not be used for required values, use const field for that.
constoptionalThe constant value that should be set when the object is created.If this type of field is not supported by CMS's, its behavior could be 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 that value.
hiddenoptionalfalseDefines if the field should be hidden from the editor.When hiding fields, CMS's might not set the field's default value. In such case, hidden should be used only with data created outside of CMS UI (e.g.: API). For example, config data that is imported into CMS when the site is created.
readOnlyoptionalfalseDefines 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's not supporting this property, a combination of hidden + required can achieve the same effect.
uniqueoptionalfalseDefines if the field value should be uniqueNot in use yet.
Not supported in many CMS's. Unique between same model type, or across all models?
widgetoptionalDefines the UI of field control (textfield, textarea, select, checkbox, etc.)not in use yet
validationsoptionalTo be definednot in use yet.
Currently field validations are based on their types, the required field and enum options.

Field Model Types

TypeDescriptionType Specific Properties
stringShort plain text
textPlain text
markdownRich text that should be run through markdownify filter.
enumA value from a list of predefined valuessource - object defining source for values.
source.type - type of source. Currently only options is supported, and it is the default
options - list of values, or objects with label and value properties
numbersubtype - int (default) or float.
min - min allowed value.
max - max allowed value.
step - jump steps.
booleanA boolean true or false
imagePath to image file. When content is imported into CMS, images will be uploaded first, then, this value will be replaced with CMS specific value such as a returned asset ID or an object referencing the uploaded image.
filePath to any file. Like with the image property, this value will be replaced with CMS specific value when content is imported into CMS.
datetimewith date and time formatting optionsformat - format of the date and time, TBD
datewith date formatting optionsformat - format of the data, TBD
colorformat - format of the color: rgb or hex.
referenceA 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
objectA 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, reference 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
<model_name>Any other model of type object. This is similar to defining reference type field referencing a single motel type. But unlike reference type, the data of this field does not require to have type property.
listList of valuesitems - object defining types and options of array items.
items.type - type of the field (default is string).
items.* - other fields related to the specific type, for example for object type these could be labelField and fields, and for reference type these could be models.
blocksTo be defined. A.K.A: rich-text (contentful), snippets (forestry), slices (prismic), block (sanity)

Examples

Reference

stackbit.yaml:

models:
  action_block:
    type: object
    label: Action Block
    description: A block with title and action
    fields:
      - type: string
        name: title
        label: Title
      - type: reference
        name: action
        models: [action_button, action_image]
  action_button:
    type: object
    label: Action Button
    fields:
      - type: string
        name: label
        label: Button Label
  action_image:
    type: object
    label: Action Image
    fields:
      - type: image
        name: image
        label: Action Image Asset

A data represented by action_block model with action_button:

actionBlock:
  title: "Find out more"
  action:
    type: "action_button"
    label: "click here"

A data represented by action_block model with action_image:

actionBlock:
  title: "Find out more"
  action:
    type: "action_image"
    image: "/assets/images/find_more.png"

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.