Field — Content Management API

DatoCMS offers a number of different fields that you can combine together to create a Model. Using the database metaphore, fields are like table columns, and when creating them you need to specify their type (string, float, etc.) and any required validation.

Different field types require different settings

When looking at a field resource, you have to pay attention to two particular properties, validators and appearance.

The validators property expresses the set of validations to be performed server-side on a specific field value for it to be considered valid, while the appearance property lets you specify how the field itself will be presented inside the form to the final editor.

For both properties, the value to specify depends on the type of field itself. For example, you can add a "Limit character count" validation to a Single-line string field, or set its appearence to "Show it as heading", but they won't be accepted for a ie. Color field, as it supports different validations and appearance settings.

Specifying validations

The validators property requires an object whose keys are the validations that you want to be enforced, and the values are objects representing any settings that the validation itself requires. If the validation doesn't have additional settings, you just pass down an empty object.

This is a valid example for a Single-line string field:

{
  "validators": {
    // "required" validator has no settings
    "required": {},
    // "length" validator requires "min" and/or "max" properties
    "length": { "min": 80 }
  }
}

Below you'll find a summary of all the validators available for each field type with their settings.

Some validators are required for a specific type of field. For example, the Modular Content field needs to have a rich_text_blocks validator, specifying which types of blocks it can contain.

Specifying the appearance

The appearance property requires an object with three specific properties: editor, parameters and addons.

The editor represents the type of editor that the users will see inside the form to change the value of this specific field. Depending on the type of field, DatoCMS offers a number of different editors for you to choose from. The parameters property is an object representing any additional settings that the editor itself might require.

This is a valid example for a Single-line string field:

{
  "appearance": {
    // single_line is a DatoCMS built-in editor that you can use with single-line string fields
    "editor": "single_line",
    // each built-in editor has specific settings
    "parameters": { "heading": true, "placeholder": "My blog post title" },
    "addons": []
  },
}

Following you'll find a summary of all the editors available for each field type with their settings.

Setting the appearance to a field editor provided by a plugin

If the project contains a plugin that exposes manual field editors, you can also configure the field to be presented with it instead of using one of the built-in editors.

In this case:

the editor property is the plugin's project-specific autogenerated UUID. You can get it from the last part of the plugin's URL within your project's Configuration screen (e.g. https://your-project.admin.datocms.com/configuration/plugins/PLUGIN_UUID/), or via API with a List all plugins call.
the field_extension property must be the ID of the specific manual field editor that the plugin exposes. This is set in the plugin's own source code, within a manualFieldExtension() call in its entry point (usually something like index.tsx).
the parameters property must provide a configuration object compatible with the config screen of the manual field extension, or an empty object if it doesn't require any configuration.

{
  "appearance": {
    // "2132" is a the ID of a plugin exposing a manual field editor
    "editor": "2134",
    // "starRating" is a manual field editor exposed by the plugin
    "field_extension": "starRating",
    // this is a valid configuration for the "starRating" field editor
    "parameters": { "maxRating": 5, "starsColor": "#ff0000" },
    "addons": []
  },
}

Configuring manual field addons

If the project contains plugins that expose manual field addons, you can also add them to the field via the addons property.

{
  "appearance": {
    "editor": "single_line",
    "parameters": { "heading": true, "placeholder": "My blog post title" },
    "addons": [
      {
        // "2138" is a the ID of a plugin exposing a manual addon editor
        "id": "2138",
        // "loremIpsumGenerator" is a manual field addon exposed by the plugin
        "field_extension": "loremIpsumGenerator",
        // this is a valid configuration for the "loremIpsumGenerator" field addon
        "parameters": { "sentences": 2 },
      }
    ]
  },
}

Available field types

Single-line string (string)

Property	Value
Code	`string`
Built-in editors for the field	`single_line`, `string_radio_group`, `string_select`
Available validators	`required`, `unique`, `length`, `format`, `enum`

Multi-line text (text)

Property	Value
Code	`text`
Built-in editors for the field	`markdown`, `wysiwyg`, `textarea`
Available validators	`required`, `length`, `format`

Boolean (boolean)

Property	Value
Code	`boolean`
Built-in editors for the field	`boolean`, `boolean_radio_group`
Available validators	no validators available

Integer (integer)

Property	Value
Code	`integer`
Built-in editors for the field	`integer`
Available validators	`required`, `number_range`

Float (float)

Property	Value
Code	`float`
Built-in editors for the field	`float`
Available validators	`required`, `number_range`

Date (date)

Property	Value
Code	`date`
Built-in editors for the field	`date_picker`
Available validators	`required`, `date_range`

Date time (date_time)

Property	Value
Code	`date_time`
Built-in editors for the field	`date_time_picker`
Available validators	`required`, `date_time_range`

Color (color)

Property	Value
Code	`color`
Built-in editors for the field	`color_picker`
Available validators	`required`

JSON (json)

Property	Value
Code	`json`
Built-in editors for the field	`json`, `string_multi_select`, `string_checkbox_group`
Available validators	`required`

Location (lat_lon)

Property	Value
Code	`lat_lon`
Built-in editors for the field	`map`
Available validators	`required`

SEO and Social (seo)

Property	Value
Code	`seo`
Built-in editors for the field	`seo`
Available validators	`required_seo_fields`, `file_size`, `image_dimensions`, `image_aspect_ratio`, `title_length`, `description_length`

Slug (slug)

Property	Value
Code	`slug`
Built-in editors for the field	`slug`
Available validators	`required`, `length`, `slug_format`, `slug_title_field`

External video (video)

Property	Value
Code	`video`
Built-in editors for the field	`video`
Available validators	`required`

Single-asset (file)

Property	Value
Code	`file`
Built-in editors for the field	`file`
Available validators	`required`, `file_size`, `image_dimensions`, `image_aspect_ratio`, `extension`, `required_alt_title`

Asset gallery (gallery)

Property	Value
Code	`gallery`
Built-in editors for the field	`gallery`
Available validators	`size`, `file_size`, `image_dimensions`, `image_aspect_ratio`, `extension`, `required_alt_title`

Single link (link)

Property	Value
Code	`link`
Built-in editors for the field	`link_select`, `link_embed`
Default `editor`	`link_select`
Required validators	`item_item_type`
Other validators available	`required`, `unique`

Multiple links (links)

Property	Value
Code	`links`
Built-in editors for the field	`links_select`, `links_embed`
Default `editor`	`links_select`
Required validators	`items_item_type`
Other validators available	`size`

Modular content (rich_text)

Property	Value
Code	`rich_text`
Built-in editors for the field	`rich_text`
Required validators	`rich_text_blocks`
Other validators available	`size`

Single Block (single_block)

Property	Value
Code	`single_block`
Built-in editors for the field	`framed_single_block`, `frameless_single_block`
Required validators	`single_block_blocks`
Other validators available	`required`

Structured text (structured_text)

Property	Value
Code	`structured_text`
Built-in editors for the field	`structured_text`
Required validators	`structured_text_blocks`, `structured_text_links`
Other validators available	`length`

Validators

date_range

Accept dates only inside a specified date range.

Parameter	Type	Required	Description
`min`	ISO 8601 date		Minimum date
`max`	ISO 8601 date		Maximum date

At least one of the parameters must be specified.

date_time_range

Accept date times only inside a specified date range.

Parameter	Type	Required	Description
`min`	ISO 8601 datetime		Minimum datetime
`max`	ISO 8601 datetime		Maximum datetime

At least one of the parameters must be specified.

enum

Only accept a specific set of values

Parameter	Type	Required	Description
`values`	`Array<String>`	✅	Set of allowed values

extension

Only accept assets with specific file extensions.

Parameter	Type	Required	Description
`extensions`	`Array<String>`		Set of allowed file extensions
`predefined_list`	one of `"image"`, `"transformable_image"`, `"video"`, `"document"`		Allowed file type

Only one of the parameters must be specified.

file_size

Accept assets only inside a specified date range.

Parameter	Type	Description
`min_value`	`Integer`	Numeric value for minimum filesize
`min_unit`	one of `"B"`, `"KB"`, `"MB"`	Unit for minimum filesize
`max_value`	`Integer`	Numeric value for maximum filesize
`max_unit`	one of `"B"`, `"KB"`, `"MB"`	Unit for maximum filesize

At least one couple of value/unit must be specified.

format

Accepts only strings that match a specified format.

Parameter	Type	Required	Description
`custom_pattern`	`Regexp`	Optional	Custom regular expression for validation
`predefined_pattern`	`"email"` or `"url"`	Optional	Specifies a pre-defined format (email or URL)

Note: Only one of custom_pattern or predefined_pattern should be specified.

If custom_pattern is used, an additional description parameter can be provided to serve as a hint for the user. This hint offers a simple explanation of the expected pattern, such as "The field must end with an 's'", instead of the default message like "Field must match the pattern: /s$/".

slug_format

Only accept slugs having a specific format.

Parameter	Type	Required	Description
`custom_pattern`	`Regexp`		Regular expression to be validated
`predefined_pattern`	`"webpage_slug"`		Allowed format

Only one of the parameters must be specified.

image_dimensions

Accept assets only within a specified height and width range.

Parameter	Type	Description
`width_min_value`	`Integer`	Numeric value for minimum width
`width_max_value`	`Integer`	Numeric value for maximum height
`height_min_value`	`Integer`	Numeric value for minimum width
`height_max_value`	`Integer`	Numeric value for maximum height

At least one pair of height/width parameters must be specified.

image_aspect_ratio

Accept assets only within a specified aspect ratio range.

Parameter	Type	Description
`min_ar_numerator`	`Integer`	Numerator part of the minimum aspect ratio
`min_ar_denominator`	`Integer`	Denominator part of the minimum aspect ratio
`eq_ar_numerator`	`Integer`	Numerator part for the required aspect ratio
`eq_ar_denominator`	`Integer`	Denominator part for the required aspect ratio
`max_ar_numerator`	`Integer`	Numerator part of the maximum aspect ratio
`max_ar_denominator`	`Integer`	Denominator part of the maximum aspect ratio

At least one pair of numerator/denominator must be specified.

item_item_type

Only accept references to records of the specified models.

Parameter	Type	Required	Description
`item_types`	`Array<Model ID>`	✅	Set of allowed model IDs
`on_publish_with_unpublished_references_strategy`	`"fail"`, `"publish_references"` (default value: `"fail"`)		Strategy to apply when a publishing is requested and this field references some unpublished records
`on_reference_unpublish_strategy`	`"fail"`, `"unpublish"`, `"delete_references"` (default value: `"fail"`)		Strategy to apply when unpublishing is requested for a record referenced by this field
`on_reference_delete_strategy`	`"fail"`, `"delete_references"` (default value: `"delete_references"`)		Strategy to apply when deletion is requested for a record referenced by this field

Possible values for on_publish_with_unpublished_references_strategy:

"fail": Fail the operation and notify the user
"publish_references": Publish also the referenced records

Possible values for on_reference_unpublish_strategy:

"fail": Fail the operation and notify the user
"unpublish": Unpublish also this record
"delete_references": Try to remove the reference to the unpublished record (if the field has a required validation it will fail)

Possible values for on_reference_delete_strategy:

"fail": Fail the operation and notify the user
"delete_references": Try to remove the reference to the deleted record (if the field has a required validation it will fail)

items_item_type

Only accept references to records of the specified models.

Parameter	Type	Required	Description
`item_types`	`Array<Model ID>`	✅	Set of allowed model IDs
`on_publish_with_unpublished_references_strategy`	`"fail"`, `"publish_references"` (default value: `"fail"`)		Strategy to apply when a publishing is requested and this field references some unpublished records
`on_reference_unpublish_strategy`	`"fail"`, `"unpublish"`, `"delete_references"` (default value: `"fail"`)		Strategy to apply when unpublishing is requested for a record referenced by this field
`on_reference_delete_strategy`	`"fail"`, `"delete_references"` (default value: `"delete_references"`)		Strategy to apply when deletion is requested for a record referenced by this field

Possible values for on_publish_with_unpublished_references_strategy:

"fail": Fail the operation and notify the user
"publish_references": Publish also the referenced records

Possible values for on_reference_unpublish_strategy:

"fail": Fail the operation and notify the user
"unpublish": Unpublish also this record
"delete_references": Try to remove the reference to the unpublished record (if the field has a required validation it will fail)

Possible values for on_reference_delete_strategy:

"fail": Fail the operation and notify the user
"delete_references": Try to remove the reference to the deleted record (if the field has a required validation it will fail)

length

Accept strings only with a specified number of characters.

Parameter	Type	Description
`min`	`Integer`	Minimum length
`eq`	`Integer`	Expected length
`max`	`Integer`	Maximum length

At least one parameter must be specified.

number_range

Accept numbers only inside a specified range.

Parameter	Type	Required	Description
`min`	`Float`		Minimum value
`max`	`Float`		Maximum value

At least one of the parameters must be specified.

required

Value must be specified or it won't be valid.

required_alt_title

Assets contained in the field are required to specify custom title or alternate text, or they won't be valid.

Parameter	Type	Required	Description
`title`	`Boolean`		Whether the title for the asset must be specified
`alt`	`Boolean`		Whether the alternate text for the asset must be specified

At least one of the parameters must be specified.

required_seo_fields

SEO field has to specify one or more properties, or it won't be valid.

Parameter	Type	Description
`title`	`Boolean`	Whether the meta title must be specified
`description`	`Boolean`	Whether the meta description must be specified
`image`	`Boolean`	Whether the social sharing image must be specified
`twitter_card`	`Boolean`	Whether the type of Twitter card must be specified

At least one of the parameters must be specified.

title_length

Limits the length of the title for a SEO field. Search engines usually truncate title tags to 60 character so it is a good practice to keep the title around this length.

Parameter	Type	Required	Description
`min`	`Integer`		Minimum value
`max`	`Integer`		Maximum value

At least one of the parameters must be specified.

description_length

Limits the length of the description for a SEO field. Search engines usually truncate description tags to 160 character so it is a good practice to keep the description around this length.

Parameter	Type	Required	Description
`min`	`Integer`		Minimum value
`max`	`Integer`		Maximum value

At least one of the parameters must be specified.

rich_text_blocks

Only accept references to block records of the specified block models.

Parameter	Type	Required	Description
`item_types`	`Array<Block Model ID>`	✅	Set of allowed Block Model IDs

single_block_blocks

Only accept references to block records of the specified block models.

Parameter	Type	Required	Description
`item_types`	`Array<Block Model ID>`	✅	Set of allowed Block Model IDs

sanitization

Checks for the presence of malicious cose in HTML fields: content is valid if no dangerous code is present.

Parameter	Type	Required	Description
`sanitize_before_validation`	`Boolean`	✅	Content is actively sanitized before applying the validation

structured_text_blocks

Only accept references to block records of the specified block models.

Parameter	Type	Required	Description
`item_types`	`Array<Block Model ID>`	✅	Set of allowed Block Model IDs

structured_text_links

Only accept itemLink to inlineItem nodes for records of the specified models.

Parameter	Type	Required	Description
`item_types`	`Array<Model ID>`	✅	Set of allowed model IDs
`on_publish_with_unpublished_references_strategy`	`"fail"`, `"publish_references"` (default value: `"fail"`)		Strategy to apply when a publishing is requested and this field references some unpublished records
`on_reference_unpublish_strategy`	`"fail"`, `"unpublish"`, `"delete_references"` (default value: `"delete_references"`)		Strategy to apply when unpublishing is requested for a record referenced by this field
`on_reference_delete_strategy`	`"fail"`, `"delete_references"` (default value: `"delete_references"`)		Strategy to apply when deletion is requested for a record referenced by this field

Possible values for on_publish_with_unpublished_references_strategy:

"fail": Fail the operation and notify the user
"publish_references": Publish also the referenced records

Possible values for on_reference_unpublish_strategy:

"fail": Fail the operation and notify the user
"unpublish": Unpublish also this record
"delete_references": Try to remove the reference to the unpublished record (if the field has a required validation it will fail)

Possible values for on_reference_delete_strategy:

"fail": Fail the operation and notify the user
"delete_references": Try to remove the reference to the deleted record (if the field has a required validation it will fail)

size

Only accept a number of items within the specified range.

Parameter	Type	Description
`min`	`Integer`	Minimum length
`eq`	`Integer`	Expected length
`max`	`Integer`	Maximum length
`multiple_of`	`Integer`	The number of items must be multiple of this value

At least one parameter must be specified.

slug_title_field

Specifies the ID of the Single-line string field that will be used to generate the slug

Parameter	Type	Required	Description
`title_field_id`	`Field ID`	✅	The field that will be used to generate the slug

unique

The value must be unique across the whole collection of records.

Configuration parameters for DatoCMS built-in field editors

If a field editor is not specified in this table, just pass an empty object {} as its configuration parameters.

boolean_radio_group

Radio group input for boolean fields.

Parameter	Type	Required	Description
`positive_radio`	`{ label: string, hint?: string }`	✅	Radio input for positive choice (`true`)
`negative_radio`	`{ label: string, hint?: string }`	✅	Radio input for negative choice (`false`)

string_radio_group

Radio group input for string fields.

Parameter	Type	Required	Description
`radios`	`Array<{ label: string, value: string, hint?: string }>`	✅	The different radio options

string_select

Select input for string fields.

Parameter	Type	Required	Description
`options`	`Array<{ label: string, value: string, hint?: string }>`	✅	The different select options

string_multi_select

Select input for JSON fields, to edit an array of strings.

Parameter	Type	Required	Description
`options`	`Array<{ label: string, value: string, hint?: string }>`	✅	The different select options

string_checkbox_group

Multiple chechboxes input for JSON fields, to edit an array of strings.

Parameter	Type	Required	Description
`options`	`Array<{ label: string, value: string, hint?: string }>`	✅	The different select options

single_line

Simple textual input for Single-line string fields.

Parameter	Type	Required	Description
`heading`	`Boolean`	✅	Indicates if the field should be shown bigger, as a field representing a heading
`placeholder`	`String`		A placeholder that will be shown in the editor's input to provide editors with an example.

markdown

Markdown editor for Multiple-paragraph text fields.

Parameter	Type	Required	Description
`toolbar`	`Array<String>`	✅	Specify which buttons the toolbar should have. Valid values: `"heading"`, `"bold"`, `"italic"`, `"strikethrough"`, `"code"`, `"unordered_list"`, `"ordered_list"`, `"quote"`, `"link"`, `"image"`, `"fullscreen"`

wysiwyg

HTML editor for Multiple-paragraph text fields.

Parameter	Type	Required	Description
`toolbar`	`Array<String>`	✅	Specify which buttons the toolbar should have. Valid values: `"format"`, `"bold"`, `"italic"`, `"strikethrough"`, `"code"`, `"ordered_list"`, `"unordered_list"`, `"quote"`, `"table"`, `"link"`, `"image"`, `"show_source"`, `"undo"`, `"redo"`, `"align_left"`, `"align_center"`, `"align_right"`, `"align_justify"`, `"outdent"`, `"indent"`, `"fullscreen"`

textarea

Basic textarea editor for Multiple-paragraph text fields.

Parameter	Type	Required	Description
`placeholder`	`String`		A placeholder that will be shown in the editor's input to provide editors with an example.

color_picker

Built-in editor for Color fields.

Parameter	Type	Required	Description
`enable_alpha`	`Boolean`	✅	Should the color picker allow to specify the alpha value?
`preset_colors`	`Array<Hex color string>`	✅	List of preset colors to offer to the user

slug

Built-in editor for Slug fields.

Parameter	Type	Required	Description
`url_prefix`	`String`		A prefix that will be shown in the editor's form to give some context to your editors.
`placeholder`	`String`		A placeholder that will be shown in the editor's input to provide editors with an example.

seo

Built-in editor for seo fields.

Parameter	Type	Required	Description
`fields`	`Array<String>`	✅	Specify which fields of the SEO input should be visible to editors. Valid values: `"title"`, `"description"`, `"image"`, `"no_index"`, `"twitter_card"`
`previews`	`Array<String>`	✅	Specify which previews should be visible to editors. Valid values: `"google_search"`, `"twitter"`, `"slack"`, `"whatsapp"`, `"telegram"`, `"facebook"`, `"linkedin"`

rich_text

Built-in editor for Modular content fields.

Parameter	Type	Required	Description
`start_collapsed`	`Boolean`		Whether you want block records collapsed by default or not

framed_single_block

Built-in editor for Single block fields.

Parameter	Type	Required	Description
`start_collapsed`	`Boolean`		Whether you want block record collapsed by default or not

structured_text

Built-in editor for Structured text fields.

Parameter	Type	Required	Description
`nodes`	`Array<String>`	✅	Specify which nodes the field should allow. Valid values: `"blockquote"`, `"code"`, `"heading"`, `"link"`, `"list"`, `"thematicBreak"`
`marks`	`Array<String>`	✅	Specify which marks the field should allow. Valid values: `"strong"`, `"emphasis"`, `"underline"`, `"strikethrough"`, `"code"`, `"highlight"`
`heading_levels`	`Array<Integer>`	✅	If `nodes` includes `"heading"`, specify which heading levels the field should allow. Valid values: numbers between 1 and 6
`blocks_start_collapsed`	`Boolean`		Whether you want block nodes collapsed by default or not
`show_links_target_blank`	`Boolean`		Whether you want to show the "Open this link in a new tab?" checkbox, that fills in the `target: "_blank"` meta attribute for links
`show_links_meta_editor`	`Boolean`		Whether you want to show the complete meta editor for links

link_select and links_select

Use a select input with auto-completion to pick the records to reference inside the field.

link_embed and links_embed

Use an expanded view with records' image preview to pick the records to reference inside the field.

integer

Built-in editor for Integer fields.

Parameter	Type	Required	Description
`placeholder`	`String`		A placeholder that will be shown in the editor's input to provide editors with an example.

float

Built-in editor for Float fields.

Parameter	Type	Required	Description
`placeholder`	`String`		A placeholder that will be shown in the editor's input to provide editors with an example.

Object payload

id string

RFC 4122 UUID of field expressed in URL-safe base64 format

type string

Must be exactly "field"

label string Example: "Title"

The label of the field

field_type enum Example: "string"

Type of input

api_key string Example: "title"

Field API key

localized boolean Example: true

Whether the field needs to be multilanguage or not

validators object Example: {"required":{}}

Optional field validations

position integer Example: 1

Ordering index

hint string, null Example: "This field will be used as post title"

Field hint

default_value boolean, null, string, number, object Example: {"en":"A default value","it":"Un valore di default"}

Default value for Field. When field is localized accepts an object of default values with site locales as keys

appearance object Example: {"editor":"single_line","parameters":{"heading":false},"addons":[{"id":"1234","field_extension":"lorem_ipsum","parameters":{}}]}

Field appearance details, plugin configuration and field add-ons

deep_filtering_enabled boolean Example: true

Whether deep filtering for block models is enabled in GraphQL or not

item_type{ type: "item_type", id: item_type.id }

Field item type

fieldsetnull, { type: "fieldset", id: fieldset.id }

Fieldset linkage

Available endpoints

Did this doc help you?

Still need help?

Explore our forum, contact support, or connect with our sales team. You can also chat live with other users in our Slack channel.