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. 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 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:

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

{
  "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`)