Create a new field - Field - Content Management API

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

Field appearance details, plugin configuration and field add-ons

position Optional integer Example: 1

Ordering index

hint Optional string, null Example: "This field will be used as post title"

Field hint

default_value Optional boolean, null, string, number, object Example: {"en":"A default value","it":"Un valore di default"}

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

deep_filtering_enabled Optional boolean Example: true

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

fieldset Optional null, { type: "fieldset", id: fieldset.id }

Fieldset linkage

Returns

Returns a field resource object.

Examples

The following examples are available:

Basic example
Creating Modular Content fields
Creating Structured Text fields

Basic example

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

Example code:

import { buildClient } from '@datocms/cma-client-node';
async function run() {
  const client = buildClient({ apiToken: '<YOUR_API_TOKEN>' });
  
  const modelIdOrApiKey = 'blog_post';
  
  const field = await client.fields.create(modelIdOrApiKey, {
    id: 'Pkg-oztERp6o-Rj76nYKJg',
    label: 'Title',
    field_type: 'string',
    api_key: 'title',
    localized: true,
    validators: {
      required: {}
    },
    appearance: {
      editor: 'single_line',
      parameters: {
        heading: false
      },
      addons: [
        {
          id: '1234',
          field_extension: 'lorem_ipsum',
          parameters: {}
        }
      ]
    },
    position: 1,
    hint: 'This field will be used as post title',
    default_value: {
      en: 'A default value',
      it: 'Un valore di default'
    },
    deep_filtering_enabled: true,
    fieldset: null
  });
  
  console.log(field);
}
run();

Returned output:

{
  id: 'Pkg-oztERp6o-Rj76nYKJg',
  label: 'Title',
  field_type: 'string',
  localized: true,
  default_value: {
    en: 'A default value',
    it: 'Un valore di default'
  },
  api_key: 'title',
  hint: 'This field will be used as post title',
  validators: {
    required: {}
  },
  appearance: {
    editor: 'single_line',
    parameters: {
      heading: false
    },
    addons: [
      {
        id: '1234',
        field_extension: 'lorem_ipsum',
        parameters: {}
      }
    ]
  },
  position: 1,
  deep_filtering_enabled: true,
  item_type: {
    type: 'item_type',
    id: 'DxMaW10UQiCmZcuuA-IkkA'
  },
  fieldset: null
}

Creating Modular Content fields

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:

Example code:

import { buildClient } from '@datocms/cma-client-node';
async function run() {
  const client = buildClient({ apiToken: '<YOUR_API_TOKEN>' });
  const modularBlock1 = await client.itemTypes.create({
    name: 'Modular Block 1',
    api_key: 'modular_block1',
    modular_block: true,
  });
  const modularBlock2 = await client.itemTypes.create({
    name: 'Modular Block 2',
    api_key: 'modular_block2',
    modular_block: true,
  });
  const itemTypeId = '1234';
  const field = await client.fields.create(itemTypeId, {
    label: 'Content',
    field_type: 'rich_text',
    api_key: 'content',
    validators: {
      rich_text_blocks: {
        item_types: [modularBlock1.id, modularBlock2.id],
      },
    },
  });
  console.log(field);
}
run();

Creating Structured Text fields

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:

Example code:

import { buildClient } from '@datocms/cma-client-node';
async function run() {
  const client = buildClient({ apiToken: '<YOUR_API_TOKEN>' });
  const modularBlock1 = await client.itemTypes.create({
    name: 'Modular Block 1',
    api_key: 'modular_block1',
    modular_block: true,
  });
  const modularBlock2 = await client.itemTypes.create({
    name: 'Modular Block 2',
    api_key: 'modular_block2',
    modular_block: true,
  });
  const itemTypeId = '1234';
  const field = await client.fields.create(itemTypeId, {
    label: 'Structured content',
    field_type: 'structured_text',
    api_key: 'content',
    validators: {
      structured_text_blocks: {
        item_types: [modularBlock1.id, modularBlock2.id],
      },
      structured_text_links: {
        item_types: [itemTypeId],
      },
    },
  });
  console.log(field);
}
run();

Did this doc help you?

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