Create a new field - Field - Content Management API

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.

For both properties, the value you can specify when creating a new field depends on the type of field itself. That is, you can add a "Limit character count" validation to a Single-line string field, or set its appearence to "Show it as heading", but you can't if you're creating Color field, because it doesn't make much sense. The Color fields 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 value is an object representing any additional settings that the validation itself might require. 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 }
  }
}

Following 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 Slug field needs to have a slug_title_field validator to specify the ID of the Single-line string field that will be used to generate the slug itself.

Specifying the appearance

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

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": []
  },
}

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.

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

You can also set the editor to be the ID of a Field editor plugin that is currently installed inside the project. If you do so, the parameters property must be filled with the instance parameters of that specific plugin:

{
  "appearance": {
    // "2132" is a the ID of an field-editor plugin
    "editor": "2134",
    // these are the specific instance-settings that the plugin requires
    "parameters": { "debug_mode": true },
    "addons": []
  },
}

The last property is addons, and is an array of Field-addon plugins that you want to install on a specific field:

{
  "appearance": {
    "editor": "single_line",
    "parameters": { "heading": true },
    "addons": [
      {
        // "2138" is a the ID of an field-addon plugin
        "id": "2138",
        // these are the specific instance-settings that the plugin requires
        "parameters": { "debug_mode": true },
      }
    ]
  },
}

If during the creation of the field you won't pass the appearance property, DatoCMS will use the default editor for that specific field type.

Available field types

Single-line string

Property	Value
`field_type`	`string`
Possible values for `editor`	`single_line`, `string_radio_group`, `string_select`
Available validators	`required`, `unique`, `length`, `format`, `enum`

Multi-line text

Property	Value
`field_type`	`text`
Possible values for `editor`	`markdown`, `wysiwyg`, `textarea`
Available validators	`required`, `length`, `format`

Boolean

Property	Value
`field_type`	`boolean`
Possible values for `editor`	`boolean`, `boolean_radio_group`
Available validators	no validators available

Integer

Property	Value
`field_type`	`integer`
Possible values for `editor`	`integer`
Available validators	`required`, `number_range`

Float

Property	Value
`field_type`	`float`
Possible values for `editor`	`float`
Available validators	`required`, `number_range`

Date

Property	Value
`field_type`	`date`
Possible values for `editor`	`date_picker`
Available validators	`required`, `date_range`

Date time

Property	Value
`field_type`	`date_time`
Possible values for `editor`	`date_time_picker`
Available validators	`required`, `date_time_range`

Color

Property	Value
`field_type`	`color`
Possible values for `editor`	`color_picker`
Available validators	`required`

JSON

Property	Value
`field_type`	`json`
Possible values for `editor`	`json`
Available validators	`required`

Location

Property	Value
`field_type`	`lat_lon`
Possible values for `editor`	`map`
Available validators	`required`

SEO

Property	Value
`field_type`	`seo`
Possible values for `editor`	`seo`
Available validators	`required_seo_fields`, `file_size`, `image_dimensions`, `title_length`, `description_length`

Slug

Property	Value
`field_type`	`slug`
Possible values for `editor`	`slug`
Required validators	`slug_title_field`
Other validators available	`required`, `length`, `slug_format`

External video

Property	Value
`field_type`	`video`
Possible values for `editor`	`video`
Available validators	`required`

Single-asset

Property	Value
`field_type`	`file`
Possible values for `editor`	`file`
Available validators	`required`, `file_size`, `image_dimensions`, `extension`, `required_alt_title`

Asset gallery

Property	Value
`field_type`	`gallery`
Possible values for `editor`	`gallery`
Available validators	`size`, `file_size`, `image_dimensions`, `extension`, `required_alt_title`

Single link

Property	Value
`field_type`	`link`
Possible values for `editor`	`link_select`, `link_embed`
Default `editor`	`link_select`
Required validators	`item_item_type`
Other validators available	`required`, `unique`

Multiple links

Property	Value
`field_type`	`links`
Possible values for `editor`	`links_select`, `links_embed`
Default `editor`	`links_select`
Required validators	`items_item_type`
Other validators available	`size`

Modular content

Property	Value
`field_type`	`rich_text`
Possible values for `editor`	`rich_text`
Required validators	`rich_text_blocks`
Other validators available	`size`

Structured text

Property	Value
`field_type`	`structured_text`
Possible values for `editor`	`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"`, `"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

Only 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_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/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 parameter 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 is 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

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.

Built-in editor parameters

If an editor is not specified in this table, just pass an empty object {} as its 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

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

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.

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.

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

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

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

link_embed / links_embed

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

Parameters

label string Optional

The label of the field

fieldType string Optional

Type of input

apiKey string Optional

Field API key

localized boolean Optional

Whether the field needs to be multilanguage or not

validators object Optional

Optional field validations

appearance object Optional

Field appearance details, plugin configuration and field add-ons

position integer Optional

Ordering index

hint string, null Optional

Field hint

defaultValue boolean, null, string, number, object Optional

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

fieldset null, fieldset.id Required

Fieldset linkage

Returns

Returns a field object.

Basic example

This is a complete example for creating a new localized Single-line string field:

Example code:

const SiteClient = require('datocms-client').SiteClient;
const client = new SiteClient('YOUR-API-TOKEN');
const modelIdOrApiKey = 'blog_post';
client.field.create(modelIdOrApiKey, {
  label: 'Title',
  fieldType: 'string',
  apiKey: 'title',
  localized: true,
  validators: {
    required: {}
  },
  appearance: {
    editor: 'single_line',
    parameters: {
      heading: false
    },
    addons: [
      {
        id: '1234',
        fieldExtension: 'lorem_ipsum',
        parameters: {}
      }
    ]
  },
  position: 1,
  hint: 'This field will be used as post title',
  defaultValue: {
    en: 'A default value',
    it: 'Un valore di default'
  },
  fieldset: null
})
.then((field) => {
  console.log(field);
})
.catch((error) => {
  console.error(error);
});

Returned output:

> node example.js
{
  "id": "124",
  "label": "Title",
  "fieldType": "string",
  "localized": true,
  "defaultValue": {
    "en": "A default value",
    "it": "Un valore di default"
  },
  "apiKey": "title",
  "hint": "This field will be used as post title",
  "validators": {
    "required": {}
  },
  "appearance": {
    "editor": "single_line",
    "parameters": {
      "heading": false
    },
    "addons": [
      {
        "id": "1234",
        "fieldExtension": "lorem_ipsum",
        "parameters": {}
      }
    ]
  },
  "position": 1,
  "itemType": "44",
  "fieldset": null
}

Creating Modular Content fields

To create a Modular content field, you first need to create the block models.

For DatoCMS, a block model is just like a regular model, so we'll create them with client.itemTypes.create(), passing the modularBlock property to true:

Example code:

const { SiteClient } = require("datocms-client");
const client = new SiteClient("YOUR-API-TOKEN");
async function createModularContent() {
  const modularBlock1 = await client.itemTypes.create({
    name: "Modular Block 1",
    apiKey: "modular_block1",
    modularBlock: true,
  });
  const modularBlock2 = await client.itemTypes.create({
    name: "Modular Block 2",
    apiKey: "modular_block2",
    modularBlock: true,
  });
  const itemTypeId = "1234";
  const field = await client.fields.create(itemTypeId, {
    label: "Content",
    fieldType: "rich_text",
    apiKey: "content",
    validators: {
      richTextBlocks: {
        itemTypes: [modularBlock1.id, modularBlock2.id],
      },
    },
  });
  console.log(field);
}
createModularContent();

Returned output:

{
  id: "1033076",
  label: "Content",
  fieldType: "rich_text",
  apiKey: "content",
  localized: false,
  hint: null,
  validators: {
    richTextBlocks: { itemTypes: [Array] },
  },
  appeareance: {
    editor: "rich_text",
    parameters: {
      startCollapsed: false,
    },
    addons: [],
  },
  position: 4,
}

Creating Structured Text fields

Stuctured Text fields support both embedded block records and links to other regular records.

For DatoCMS, a block model is just like a regular model, so we'll create them with client.itemTypes.create(), passing the modularBlock property to true:

Example code:

const { SiteClient } = require("datocms-client");
const client = new SiteClient("YOUR-API-TOKEN");
async function createModularContent() {
  const modularBlock1 = await client.itemTypes.create({
    name: "Modular Block 1",
    apiKey: "modular_block1",
    modularBlock: true,
  });
  const modularBlock2 = await client.itemTypes.create({
    name: "Modular Block 2",
    apiKey: "modular_block2",
    modularBlock: true,
  });
  const itemTypeId = "1234";
  const field = await client.fields.create(itemTypeId, {
    label: "Structured content",
    fieldType: "structured_text",
    apiKey: "content",
    validators: {
      structuredTextBlocks: {
        itemTypes: [modularBlock1.id, modularBlock2.id],
      },
      structuredTextLinks: {
        itemTypes: [itemTypeId],
      },
    },
  });
  console.log(field);
}
createModularContent();

Returned output:

{
  id: "1033076",
  label: "Content",
  localized: false,
  apiKey: "content",
  fieldType: "structured_text",
  hint: null,
  validators: {
    structuredTextBlocks: { itemTypes: [Array] },
    structuredTextLinks: { itemTypes: [Array] },
  },
  appeareance: {
    editor: "structured_text",
    parameters: {
      startCollapsed: false,
      nodes: [Array],
      marks: [Array],
    },
    addons: [],
  },
  position: 4,
}

Questions?

We're always happy to help with code or other questions you might have. Search our documentation, forum, contact support, or connect with our sales team. You can chat live with other developers in our Slack channel.