Custom Fields
Define, validate, display, query, and automate typed custom data on Signals entities.
Overview
Custom fields add tenant-defined data without changing an entity's database table. Definitions live in custom_fields; values use typed columns in the custom_field_values EAV table. REST and MCP expose those values as a flat custom_fields object, so callers never need to understand EAV storage.
The registered modules are: Account, Vehicle, Facility, Equipment Test, CatalogueItem, CatalogueItemGroup, Repair, StockCheck, WarehouseTransfer, Asset, Activity, Warehouse, Rental, RentalLine, Invoice, Address, ApprovalChainDefinition, CreditNote, Document, EquipmentTestResult, InvoicePayment, PurchaseOrder, RentalProject, Report, Service, and Workflow.
Manage definitions in Studio
Open Admin → Data → Custom Fields at /admin/settings/custom-fields. Choose an entity in the left rail, then create or select a field. Studio protects unsaved edits when moving between fields or entities and shows validation errors beside the responsible control.
Each definition controls:
| Setting | Contract |
|---|---|
| Display name | Human-readable label on forms and detail views. |
| Key | Flat API/MCP key. Must start with a lowercase letter, contain only lowercase letters, numbers, and underscores, and not collide with a core schema field. |
| Module | Registered entity type. It cannot change after creation. |
| Field type | Typed editor, validation, storage, filtering, and sorting behavior. It is locked once a value row has existed. |
| Group | Optional visual section. Drag fields in the rail to reorder them atomically. |
| List | Required for Lists and MultiLists; forbidden for other types. |
| Required/default | Server-enforced on create. Conditional required rules may depend on another core or custom schema field. Defaults are type-validated. |
| Visibility | Conditional rules plus role visibility. Both UI and server write boundaries enforce them. |
| Placement | create, edit, detail, and quick independently control where a field is available. |
| Searchable | Enables documented custom_fields. filters and supported EAV sorting for the field. |
| Active | Inactive definitions disappear from active forms, schema, filters, and agent value tools without deleting stored data. |
The role selector is populated from the actual role registry. Rule fields are selected from the resolved module schema rather than entered as unchecked text.
Field types
The API and MCP use lowercase snake_case values for field_type (for example string, date_time, and multi_lists). Integer codes and PascalCase spellings are rejected. Responses also include the display name in field_type_label.
| API value | Editor and public value | EAV storage |
|---|---|---|
string |
Single-line string | value_string |
text |
Multi-line plain text | value_text |
number |
Decimal number | value_decimal |
boolean |
Boolean checkbox | value_boolean |
date_time |
ISO date and time | value_datetime |
date |
ISO date | value_date |
time |
Time | value_time |
email |
Valid email address | value_string |
website |
Valid URL | value_string |
lists |
One option; API/MCP read the option label | value_integer list-entry ID |
multi_lists |
Option labels array | value_json list-entry IDs |
auto_number |
Read-only generated value | value_string |
currency |
Decimal monetary value | value_decimal |
telephone |
Telephone string | value_string |
file_image |
Uploaded file/image metadata | value_json |
rich_text |
Markdown-formatted text | value_text |
json_key_value |
JSON object | value_json |
colour |
Colour value | value_string |
percentage |
Decimal percentage | value_decimal |
FileImage values are stored through the attachment service. EAV contains safe metadata (attachment_id, UUID, original name, MIME type, and size), not a filesystem path. Replacing or clearing the field deletes the preceding attachment. Caller-supplied attachment metadata is rejected unless it is the entity's existing value.
AutoNumber settings contain optional prefix and suffix, a pad_width from 1–20, and a positive starting_value. The number is assigned once on entity creation. Changing formatting never rewinds the persisted sequence or reuses issued values.
Groups and lifecycle safety
Groups are managed at /admin/settings/custom-field-groups. Deletion is blocked while any field remains assigned. Moving a field to a group or explicitly to no group uses patch semantics: an omitted group leaves it unchanged; null removes the assignment.
Studio shows the count of entities with non-empty values. A definition can be deleted only when that count is zero. If it has populated values, deactivate it instead. Deactivation preserves the definition and EAV history. A type remains locked after any value row has existed, even if its value was later cleared.
REST API
Definitions use /api/v1/custom_fields. Prefer a semantic type name:
{
"name": "po_reference",
"display_name": "PO reference",
"module_type": "Rental",
"field_type": "string",
"is_searchable": true
}
Entity create/update endpoints accept the following custom_fields request fragment. Success responses return the field map at data.custom_fields within the resource:
{
"custom_fields": {
"po_reference": "PO-12345",
"service_level": "Gold",
"delivery_flags": ["Tail lift", "Timed slot"]
}
}
Unknown, hidden, misplaced, invalid, or conditionally required values return HTTP 422. AutoNumber is generated by the server. List inputs accept public labels or valid list-entry IDs; responses return labels.
Filtering and sorting
Filter with ?filter[field][operator]=value:
?filter[custom_fields.po_reference][contains]=PO-
?filter[custom_fields.credit_score][gte]=700
?filter[custom_fields.service_level][eq]=Gold
?filter[custom_fields.delivery_flags][contains]=Tail%20lift
The schema advertises operators supported by each field type. Unary null, not_null, present, and blank require true (HTTP also accepts 1). An absent EAV row satisfies null and blank; JSON null and empty objects/arrays have field-specific presence rules. Invalid, unknown, non-searchable, or unsupported filters return a coded 422; see API Conventions.
Sort a supported searchable field with ?sort=custom_fields.po_reference or ?sort=-custom_fields.po_reference. Missing values sort last in both directions. Unsupported sorts are reported in meta.ignored_sorts. MultiLists, FileImage, and JsonKeyValue are not sortable.
MCP
Use describe-custom-field-schema before writing values. It reports active keys, semantic types, required and visibility rules, role/placement availability, list choices, filter operators, and sortability.
Definition workflow:
list-custom-field-groupsorcreate-custom-field-groupwhen grouping is needed.create-custom-fieldwithfield_type=string(or another API value).get-custom-field/update-custom-fieldfor inspection and patching.deactivate-custom-fieldrather than deleting a used definition;reactivate-custom-fieldrestores it.
Value workflow:
describe-custom-field-schemafor the module.get-entity-custom-fieldsfor current values.set-entity-custom-field-valueswith only the keys to patch.
The tools call the same guarded action and validator paths as REST and browser forms. They require custom-fields:read or custom-fields:write token abilities and the corresponding user permissions.
Schema and integration guidance
The module schema registry merges active custom definitions with core fields. A custom key can never overwrite a core schema key. Schema metadata is the source of truth for type, filter operator, sort, list binding (option_list_id), validation, visibility, roles, and placements.
Plugins and external apps should discover definitions rather than cache them indefinitely. Re-read the schema after administrators create, reorder, deactivate, or change a definition. See the machine-readable OpenAPI document at /docs/api.json and the agent guide in SKILL.md.
At a glance
Define custom data fields that extend entities with additional information. Fields can be filtered by module type.
| Action | Description |
|---|---|
| Create | Define a new custom field with type, module, group, and validation |
| Edit | Update field configuration |
| Delete | Remove a field definition |