Show examples in:
    Create a new field

    Parameters

    id  string  Optional
    RFC 4122 UUID of field expressed in URL-safe base64 format
    label  Required  string  Example: "Title"

    The label of the field

    field_type  Required  enum  Example: "string"

    Type of input

    api_key  Required  string  Example: "title"

    Field API key

    localized  Optional  boolean  Example: true

    Whether the field needs to be multilanguage or not

    validators  Optional  object  Example: {"required":{}}

    Optional field validations

    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

    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();