Field metadata
Every canonical retrieve, create, and update returns an envelope:
Code
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
| Key | Type | Meaning |
|---|---|---|
name | string | The field's API name — the key to read/write in detail. |
label | string | Human-readable label for the field. |
type | string | Field type (for example string, picklist, boolean, date, reference). |
required | boolean | Whether the field must be supplied on write. |
readOnly | boolean | null | Do not offer the field for editing. Populated by theft and person. |
createable | boolean | null | The field may be set on create. Populated by vehicle, item, and location. |
updateable | boolean | null | The field may be set on update. Populated by vehicle, item, and location. |
section | string | null | A grouping hint for laying the field out under a section heading. |
referenceTo | string | null | For reference fields, the related object the value points to. |
options | array | null | Allowed values for enumerated fields, each { "label", "value" }. |
controlledOptions | array | null | Dependent-picklist option sets, keyed by the controlling field's value (see below). |
controllingFieldName | string | null | For a dependent picklist, the name of the field that controls which options are valid. |
layoutHint | string | null | An 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 withcreateableandupdateable. To decide whether to disable an input, treat the field as editable whenreadOnlyisfalseor whenupdateableistrue.
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:
Code
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:
Code
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
- Read
detailfor current values andfieldSpecsfor the form definition. - For each
fieldSpec, render an input of the righttype, labeled bylabel, grouped bysection. - Mark it required when
requiredistrue. Disable it when it is not editable (see the editability note above). - For enumerated fields, build the control from
options. For dependent picklists, filter by the controlling field's current value. - On submit, send only the writable fields back in the record body — the API re-validates and returns the updated envelope.