# Field

DatoCMS offers a number of different fields that you can combine together to create a [Model](https://www.datocms.com/docs/content-management-api/resources/item-type.md). 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:

```js
{
  "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:

```js
{
  "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](https://www.datocms.com/docs/plugin-sdk/manual-field-extensions.md), 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](https://www.datocms.com/docs/content-management-api/resources/plugin/instances.md) 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](https://www.datocms.com/docs/plugin-sdk/manual-field-extensions.md#add-per-field-config-screens-to-manual-field-extensions), or an empty object if it doesn't require any configuration.

```js
{
  "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](https://www.datocms.com/docs/plugin-sdk/manual-field-extensions.md), you can also add them to the field via the `addons` property.

```js
{
  "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

<details>
<summary>Single-line string (string)</summary>

| Property | Value |
| --- | --- |

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

</details>

<details>
<summary>Multi-line text (text)</summary>

| Property | Value |
| --- | --- |

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

</details>

<details>
<summary>Boolean (boolean)</summary>

| Property | Value |
| --- | --- |

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

</details>

<details>
<summary>Integer (integer)</summary>

| Property | Value |
| --- | --- |

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

</details>

<details>
<summary>Float (float)</summary>

| Property | Value |
| --- | --- |

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

</details>

<details>
<summary>Date (date)</summary>

| Property | Value |
| --- | --- |

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

</details>

<details>
<summary>Date time (date_time)</summary>

| Property | Value |
| --- | --- |

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

</details>

<details>
<summary>Color (color)</summary>

| Property | Value |
| --- | --- |

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

</details>

<details>
<summary>JSON (json)</summary>

| Property | Value |
| --- | --- |

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

</details>

<details>
<summary>Location (lat_lon)</summary>

| Property | Value |
| --- | --- |

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

</details>

<details>
<summary>SEO and Social (seo)</summary>

| 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` |

</details>

<details>
<summary>Slug (slug)</summary>

| Property | Value |
| --- | --- |

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

</details>

<details>
<summary>External video (video)</summary>

| Property | Value |
| --- | --- |

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

</details>

<details>
<summary>Single-asset (file)</summary>

| 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` |

</details>

<details>
<summary>Asset gallery (gallery)</summary>

| 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` |

</details>

<details>
<summary>Single link (link)</summary>

| 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` |

</details>

<details>
<summary>Multiple links (links)</summary>

| 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` |

</details>

<details>
<summary>Modular content (rich_text)</summary>

| Property | Value |
| --- | --- |

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

</details>

<details>
<summary>Single Block (single_block)</summary>

| 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` |

</details>

<details>
<summary>Structured text (structured_text)</summary>

| Property | Value |
| --- | --- |

| Code | `structured_text` |
| Built-in editors for the field | `structured_text` |
| Required validators | `structured_text_blocks`, `structured_text_links` |
| Other validators available | `required`, `length`, `structured_text_inline_blocks` |

</details>

### Validators

<details>
<summary>date_range</summary>

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.

</details>

<details>
<summary>date_time_range</summary>

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.

</details>

<details>
<summary>enum</summary>

Only accept a specific set of values

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |

| `values` | `Array<String>` | ✅ | Set of allowed values |

</details>

<details>
<summary>extension</summary>

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.

</details>

<details>
<summary>file_size</summary>

Accept 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.

</details>

<details>
<summary>format</summary>

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$/"`.

</details>

<details>
<summary>slug_format</summary>

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.

</details>

<details>
<summary>image_dimensions</summary>

Accept 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.

</details>

<details>
<summary>image_aspect_ratio</summary>

Accept 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.

</details>

<details>
<summary>item_item_type</summary>

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)

</details>

<details>
<summary>items_item_type</summary>

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)

</details>

<details>
<summary>length</summary>

Accept 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.

</details>

<details>
<summary>number_range</summary>

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.

</details>

<details>
<summary>required</summary>

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

</details>

<details>
<summary>required_alt_title</summary>

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.

</details>

<details>
<summary>required_seo_fields</summary>

SEO 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.

</details>

<details>
<summary>title_length</summary>

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.

</details>

<details>
<summary>description_length</summary>

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.

</details>

<details>
<summary>rich_text_blocks</summary>

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 |

</details>

<details>
<summary>single_block_blocks</summary>

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 |

</details>

<details>
<summary>sanitized_html</summary>

Checks for the presence of malicious code 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 |

</details>

<details>
<summary>structured_text_blocks</summary>

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 |

</details>

<details>
<summary>structured_text_inline_blocks</summary>

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 |

</details>

<details>
<summary>structured_text_links</summary>

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)

</details>

<details>
<summary>size</summary>

Only 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.

</details>

<details>
<summary>slug_title_field</summary>

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 |

</details>

<details>
<summary>unique</summary>

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

</details>

### 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.

<details>
<summary>boolean_radio_group</summary>

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`) |

</details>

<details>
<summary>string_radio_group</summary>

Radio group input for *string* fields.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |

| `radios` | `Array<{ label: string, value: string, hint?: string }>` | ✅ | The different radio options |

</details>

<details>
<summary>string_select</summary>

Select input for *string* fields.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |

| `options` | `Array<{ label: string, value: string, hint?: string }>` | ✅ | The different select options |

</details>

<details>
<summary>string_multi_select</summary>

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 |

</details>

<details>
<summary>string_checkbox_group</summary>

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 |

</details>

<details>
<summary>single_line</summary>

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. |

</details>

<details>
<summary>markdown</summary>

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"` |

</details>

<details>
<summary>wysiwyg</summary>

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"` |

</details>

<details>
<summary>textarea</summary>

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. |

</details>

<details>
<summary>color_picker</summary>

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 |

</details>

<details>
<summary>slug</summary>

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. |

</details>

<details>
<summary>seo</summary>

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"`, `"twitter"`, `"slack"`, `"whatsapp"`, `"telegram"`, `"facebook"`, `"linkedin"` |

</details>

<details>
<summary>rich_text</summary>

Built-in editor for *Modular content* fields.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |

| `start_collapsed` | `Boolean` |  | Whether you want block records collapsed by default or not |

</details>

<details>
<summary>framed_single_block</summary>

Built-in editor for *Single block* fields.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |

| `start_collapsed` | `Boolean` |  | Whether you want block record collapsed by default or not |

</details>

<details>
<summary>structured_text</summary>

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 |

</details>

<details>
<summary>link_select and links_select</summary>

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

</details>

<details>
<summary>link_embed and links_embed</summary>

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

</details>

<details>
<summary>integer</summary>

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. |

</details>

<details>
<summary>float</summary>

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. |

</details>

## Object payload

id string

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

Example: `"Pkg-oztERp6o-Rj76nYKJg"`

type string

Must be exactly `"field"`.

label string

The label of the field

Example: `"Title"`

field\_type enum

Type of input

Example: `"string"`

Show enum values

boolean

color

date

date\_time

file

float

gallery

integer

json

lat\_lon

link

links

rich\_text

seo

single\_block

slug

string

structured\_text

text

video

api\_key string

Field API key

Example: `"title"`

localized boolean

Whether the field needs to be multilanguage or not

validators object

Optional field validations

Example: `{ required: {} }`

position integer

Ordering index

Example: `1`

hint string, null

Field hint

Example: `"This field will be used as post title"`

default\_value

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

Type: boolean, null, string, number, object

Example: `{ en: "A default value", it: "Un valore di default" }`

appearance object

Field appearance details, plugin configuration and field add-ons

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

Show object format

editor string

A valid editor can be a DatoCMS default field editor type (ie. `"single_line"`), or a plugin ID offering a custom field editor

parameters object

The editor plugin's parameters

addons

An array of add-on plugins with id and parameters

Type: Array<object\>

Show objects format inside array

id string

The ID of a plugin offering a field addon

parameters object

field\_extension string

The specific field extension to use for the field (only if the editor is a modern plugin)

field\_extension string

The specific field extension to use for the field (only if the editor is a modern plugin)

deep\_filtering\_enabled boolean

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

item\_type

Field item type

Type: [ResourceLinkage<"item\_type"\>](https://www.datocms.com/docs/content-management-api/resources/item_type.md)

fieldset

Fieldset linkage

Type: null, [ResourceLinkage<"fieldset"\>](https://www.datocms.com/docs/content-management-api/resources/fieldset.md)

Show deprecated

appeareance object Deprecated

Field appearance

This field contains a typo and will be removed in future versions: use `appearance` instead

Show object format

editor string

parameters object

## Available endpoints

-   [Create a new field](https://www.datocms.com/docs/content-management-api/resources/field/create.md)

-   [Update a field](https://www.datocms.com/docs/content-management-api/resources/field/update.md)
-   [List all fields of a model/block](https://www.datocms.com/docs/content-management-api/resources/field/instances.md)

-   [List fields referencing a model/block](https://www.datocms.com/docs/content-management-api/resources/field/referencing.md)
-   [Retrieve a field](https://www.datocms.com/docs/content-management-api/resources/field/self.md)

-   [Delete a field](https://www.datocms.com/docs/content-management-api/resources/field/destroy.md)
-   [Duplicate a field](https://www.datocms.com/docs/content-management-api/resources/field/duplicate.md)

## Related content in "Content Management API"

- [Content Management API Overview](https://www.datocms.com/docs/content-management-api.md)

- [Using the JavaScript CMA client](https://www.datocms.com/docs/content-management-api/using-the-nodejs-clients.md)
- [API versioning](https://www.datocms.com/docs/content-management-api/api-versioning.md)

- [Authentication](https://www.datocms.com/docs/content-management-api/authentication.md)
- [Environments](https://www.datocms.com/docs/content-management-api/setting-the-environment.md)

- [Error codes & handling failures (CMA)](https://www.datocms.com/docs/content-management-api/errors.md)
- [Pagination](https://www.datocms.com/docs/content-management-api/pagination.md)

- [Asynchronous jobs](https://www.datocms.com/docs/content-management-api/async-jobs.md)
- [Technical Limits (CMA)](https://www.datocms.com/docs/content-management-api/technical-limits.md)

- [Record](https://www.datocms.com/docs/content-management-api/resources/item.md)
- [Scheduled publication](https://www.datocms.com/docs/content-management-api/resources/scheduled-publication.md)

- [Scheduled unpublishing](https://www.datocms.com/docs/content-management-api/resources/scheduled-unpublishing.md)
- [Upload](https://www.datocms.com/docs/content-management-api/resources/upload.md)

- [Site](https://www.datocms.com/docs/content-management-api/resources/site.md)
- [Model/Block model](https://www.datocms.com/docs/content-management-api/resources/item-type.md)

- [Field](https://www.datocms.com/docs/content-management-api/resources/field.md)
- [Create a new field](https://www.datocms.com/docs/content-management-api/resources/field/create.md)

- [Update a field](https://www.datocms.com/docs/content-management-api/resources/field/update.md)
- [List all fields of a model/block](https://www.datocms.com/docs/content-management-api/resources/field/instances.md)

- [List fields referencing a model/block](https://www.datocms.com/docs/content-management-api/resources/field/referencing.md)
- [Retrieve a field](https://www.datocms.com/docs/content-management-api/resources/field/self.md)

- [Delete a field](https://www.datocms.com/docs/content-management-api/resources/field/destroy.md)
- [Duplicate a field](https://www.datocms.com/docs/content-management-api/resources/field/duplicate.md)

- [Fieldset](https://www.datocms.com/docs/content-management-api/resources/fieldset.md)
- [Record version](https://www.datocms.com/docs/content-management-api/resources/item-version.md)

- [Upload permission](https://www.datocms.com/docs/content-management-api/resources/upload-request.md)
- [Upload track](https://www.datocms.com/docs/content-management-api/resources/upload-track.md)

- [Manual tags](https://www.datocms.com/docs/content-management-api/resources/upload-tag.md)
- [Smart tags](https://www.datocms.com/docs/content-management-api/resources/upload-smart-tag.md)

- [Upload Collection](https://www.datocms.com/docs/content-management-api/resources/upload-collection.md)
- [Search Index](https://www.datocms.com/docs/content-management-api/resources/search-index.md)

- [Search result](https://www.datocms.com/docs/content-management-api/resources/search-result.md)
- [Search indexing activity](https://www.datocms.com/docs/content-management-api/resources/search-index-event.md)

- [Environment](https://www.datocms.com/docs/content-management-api/resources/environment.md)
- [Maintenance mode](https://www.datocms.com/docs/content-management-api/resources/maintenance-mode.md)

- [Menu Item](https://www.datocms.com/docs/content-management-api/resources/menu-item.md)
- [Schema Menu Item](https://www.datocms.com/docs/content-management-api/resources/schema-menu-item.md)

- [Uploads filter](https://www.datocms.com/docs/content-management-api/resources/upload-filter.md)
- [Model filter](https://www.datocms.com/docs/content-management-api/resources/item-type-filter.md)

- [Plugin](https://www.datocms.com/docs/content-management-api/resources/plugin.md)
- [Workflow](https://www.datocms.com/docs/content-management-api/resources/workflow.md)

- [Asynchronous job](https://www.datocms.com/docs/content-management-api/resources/job.md)
- [Job result](https://www.datocms.com/docs/content-management-api/resources/job-result.md)

- [Account](https://www.datocms.com/docs/content-management-api/resources/account.md)
- [Organization](https://www.datocms.com/docs/content-management-api/resources/organization.md)

- [Invitation](https://www.datocms.com/docs/content-management-api/resources/site-invitation.md)
- [Collaborator](https://www.datocms.com/docs/content-management-api/resources/user.md)

- [Role](https://www.datocms.com/docs/content-management-api/resources/role.md)
- [API token](https://www.datocms.com/docs/content-management-api/resources/access-token.md)

- [Webhook](https://www.datocms.com/docs/content-management-api/resources/webhook.md)
- [Webhook call](https://www.datocms.com/docs/content-management-api/resources/webhook-call.md)

- [Build trigger](https://www.datocms.com/docs/content-management-api/resources/build-trigger.md)
- [Deploy activity](https://www.datocms.com/docs/content-management-api/resources/build-event.md)

- [Subscription limit](https://www.datocms.com/docs/content-management-api/resources/subscription-limit.md)
- [Subscription feature](https://www.datocms.com/docs/content-management-api/resources/subscription-feature.md)

- [SSO Settings](https://www.datocms.com/docs/content-management-api/resources/sso-settings.md)
- [SSO User](https://www.datocms.com/docs/content-management-api/resources/sso-user.md)

- [SSO Group](https://www.datocms.com/docs/content-management-api/resources/sso-group.md)
- [White-label settings](https://www.datocms.com/docs/content-management-api/resources/white-label-settings.md)

- [Audit log event](https://www.datocms.com/docs/content-management-api/resources/audit-log-event.md)