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

content_link_enabled boolean Optional

Whether Content Link (visual editing) encoding is emitted for this field's value in the Content Delivery API. Defaults to true; can only be set to false on string, text and structured_text fields

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
  content_link_enabled: true,
18
  item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" },
19
  fieldset: null,
20
}

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 field = await client.fields.create("UZyfjdBES8y2W2ruMEHSoA", {
20
    label: "Content",
21
    field_type: "rich_text",
22
    api_key: "content",
23
    validators: {
24
      rich_text_blocks: {
25
        item_types: [modularBlock1.id, modularBlock2.id],
26
      },
27
    },
28
  });
29

30
  console.log(field);
31
}
32

33
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
  content_link_enabled: true,
18
  item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" },
19
  fieldset: null,
20
}

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 and structured_text_inline_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 field = await client.fields.create("UZyfjdBES8y2W2ruMEHSoA", {
20
    label: "Structured content",
21
    field_type: "structured_text",
22
    api_key: "content",
23
    validators: {
24
      structured_text_blocks: {
25
        item_types: [modularBlock1.id, modularBlock2.id],
26
      },
27
      structured_text_inline_blocks: {
28
        item_types: [modularBlock1.id],
29
      },
30
      structured_text_links: {
31
        item_types: ["UZyfjdBES8y2W2ruMEHSoA"],
32
      },
33
    },
34
  });
35

36
  console.log(field);
37
}
38

39
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
  content_link_enabled: true,
18
  item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" },
19
  fieldset: null,
20
}