# Field metadata

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

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

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

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