Field metadata

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

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

fieldSpecs describes each field on the record so you can build a form
dynamically — labels, types, whether a field is required or read-only, and its
allowed values — without hard-coding them. Every domain returns the same
fieldSpec shape, so one rendering routine works across theft cases, vehicles,
persons, and items.

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	The field cannot be written. Populated by theft and person.
`createable`	boolean \| null	The field may be set on create. Populated by vehicle and item.
`updateable`	boolean \| null	The field may be set on update. Populated by vehicle and item.
`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
and item express it with createable / updateable. To decide whether to
disable an input, treat the field as editable when readOnly is false or
when updateable is true.

Enumerated fields (`options`)

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

{
  "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 — one entry per controlling value, each with the options
valid when the controlling field holds that value:

{
  "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.

Rendering checklist

Read detail for current values and fieldSpecs for the form definition.
For each fieldSpec, render an input of the right type, labeled by label,
grouped by section.
Mark it required when required is true; 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.

The fieldSpec shape

Enumerated fields (options)

Dependent picklists (controlledOptions)

Rendering checklist

Enumerated fields (`options`)

Dependent picklists (`controlledOptions`)