--- type: api title: Update a field definition description: **Spaces method and path for this operation:** url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/kibana-serverless/operation/operation-updatecasefielddefinitiondefaultspace resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/kibana-serverless/operation/operation-updatecasefielddefinitiondefaultspace products: - Kibana --- # Update a field definition Availability: - Server: `https://{kibana_url}` ## Paths - `PUT` `/api/cases/field_definitions/{field_definition_id}` - `PUT` `/s/{space_id}/api/cases/field_definitions/{field_definition_id}` - [Api key auth](/elastic/docs-builder/docs/4371/api/doc/kibana-serverless/authentication#apikeyauth) #### Path Parameters - `field_definition_id` (string · max: 36) The identifier for the field definition. ## Description Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information. Updates editable attributes of a field definition. Server-managed attributes (`displayOrder`, `legacyKey`) are preserved. You must have the "Manage templates" sub-privilege for the Cases feature of the owning solution. A field's `name` and YAML `type` are immutable after creation — an attempt to change either returns `409` with `attributes.code = "field_identity_immutable"` and `attributes.changed` listing which identity attributes were modified. Setting `isGlobal` to `false` when the field is linked to an active custom field in the Cases configuration returns `409`; otherwise demotion is allowed. Requires the Cases feature to be enabled in the space. Use `dry_run=true` to validate the request without writing anything. ## Query String Parameters - `dry_run` (boolean · default: false) When true, runs authorization, body, and identity-immutability validation without updating the field definition. Returns `{ "valid": true }` on success. ## Request Body `application/json` - `definition` (string · max: 1000000) — required The field definition as a YAML string describing a single field (type, label, control, metadata). - `description` (string · max: 1000) — optional Optional human-readable description of the field's purpose. - `isGlobal` (boolean) — optional When true, this field is rendered in every case for this owner, regardless of the template used. Global fields cannot be demoted (set to false) while they are linked to an active custom field in the Cases configuration. - `name` (string · min: 1 · max: 1000) — optional The field name, unique per owner (case-insensitive). Must match the `name` key inside the YAML definition. When omitted, the name is extracted from the definition YAML automatically. Immutable after creation. Unlike POST, the 50-character limit is not enforced on PUT so that definitions with legacy names that exceed the limit remain modifiable. - `owner` (string · min: 1 · max: 30) — required The application that owns this field definition. ## Responses #### `200` Indicates a successful call. Returns the updated field definition, or `{ "valid": true }` when `dry_run=true`. `application/json` One of: - **Cases_field_definition_response** A field definition from the field library. The `legacyKey` attribute, which is a server-managed link to a migrated custom field, is not included in the public API response. - `definition` (string) The field definition as a YAML string. New definitions are limited to 30 000 characters, but existing definitions created via internal tooling may be longer. - `description` (string) Optional human-readable description of the field's purpose. - `displayOrder` (integer · min: 0) Position of a global field in the case details view. Assigned by the server and changed via the Field Library reorder controls. - `fieldDefinitionId` (string · max: 36) Unique server-assigned identifier for the field definition (UUID). May be UUIDv4 for definitions created through the public API, or UUIDv5 for definitions created by internal migration processes. - `isGlobal` (boolean) When true, this field is rendered in every case regardless of which template the case uses. - `name` (string) The field name. Must match the `name` property in the YAML definition and is unique per owner (case-insensitive). Immutable after creation. - `owner` (string · max: 50) The application that owns this field definition. - **{ valid }** - `valid` (boolean) #### `400` The request body is invalid, the YAML definition is malformed, the `name` does not match the YAML definition's `name`, or the owner would be changed. `application/json` - `error` (string) - `message` (string) - `statusCode` (integer) #### `401` Authorization information is missing or invalid. `application/json` - `error` (string) - `message` (string) - `statusCode` (integer) #### `403` The user does not have the manage templates privilege for the owner. `application/json` - `error` (string) - `message` (string) - `statusCode` (integer) #### `404` The field definition was not found. `application/json` - `error` (string) - `message` (string) - `statusCode` (integer) #### `409` A field's name or type cannot be changed after creation, or a global field cannot be demoted while linked to an active custom field. `application/json` Any of: - **{ attributes, error, message, … }** Identity-immutable conflict — name or type was changed. - `attributes` (object) - `changed` ([] string) - `code` (enum) Values: `field_identity_immutable` - `error` (string) - `message` (string) - `statusCode` (integer) - **Cases_response_4xx** - `error` (string) - `message` (string) - `statusCode` (integer) ## Code Examples #### Console ```console PUT /api/cases/field_definitions/{field_definition_id} { "definition": "name: priority\nlabel: Priority\ntype: keyword\ncontrol: SELECT_BASIC\nmetadata:\n options: [low, medium, high]\n default: medium\n", "description": "Ticket priority level.", "isGlobal": false, "name": "priority", "owner": "cases" } ``` #### curl ```curl curl -X PUT "https://{kibana_url}/api/cases/field_definitions/{field_definition_id}" \ -H "Content-Type: application/json" \ -d '{ "definition": "name: priority\nlabel: Priority\ntype: keyword\ncontrol: SELECT_BASIC\nmetadata:\n options: [low, medium, high]\n default: medium\n", "description": "Ticket priority level.", "isGlobal": false, "name": "priority", "owner": "cases" }' ``` ## Response Examples #### A reusable field definition. ```json { "definition": "name: priority\nlabel: Priority\ntype: keyword\ncontrol: SELECT_BASIC\nmetadata:\n options: [low, medium, high]\n default: medium\n", "description": "Ticket priority level.", "fieldDefinitionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "isGlobal": false, "name": "priority", "owner": "cases" } ``` #### The request is invalid. ```json { "error": "Bad Request", "message": "Template [invalid-template-id] not found for owner [cases]", "statusCode": 400 } ``` #### Authorization information is missing or invalid. ```json { "error": "Unauthorized", "message": "Unable to authenticate with the provided credentials.", "statusCode": 401 } ``` #### The user does not have access to the requested resource. ```json { "error": "Forbidden", "message": "Unauthorized to access cases", "statusCode": 403 } ``` #### The requested resource was not found. ```json { "error": "Not Found", "message": "Saved object [cases-template/9da1ea2a-09f8-4d0e-bf9d-09bf8c9d0f42] not found", "statusCode": 404 } ``` #### A resource conflict occurred. ```json { "error": "Conflict", "message": "Template name \u0022Security incident\u0022 already exists for owner \u0022cases\u0022", "statusCode": 409 } ```