Choose your language:
    Create a new field

    DatoCMS offers a number of different fields that you can combine togheter to create a Model.

    Different field types require different settings

    When creating a new field, you have to pay attention to two particular properties, validators and appearance.

    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
    PropertyValue
    field_typestring
    Possible values for editorsingle_line
    Available validatorsrequired, unique, length, format, enum
    Multi-line text
    PropertyValue
    field_typetext
    Possible values for editormarkdown, wysiwyg, textarea
    Available validatorsrequired, length, format
    Boolean
    PropertyValue
    field_typeboolean
    Possible values for editorboolean
    Available validatorsno validators available
    Integer
    PropertyValue
    field_typeinteger
    Possible values for editorinteger
    Available validatorsrequired, number_range
    Float
    PropertyValue
    field_typefloat
    Possible values for editorfloat
    Available validatorsrequired, number_range
    Date
    PropertyValue
    field_typedate
    Possible values for editordate_picker
    Available validatorsrequired, date_range
    Date time
    PropertyValue
    field_typedate_time
    Possible values for editordate_time_picker
    Available validatorsrequired, date_time_range
    Color
    PropertyValue
    field_typecolor
    Possible values for editorcolor_picker
    Available validatorsrequired
    JSON
    PropertyValue
    field_typejson
    Possible values for editorjson
    Available validatorsrequired
    Location
    PropertyValue
    field_typelat_lon
    Possible values for editormap
    Available validatorsrequired
    SEO
    PropertyValue
    field_typeseo
    Possible values for editorseo
    Available validatorsrequired_seo_fields, file_size, image_dimensions, title_length, description_length
    Slug
    PropertyValue
    field_typeslug
    Possible values for editorslug
    Required validatorsslug_title_field
    Other validators availablerequired, length, slug_format
    External video
    PropertyValue
    field_typevideo
    Possible values for editorvideo
    Available validatorsrequired
    Single-asset
    PropertyValue
    field_typefile
    Possible values for editorfile
    Available validatorsrequired, file_size, image_dimensions, extension, required_alt_title
    Asset gallery
    PropertyValue
    field_typegallery
    Possible values for editorgallery
    Available validatorssize, file_size, image_dimensions, extension, required_alt_title
    Single link
    PropertyValue
    field_typelink
    Possible values for editorlink_select, link_embed
    Default editorlink_select
    Required validatorsitem_item_type
    Other validators availablerequired, unique
    Multiple links
    PropertyValue
    field_typelinks
    Possible values for editorlinks_select, links_embed
    Default editorlinks_select
    Required validatorsitems_item_type
    Other validators availablesize
    Modular content
    PropertyValue
    field_typerich_text
    Possible values for editorrich_text
    Required validatorsrich_text_blocks
    Other validators availablesize
    Structured text
    PropertyValue
    field_typestructured_text
    Possible values for editorstructured_text
    Required validatorsstructured_text_blocks, structured_text_links
    Other validators availablelength

    Validators

    date_range

    Accept dates only inside a specified date range.

    ParameterTypeRequiredDescription
    minISO 8601 dateMinimum date
    maxISO 8601 dateMaximum date

    At least one of the parameters must be specified.

    date_time_range

    Accept date times only inside a specified date range.

    ParameterTypeRequiredDescription
    minISO 8601 datetimeMinimum datetime
    maxISO 8601 datetimeMaximum datetime

    At least one of the parameters must be specified.

    enum

    Only accept a specific set of values

    ParameterTypeRequiredDescription
    valuesArray<String>Set of allowed values
    extension

    Only accept assets with specific file extensions.

    ParameterTypeRequiredDescription
    extensionsArray<String>Set of allowed file extensions
    predefined_listone 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.

    ParameterTypeRequiredDescription
    min_valueIntegerNumeric value for minimum filesize
    min_unitone of "B", "KB", "MB"Unit for minimum filesize
    max_valueIntegerNumeric value for maximum filesize
    max_unitone 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.

    ParameterTypeRequiredDescription
    custom_patternRegexpRegular expression to be validated
    predefined_patternone of "email", "url"Allowed format

    Only one of the parameters must be specified.

    slug_format

    Only accept slugs having a specific format.

    ParameterTypeRequiredDescription
    custom_patternRegexpRegular 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.

    ParameterTypeRequiredDescription
    width_min_valueIntegerNumeric value for minimum width
    width_max_valueIntegerNumeric value for maximum height
    height_min_valueIntegerNumeric value for minimum width
    height_max_valueIntegerNumeric value for maximum height

    At least one parameter must be specified.

    item_item_type

    Only accept references to records of the specified models.

    ParameterTypeRequiredDescription
    item_typesArray<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.

    ParameterTypeRequiredDescription
    item_typesArray<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.

    ParameterTypeRequiredDescription
    minIntegerMinimum length
    eqIntegerExpected length
    maxIntegerMaximum length

    At least one parameter must be specified.

    number_range

    Accept numbers only inside a specified range.

    ParameterTypeRequiredDescription
    minFloatMinimum value
    maxFloatMaximum 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.

    ParameterTypeRequiredDescription
    titleBooleanWhether the title for the asset must be specified
    altBooleanWhether 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.

    ParameterTypeRequiredDescription
    titleBooleanWhether the meta title must be specified
    descriptionBooleanWhether the meta description must be specified
    imageBooleanWhether the social sharing image must be specified
    twitter_cardBooleanWhether 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.

    ParameterTypeRequiredDescription
    minIntegerMinimum value
    maxIntegerMaximum 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.

    ParameterTypeRequiredDescription
    minIntegerMinimum value
    maxIntegerMaximum value

    At least one of the parameters must be specified.

    rich_text_blocks

    Only accept references to block records of the specified block models.

    ParameterTypeRequiredDescription
    item_typesArray<Block Model ID>Set of allowed Block Model IDs
    structured_text_blocks

    Only accept references to block records of the specified block models.

    ParameterTypeRequiredDescription
    item_typesArray<Block Model ID>Set of allowed Block Model IDs
    structured_text_links

    Only accept itemLink to inlineItem nodes for records of the specified models.

    ParameterTypeRequiredDescription
    item_typesArray<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.

    ParameterTypeRequiredDescription
    minIntegerMinimum length
    eqIntegerExpected length
    maxIntegerMaximum length
    multiple_ofIntegerThe 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

    ParameterTypeRequiredDescription
    title_field_idField IDThe 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.

    single_line

    Simple textual input for Single-line string fields.

    ParameterTypeRequiredDescription
    headingBooleanIndicates if the field should be shown bigger, as a field representing a heading
    markdown

    Markdown editor for Multiple-paragraph text fields.

    ParameterTypeRequiredDescription
    toolbarArray<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.

    ParameterTypeRequiredDescription
    toolbarArray<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.

    ParameterTypeRequiredDescription
    enable_alphaBooleanShould the color picker allow to specify the alpha value?
    preset_colorsArray<Hex color string>List of preset colors to offer to the user
    slug

    Built-in editor for Slug fields.

    ParameterTypeRequiredDescription
    url_prefixStringA 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.

    ParameterTypeRequiredDescription
    start_collapsedBooleanWhether you want block records collapsed by default or not
    structured_text

    Built-in editor for Structured text fields.

    ParameterTypeRequiredDescription
    nodesArray<String>Specify which nodes the field should allow. Valid values: "blockquote", "code", "heading", "link", "list", "thematicBreak"
    marksArray<String>Specify which marks the field should allow. Valid values: "strong", "emphasis", "underline", "strikethrough", "code", "highlight"
    blocks_start_collapsedBooleanWhether you want block nodes collapsed by default or not
    show_links_target_blankBooleanWhether 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_editorBooleanWhether 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.

    Examples

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