Custom Field Definitions

Tenant catalog of user-defined custom fields (which fields exist per feature, their type, validation and presentation). Values travel in each entity's customFields list.

📄️ Get custom field definition by ID

Returns a single definition by its primary key (enabled or not). The response carries a strong `ETag` header with the current version. For EAV-backed featureTypes (product-models, product-variants, manufacturing-custom-fields) the `featureType` query parameter is required to select the ges_customfield id namespace; no ETag is emitted for them.

📄️ Update custom field definition

Full replacement of an existing definition. `featureType` and `dataType` are immutable (stored values keyed by the id would stop matching); renaming `apiName`/`label` is always safe. `options` is rejected here: manage options through the `/options` sub-resource. Send the `If-Match` header with the current ETag for optimistic concurrency control. For EAV-backed featureTypes pass the `featureType` query parameter (If-Match is ignored for them).

📄️ Delete custom field definition

Deletes a definition. Stored JSON values keyed by this id are left in place and ignored by readers (prefer disabling via `enabled=false` when the data should stay recoverable). Send the `If-Match` header with the current ETag for optimistic concurrency control.

📄️ Merge-patch custom field definition

RFC 7396 merge-patch over `application/merge-patch+json`. Send only the fields you want to change; include a field with value `null` to remove it. Use the `If-Match` header for optimistic concurrency control.

📄️ Get option by ID

Returns a single option (enabled or not). The response carries a strong `ETag` header with the current version.

📄️ Update option

Full replacement (value, displayOrder, enabled). Renaming `value` does NOT rewrite previously stored entity values (they keep the old label and stop matching any option); prefer disabling the old option and creating a new one when the meaning changes. Send the `If-Match` header with the current ETag for optimistic concurrency control.

📄️ Delete option

Deletes an option. Previously stored entity values with this label are left in place (readable but no longer writable); prefer disabling via `enabled=false` when the data should stay consistent. Send the `If-Match` header with the current ETag for optimistic concurrency control.

📄️ List custom field definitions

Returns a paginated list of custom field definitions with envelope `{data, totalCount, skip, limit, hasMore}`. Optional `featureType` filter: JSON-backed (customers, optometry-exams, audiology-exams, contactology-fittings, contact-lens-exams) or EAV-backed bridge (product-models, product-variants, manufacturing-custom-fields; scoped to the caller's companies). Disabled definitions are hidden unless `includeDisabled=true`. Fixed ordering: featureType, displayOrder, apiName.

📄️ Create custom field definition

Creates a new custom field definition for the given `featureType`. The `apiName` must be unique within the featureType. For `dataType=ENUM` the `options` array is accepted as an optional creation seed (each label becomes an option row); afterwards options are managed through the paginated `/options` sub-resource. EAV-backed featureTypes (product-models, product-variants, manufacturing-custom-fields) accept dataType COLOR, an optional `companyId` (defaults to the caller's current company) and store into ges_customfield until the ADR-003 Fase 3 migration. Business logic runs in the legacy WAR via the internal commands gateway.

📄️ List options of a custom field definition

Returns a paginated page of the definition's options with envelope `{data, totalCount, skip, limit, hasMore}`, ordered by displayOrder then value. `search` filters by case-insensitive containment on the value ÔÇö use it for autocomplete over large catalogs instead of fetching everything. Disabled options are hidden unless `includeDisabled=true`.

📄️ Create option

Adds one option to a dataType=ENUM (or COLOR for EAV-backed featureTypes) definition. The `value` must be unique within the definition (it is what entity writes store). `hex` is only accepted for COLOR definitions. Business logic runs in the legacy WAR via the internal commands gateway.

📄️ Bulk create options

Adds up to 1000 options in one request (all-or-nothing: any invalid or duplicate entry rolls back the whole batch). Intended for imports of large catalogs; send multiple batches for bigger volumes.