ThinkLP
Guides

Field metadata

Every canonical retrieve, create, and update returns an envelope:

JSONCode
{ "detail": { "...": "the record itself" }, "fieldSpecs": [{ "...": "metadata for one field" }] }

fieldSpecs describes each field on the record so you can build a form dynamically. It carries the label, the type, whether a field is required or read-only, and the allowed values. You do not have to hard-code any of them. Every domain returns the same fieldSpec shape, so one rendering routine works across theft cases, vehicles, persons, items, and locations.

The fieldSpec shape

KeyTypeMeaning
namestringThe field's API name — the key to read/write in detail.
labelstringHuman-readable label for the field.
typestringField type (for example string, picklist, boolean, date, reference).
requiredbooleanWhether the field must be supplied on write.
readOnlyboolean | nullDo not offer the field for editing. Populated by theft and person.
createableboolean | nullThe field may be set on create. Populated by vehicle, item, and location.
updateableboolean | nullThe field may be set on update. Populated by vehicle, item, and location.
sectionstring | nullA grouping hint for laying the field out under a section heading.
referenceTostring | nullFor reference fields, the related object the value points to.
optionsarray | nullAllowed values for enumerated fields, each { "label", "value" }.
controlledOptionsarray | nullDependent-picklist option sets, keyed by the controlling field's value (see below).
controllingFieldNamestring | nullFor a dependent picklist, the name of the field that controls which options are valid.
layoutHintstring | nullAn optional rendering hint (for example a wide/full-width field).

Keys a domain does not use are null. A generic renderer should treat any null as "not applicable" rather than assuming a default.

Editability: theft and person express editability with readOnly. Vehicle, item, and location express it with createable and updateable. To decide whether to disable an input, treat the field as editable when readOnly is false or when updateable is true.

readOnly is a form hint, not the write rule — some fields accept a value on create and refuse a change afterwards. The reference states each field's rule.

Enumerated fields (options)

When type is picklist (or otherwise enumerated), options lists the allowed values. Render a select control from it:

JSONCode
{ "name": "investigationType", "label": "Investigation Type", "type": "picklist", "required": true, "options": [ { "label": "External Theft", "value": "External Theft" }, { "label": "Internal Theft", "value": "Internal Theft" } ] }

Use value as the value you send back in detail, and label as the text you show the user.

Dependent picklists (controlledOptions)

Some fields' valid values depend on another field. Those carry controllingFieldName, the name of the controlling field, and controlledOptions. controlledOptions holds one entry per controlling value. Each entry lists the options that are valid when the controlling field holds that value:

JSONCode
{ "name": "incidentType", "label": "Incident Type", "type": "picklist", "controllingFieldName": "investigationType", "controlledOptions": [ { "value": "External Theft", "options": [{ "label": "Shoplifting", "value": "Shoplifting" }] }, { "value": "Internal Theft", "options": [ { "label": "Register Theft", "value": "Register Theft" } ] } ] }

When the user picks a value for the controlling field, show only the matching entry's options for the dependent field.

Custom properties

GET /theft-cases/field-specs also returns customProperties, an array of the tenant's own case fields. fieldSpecs is unchanged. Each entry is { "key", "label", "type", "required", "options" }. key is the domain property key, never a Salesforce field API name. label is the mapping label, or the field label when the mapping label is blank. type and options come from the field. required is true when a report must send the key. The array is in form order, and it is empty when the org has no custom properties. Send values on POST /theft-cases as customProperties, a map of those keys to strings. PUT ignores the map.

Rendering checklist

  1. Read detail for current values and fieldSpecs for the form definition.
  2. For each fieldSpec, render an input of the right type, labeled by label, grouped by section.
  3. Mark it required when required is true. Disable it when it is not editable (see the editability note above).
  4. For enumerated fields, build the control from options. For dependent picklists, filter by the controlling field's current value.
  5. On submit, send only the writable fields back in the record body — the API re-validates and returns the updated envelope.
Last modified on