# 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"` Show enum values 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: {} }], }` Show object format 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 Show objects format inside array 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: `1` 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"\>](https://www.datocms.com/docs/content-management-api/resources/fieldset.md) Show deprecated appeareance object Deprecated Field appearance This field contains a typo and will be removed in future versions: use `appearance` instead Show object format editor string Required parameters object Required ## Returns Returns a resource object of type [field](https://www.datocms.com/docs/content-management-api/resources/field.md) ## Other examples Example Basic example This is a complete example for creating a new localized *Single-line string* field: ###### Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const modelIdOrApiKey = "blog_post"; const field = await client.fields.create(modelIdOrApiKey, { label: "Title", field_type: "string", api_key: "title", }); // Check the 'Returned output' tab for the result ☝️ console.log(field); } run(); ``` ###### Returned output ```javascript { id: "Pkg-oztERp6o-Rj76nYKJg", label: "Title", field_type: "string", api_key: "title", localized: true, validators: { required: {} }, position: 1, hint: "This field will be used as post title", default_value: { en: "A default value", it: "Un valore di default" }, appearance: { editor: "single_line", parameters: { heading: false }, addons: [{ id: "1234", field_extension: "lorem_ipsum", parameters: {} }], }, deep_filtering_enabled: true, item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" }, fieldset: null, } ``` Example Creating Modular Content fields In this example: - first we create some [block models](https://www.datocms.com/docs/content-modelling/blocks.md) 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](https://www.datocms.com/docs/content-modelling/modular-content.md) field, passing down the allowed block models in the `rich_text_blocks` validator: ###### Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { // Make sure the API token has access to the CMA, and is stored securely const client = buildClient({ apiToken: process.env.DATOCMS_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 field = await client.fields.create("UZyfjdBES8y2W2ruMEHSoA", { label: "Content", field_type: "rich_text", api_key: "content", validators: { rich_text_blocks: { item_types: [modularBlock1.id, modularBlock2.id], }, }, }); console.log(field); } run(); ``` ###### Returned output ```javascript { id: "Pkg-oztERp6o-Rj76nYKJg", label: "Title", field_type: "string", api_key: "title", localized: true, validators: { required: {} }, position: 1, hint: "This field will be used as post title", default_value: { en: "A default value", it: "Un valore di default" }, appearance: { editor: "single_line", parameters: { heading: false }, addons: [{ id: "1234", field_extension: "lorem_ipsum", parameters: {} }], }, deep_filtering_enabled: true, item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" }, fieldset: null, } ``` Example Creating Structured Text fields [Structured Text](https://www.datocms.com/docs/content-modelling/structured-text.md) 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](https://www.datocms.com/docs/content-modelling/blocks.md) 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: ###### Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { // Make sure the API token has access to the CMA, and is stored securely const client = buildClient({ apiToken: process.env.DATOCMS_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 field = await client.fields.create("UZyfjdBES8y2W2ruMEHSoA", { label: "Structured content", field_type: "structured_text", api_key: "content", validators: { structured_text_blocks: { item_types: [modularBlock1.id, modularBlock2.id], }, structured_text_inline_blocks: { item_types: [modularBlock1.id], }, structured_text_links: { item_types: ["UZyfjdBES8y2W2ruMEHSoA"], }, }, }); console.log(field); } run(); ``` ###### Returned output ```javascript { id: "Pkg-oztERp6o-Rj76nYKJg", label: "Title", field_type: "string", api_key: "title", localized: true, validators: { required: {} }, position: 1, hint: "This field will be used as post title", default_value: { en: "A default value", it: "Un valore di default" }, appearance: { editor: "single_line", parameters: { heading: false }, addons: [{ id: "1234", field_extension: "lorem_ipsum", parameters: {} }], }, deep_filtering_enabled: true, item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" }, fieldset: null, } ``` ## Related content in "Content Management API" - [Content Management API Overview](https://www.datocms.com/docs/content-management-api.md) - [Using the JavaScript CMA client](https://www.datocms.com/docs/content-management-api/using-the-nodejs-clients.md) - [API versioning](https://www.datocms.com/docs/content-management-api/api-versioning.md) - [Authentication](https://www.datocms.com/docs/content-management-api/authentication.md) - [Environments](https://www.datocms.com/docs/content-management-api/setting-the-environment.md) - [Error codes & handling failures (CMA)](https://www.datocms.com/docs/content-management-api/errors.md) - [Pagination](https://www.datocms.com/docs/content-management-api/pagination.md) - [Asynchronous jobs](https://www.datocms.com/docs/content-management-api/async-jobs.md) - [Technical Limits (CMA)](https://www.datocms.com/docs/content-management-api/technical-limits.md) - [Record](https://www.datocms.com/docs/content-management-api/resources/item.md) - [Scheduled publication](https://www.datocms.com/docs/content-management-api/resources/scheduled-publication.md) - [Scheduled unpublishing](https://www.datocms.com/docs/content-management-api/resources/scheduled-unpublishing.md) - [Upload](https://www.datocms.com/docs/content-management-api/resources/upload.md) - [Site](https://www.datocms.com/docs/content-management-api/resources/site.md) - [Model/Block model](https://www.datocms.com/docs/content-management-api/resources/item-type.md) - [Field](https://www.datocms.com/docs/content-management-api/resources/field.md) - [Create a new field](https://www.datocms.com/docs/content-management-api/resources/field/create.md) - [Update a field](https://www.datocms.com/docs/content-management-api/resources/field/update.md) - [List all fields of a model/block](https://www.datocms.com/docs/content-management-api/resources/field/instances.md) - [List fields referencing a model/block](https://www.datocms.com/docs/content-management-api/resources/field/referencing.md) - [Retrieve a field](https://www.datocms.com/docs/content-management-api/resources/field/self.md) - [Delete a field](https://www.datocms.com/docs/content-management-api/resources/field/destroy.md) - [Duplicate a field](https://www.datocms.com/docs/content-management-api/resources/field/duplicate.md) - [Fieldset](https://www.datocms.com/docs/content-management-api/resources/fieldset.md) - [Record version](https://www.datocms.com/docs/content-management-api/resources/item-version.md) - [Upload permission](https://www.datocms.com/docs/content-management-api/resources/upload-request.md) - [Upload track](https://www.datocms.com/docs/content-management-api/resources/upload-track.md) - [Manual tags](https://www.datocms.com/docs/content-management-api/resources/upload-tag.md) - [Smart tags](https://www.datocms.com/docs/content-management-api/resources/upload-smart-tag.md) - [Upload Collection](https://www.datocms.com/docs/content-management-api/resources/upload-collection.md) - [Search Index](https://www.datocms.com/docs/content-management-api/resources/search-index.md) - [Search result](https://www.datocms.com/docs/content-management-api/resources/search-result.md) - [Search indexing activity](https://www.datocms.com/docs/content-management-api/resources/search-index-event.md) - [Environment](https://www.datocms.com/docs/content-management-api/resources/environment.md) - [Maintenance mode](https://www.datocms.com/docs/content-management-api/resources/maintenance-mode.md) - [Menu Item](https://www.datocms.com/docs/content-management-api/resources/menu-item.md) - [Schema Menu Item](https://www.datocms.com/docs/content-management-api/resources/schema-menu-item.md) - [Uploads filter](https://www.datocms.com/docs/content-management-api/resources/upload-filter.md) - [Model filter](https://www.datocms.com/docs/content-management-api/resources/item-type-filter.md) - [Plugin](https://www.datocms.com/docs/content-management-api/resources/plugin.md) - [Workflow](https://www.datocms.com/docs/content-management-api/resources/workflow.md) - [Asynchronous job](https://www.datocms.com/docs/content-management-api/resources/job.md) - [Job result](https://www.datocms.com/docs/content-management-api/resources/job-result.md) - [Account](https://www.datocms.com/docs/content-management-api/resources/account.md) - [Organization](https://www.datocms.com/docs/content-management-api/resources/organization.md) - [Invitation](https://www.datocms.com/docs/content-management-api/resources/site-invitation.md) - [Collaborator](https://www.datocms.com/docs/content-management-api/resources/user.md) - [Role](https://www.datocms.com/docs/content-management-api/resources/role.md) - [API token](https://www.datocms.com/docs/content-management-api/resources/access-token.md) - [Webhook](https://www.datocms.com/docs/content-management-api/resources/webhook.md) - [Webhook call](https://www.datocms.com/docs/content-management-api/resources/webhook-call.md) - [Build trigger](https://www.datocms.com/docs/content-management-api/resources/build-trigger.md) - [Deploy activity](https://www.datocms.com/docs/content-management-api/resources/build-event.md) - [Subscription limit](https://www.datocms.com/docs/content-management-api/resources/subscription-limit.md) - [Subscription feature](https://www.datocms.com/docs/content-management-api/resources/subscription-feature.md) - [SSO Settings](https://www.datocms.com/docs/content-management-api/resources/sso-settings.md) - [SSO User](https://www.datocms.com/docs/content-management-api/resources/sso-user.md) - [SSO Group](https://www.datocms.com/docs/content-management-api/resources/sso-group.md) - [White-label settings](https://www.datocms.com/docs/content-management-api/resources/white-label-settings.md) - [Audit log event](https://www.datocms.com/docs/content-management-api/resources/audit-log-event.md)