Custom fields

Custom fields let a tenant add validated attributes without changing the ICAP schema. Define the field once, then supply its value in an entity's extensionFields object.

Supported resources

Custom field definitions currently apply to these entity types only:

Definitions are isolated to a tenant and entity type. The same key may be defined separately for different entity types.

Define before using

Create an extension field definition with a stable key, a human-readable label, data type, entity type, requiredness, and optional validation constraints.

Supported data types are text, integer, decimal, boolean, date, and dateTime.

{
  "key": "costCenter",
  "label": "Cost center",
  "dataType": "text",
  "entityType": "identity",
  "required": true,
  "pattern": "^[A-Z]{2}-[0-9]{4}$"
}

Data types and value formats

Custom-field values must be scalar JSON values; arrays and objects are not supported. Use the JSON type and format that correspond to the definition's dataType.

Use UTC (Z) for dateTime values where practical. When a date or dateTime definition has a min or max, ICAP parses and validates the supplied value as a date/time. Without either bound, the current validator accepts any string for these two data types; sending ISO 8601 values remains the interoperable choice.

For example, these values use the expected formats:

{
  "extensionFields": {
    "validFromDate": "2026-09-09",
    "appointmentAt": "2026-09-09T14:30:00Z"
  }
}

Optional validation constraints

Add constraints to a definition only when the selected data type supports them. Omit an optional constraint, or set it to null, when it should not be applied.

For temporal fields, min and max are relative offsets, not fixed dates. For example, "min": 0 requires a value no earlier than validation time, while "max": 86400 allows a value up to 24 hours later. ICAP does not currently enforce that min is less than or equal to max, so configure compatible bounds.

Set the extended-entity value

After creating the definition, set values using extensionFields on a create request or with JSON Patch on an existing record:

[
  { "op": "add", "path": "/extensionFields/costCenter", "value": "CZ-1042" }
]

Unknown keys, missing required values, or values with the wrong JSON type are rejected. Constraints are checked when an entity is created or updated.

Change definitions carefully

Definitions govern validation when an entity is created or updated. Changing a definition does not migrate values already stored on entities.

• Before making a field required, populate a valid value on every affected record. Later updates must satisfy the current definition.

• To retire a required field, first update its definition to required: false. Then remove the field's value from every affected record. Finally, delete the definition using its current version. Deleting a definition does not remove stored values; values left under an undefined key can cause later updates to fail.

• The definition's key, dataType, and entityType are immutable. Create a new definition and migrate values when one of these must change.

Definition removal physically removes the definition. There is no restore operation.

Manage definitions through /extensionFieldDefinition; its updates and removal require If-Match. See concurrency and the API contract.