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.
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.
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.
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 },"addons": []},}
Following you'll find a summary of all the editors available for each field type with their settings.
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 build-in editors.
In this case:
editor property must be the ID of the plugin;field_extension property must be the ID of the specific manual field editor that the plugin exposes;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": []},}
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 },"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 },}]},}
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 |
text)| Property | Value |
|---|---|
| Code | text |
| Built-in editors for the field | markdown, wysiwyg, textarea |
| Available validators | required, length, format |
boolean)| Property | Value |
|---|---|
| Code | boolean |
| Built-in editors for the field | boolean, boolean_radio_group |
| Available validators | no validators available |
integer)| Property | Value |
|---|---|
| Code | integer |
| Built-in editors for the field | integer |
| Available validators | required, number_range |
float)| Property | Value |
|---|---|
| Code | float |
| Built-in editors for the field | float |
| Available validators | required, number_range |
date)| Property | Value |
|---|---|
| Code | date |
| Built-in editors for the field | date_picker |
| Available validators | required, date_range |
date_time)| Property | Value |
|---|---|
| Code | date_time |
| Built-in editors for the field | date_time_picker |
| Available validators | required, date_time_range |
color)| Property | Value |
|---|---|
| Code | color |
| Built-in editors for the field | color_picker |
| Available validators | required |
json)| Property | Value |
|---|---|
| Code | json |
| Built-in editors for the field | json, string_multi_select, string_checkbox_group |
| Available validators | required |
lat_lon)| Property | Value |
|---|---|
| Code | lat_lon |
| Built-in editors for the field | map |
| Available validators | required |
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)| Property | Value |
|---|---|
| Code | slug |
| Built-in editors for the field | slug |
| Available validators | required, length, slug_format, slug_title_field |
video)| Property | Value |
|---|---|
| Code | video |
| Built-in editors for the field | video |
| Available validators | required |
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 |
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 |
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 |
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 |
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)| 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)| 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 |
date_rangeAccept 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_rangeAccept 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.
enumOnly accept a specific set of values
| Parameter | Type | Required | Description |
|---|---|---|---|
values | Array<String> | ✅ | Set of allowed values |
extensionOnly 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_sizeAccept assets only inside a specified date range.
| Parameter | Type | Required | 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.
formatOnly accept strings having a specific format.
| Parameter | Type | Required | Description |
|---|---|---|---|
custom_pattern | Regexp | Regular expression to be validated | |
predefined_pattern | one of "email", "url" | Allowed format |
Only one of the parameters must be specified.
slug_formatOnly 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_dimensionsAccept assets only within a specified height and width range.
| Parameter | Type | Required | 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_ratioAccept assets only within a specified aspect ratio range.
| Parameter | Type | Required | 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_typeOnly 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 recordsPossible 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_typeOnly 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 recordsPossible 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)lengthAccept strings only with a specified number of characters.
| Parameter | Type | Required | Description |
|---|---|---|---|
min | Integer | Minimum length | |
eq | Integer | Expected length | |
max | Integer | Maximum length |
At least one parameter must be specified.
number_rangeAccept 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.
requiredValue must be specified or it won't be valid.
required_alt_titleAssets 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_fieldsSEO field has to specify one or more properties, or it won't be valid.
| Parameter | Type | Required | 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_lengthLimits 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_lengthLimits 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_blocksOnly 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_blocksOnly 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 |
sanitizationChecks 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_blocksOnly 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_linksOnly 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 recordsPossible 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)sizeOnly accept a number of items within the specified range.
| Parameter | Type | Required | 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_fieldSpecifies 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 |
uniqueThe value must be unique across the whole collection of records.
If a field editor is not specified in this table, just pass an empty object {} as its configuration parameters.
boolean_radio_groupRadio 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_groupRadio group input for string fields.
| Parameter | Type | Required | Description |
|---|---|---|---|
radios | Array<{ label: string, value: string, hint?: string }> | ✅ | The different radio options |
string_selectSelect input for string fields.
| Parameter | Type | Required | Description |
|---|---|---|---|
options | Array<{ label: string, value: string, hint?: string }> | ✅ | The different select options |
string_multi_selectSelect 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_groupMultiple 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_lineSimple 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 |
markdownMarkdown 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" |
wysiwygHTML 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" |
textareaBasic textarea editor for Multiple-paragraph text fields.
color_pickerBuilt-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 |
slugBuilt-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. |
seoBuilt-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_textBuilt-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_blockBuilt-in editor for Single block fields.
| Parameter | Type | Required | Description |
|---|---|---|---|
start_collapsed | Boolean | Whether you want block record collapsed by default or not |
structured_textBuilt-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_selectUse a select input with auto-completion to pick the records to reference inside the field.
link_embed and links_embedUse an expanded view with records' image preview to pick the records to reference inside the field.
"field"The label of the field
Type of input
Field API key
Whether the field needs to be multilanguage or not
Optional field validations
Ordering index
Field hint
Default value for Field. When field is localized accepts an object of default values with site locales as keys
Field appearance details, plugin configuration and field add-ons
Whether deep filtering for block models is enabled in GraphQL or not
Field item type
Fieldset linkage