Show examples in:

Javascript HTTP

Endpoint info

Body parameters

Returns

Available examples

Basic example

Creating Modular Content fields

Creating Structured Text fields

Content Management API > Field

Create a new field

Body parameters

id string Optional

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

Example:

"Pkg-oztERp6o-Rj76nYKJg"

label string Required

The label of the field

Example:

"Title"

field_type enum Required

Type of input

Example:

"string"

boolean Optional

color Optional

date Optional

date_time Optional

file Optional

float Optional

gallery Optional

integer Optional

json Optional

lat_lon Optional

link Optional

links Optional

rich_text Optional

seo Optional

single_block Optional

slug Optional

string Optional

structured_text Optional

text Optional

video Optional

api_key string Required

Field API key

Example:

"title"

localized boolean Optional

Whether the field needs to be multilanguage or not

validators object Optional

Optional field validations

Example:

{ required: {} }

appearance object Optional

Field appearance details, plugin configuration and field add-ons

Example:

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

editor string Required

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 Required

The editor plugin's parameters

addons Required

An array of add-on plugins with id and parameters

Type: Array<object>

id string Required

The ID of a plugin offering a field addon

parameters object Required

field_extension string Optional

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

field_extension string Optional

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

position integer Optional

Ordering index

Example:

hint string, null Optional

Field hint

Example:

"This field will be used as post title"

default_value Optional

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

deep_filtering_enabled boolean Optional

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

fieldset Optional

Fieldset linkage

Type: null, ResourceLinkage<"fieldset">

appeareance object Deprecated

Field appearance

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

editor string Required

parameters object Required

Returns

Returns a resource object of type field

Other examples

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

1
import { buildClient } from "@datocms/cma-client-node";
2

3
async function run() {
4
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
5

6
  const modelIdOrApiKey = "blog_post";
7

8
  const field = await client.fields.create(modelIdOrApiKey, {
9
    label: "Title",
10
    field_type: "string",
11
    api_key: "title",
12
  });
13

14
  // Check the 'Returned output' tab for the result ☝️
15
  console.log(field);
16
}
17

18
run();

1
{
2
  id: "Pkg-oztERp6o-Rj76nYKJg",
3
  label: "Title",
4
  field_type: "string",
5
  api_key: "title",
6
  localized: true,
7
  validators: { required: {} },
8
  position: 1,
9
  hint: "This field will be used as post title",
10
  default_value: { en: "A default value", it: "Un valore di default" },
11
  appearance: {
12
    editor: "single_line",
13
    parameters: { heading: false },
14
    addons: [{ id: "1234", field_extension: "lorem_ipsum", parameters: {} }],
15
  },
16
  deep_filtering_enabled: true,
17
  item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" },
18
  fieldset: null,
19
}

In this example:

first we create some block models using the client.itemTypes.create() method, making sure to set the modular_block attribute to true — this tells the API that they're in fact block models, and not regular models;
we then create a Modular content field, passing down the allowed block models in the rich_text_blocks validator:

1
import { buildClient } from "@datocms/cma-client-node";
2

3
async function run() {
4
  // Make sure the API token has access to the CMA, and is stored securely
5
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
6

7
  const modularBlock1 = await client.itemTypes.create({
8
    name: "Modular Block 1",
9
    api_key: "modular_block1",
10
    modular_block: true,
11
  });
12

13
  const modularBlock2 = await client.itemTypes.create({
14
    name: "Modular Block 2",
15
    api_key: "modular_block2",
16
    modular_block: true,
17
  });
18

19
  const itemTypeId = "1234";
20

21
  const field = await client.fields.create(itemTypeId, {
22
    label: "Content",
23
    field_type: "rich_text",
24
    api_key: "content",
25
    validators: {
26
      rich_text_blocks: {
27
        item_types: [modularBlock1.id, modularBlock2.id],
28
      },
29
    },
30
  });
31

32
  console.log(field);
33
}
34

35
run();

1
{
2
  id: "Pkg-oztERp6o-Rj76nYKJg",
3
  label: "Title",
4
  field_type: "string",
5
  api_key: "title",
6
  localized: true,
7
  validators: { required: {} },
8
  position: 1,
9
  hint: "This field will be used as post title",
10
  default_value: { en: "A default value", it: "Un valore di default" },
11
  appearance: {
12
    editor: "single_line",
13
    parameters: { heading: false },
14
    addons: [{ id: "1234", field_extension: "lorem_ipsum", parameters: {} }],
15
  },
16
  deep_filtering_enabled: true,
17
  item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" },
18
  fieldset: null,
19
}

Structured 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:

In this example:

first we create some block models using the client.itemTypes.create() method, making sure to set the modular_block attribute to true — this tells the API that they're in fact block models, and not regular models;
we then create the Structured Text field, passing down the embeddable block models in the structured_text_blocks validator, and the linkable record models in the structured_text_links validator:

1
import { buildClient } from "@datocms/cma-client-node";
2

3
async function run() {
4
  // Make sure the API token has access to the CMA, and is stored securely
5
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
6

7
  const modularBlock1 = await client.itemTypes.create({
8
    name: "Modular Block 1",
9
    api_key: "modular_block1",
10
    modular_block: true,
11
  });
12

13
  const modularBlock2 = await client.itemTypes.create({
14
    name: "Modular Block 2",
15
    api_key: "modular_block2",
16
    modular_block: true,
17
  });
18

19
  const itemTypeId = "1234";
20

21
  const field = await client.fields.create(itemTypeId, {
22
    label: "Structured content",
23
    field_type: "structured_text",
24
    api_key: "content",
25
    validators: {
26
      structured_text_blocks: {
27
        item_types: [modularBlock1.id, modularBlock2.id],
28
      },
29
      structured_text_links: {
30
        item_types: [itemTypeId],
31
      },
32
    },
33
  });
34

35
  console.log(field);
36
}
37

38
run();

1
{
2
  id: "Pkg-oztERp6o-Rj76nYKJg",
3
  label: "Title",
4
  field_type: "string",
5
  api_key: "title",
6
  localized: true,
7
  validators: { required: {} },
8
  position: 1,
9
  hint: "This field will be used as post title",
10
  default_value: { en: "A default value", it: "Un valore di default" },
11
  appearance: {
12
    editor: "single_line",
13
    parameters: { heading: false },
14
    addons: [{ id: "1234", field_extension: "lorem_ipsum", parameters: {} }],
15
  },
16
  deep_filtering_enabled: true,
17
  item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" },
18
  fieldset: null,
19
}

Did this doc help you?

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.