> ## Documentation Index
> Fetch the complete documentation index at: https://docs.farmtrace.co.za/llms.txt
> Use this file to discover all available pages before exploring further.

# Form fields

> Configure nested Dsync forms, submission behavior, scan rules, UI options, and device requirements.

A form is the object stored in a function's `form` key. The same structure can be nested under another form's `form` key. Omitted values use the defaults shown below.

## Form structure and submission

| Key              | Type             | Default    | Use                                                                                                                                               |
| ---------------- | ---------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `form`           | object           | `{}`       | Defines a child form. A child form uses this same key set.                                                                                        |
| `components`     | array of objects | `[]`       | Lists the fields and actions rendered by this form.                                                                                               |
| `postTo`         | string           | `"child"`  | Destination or parent/child posting target used by the workflow. Use the value expected by the configured relation.                               |
| `formType`       | string           | `"single"` | Selects the client flow. Current routes include `single`, `multi-scan`, `new-dsync`, `header`, `line-item`, `line-item-form`, and `bottom_sheet`. |
| `appendJson`     | object           | `{}`       | Adds fixed key/value pairs to the submitted record.                                                                                               |
| `hasGUID`        | boolean          | `false`    | Adds a generated identifier to the submitted record when enabled.                                                                                 |
| `iDColName`      | string           | `"Id"`     | Names the column that receives the generated identifier from `hasGUID`.                                                                           |
| `hasTimestamp`   | boolean          | `false`    | Adds the current submission timestamp under `Timestamp`.                                                                                          |
| `featureSupport` | object           | `{}`       | Enables form capabilities such as location or NFC. See [Feature support](#feature-support).                                                       |
| `hasLocation`    | boolean          | `false`    | Legacy location switch. Prefer `featureSupport.location`.                                                                                         |
| `formulas`       | array of objects | `[]`       | Defines named formulas used by calculated component values. See [Formulas](#formulas).                                                            |

<Note>
  Use JSON booleans and numbers (`true`, `false`, `10`) rather than quoted values (`"true"`, `"10"`) in new setup. This keeps the configuration unambiguous.
</Note>

## Scan and relationship behavior

| Key                 | Type    | Default | Use                                                                                                                                                 |
| ------------------- | ------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `denyDuplicateScan` | boolean | `false` | Rejects a repeated scan for the same function. When enabled, the client applies at least a 10-second duplicate lockout even if `scanDelay` is zero. |
| `scansBeforeDelay`  | integer | `1`     | Number of consecutive scans allowed before the configured delay/duplicate feedback is applied.                                                      |
| `scanDelay`         | integer | `0`     | Delay in seconds used by scan duplicate handling. Zero disables the delay unless `denyDuplicateScan` is enabled.                                    |
| `headerPostID`      | string  | `""`    | Column used to pass a created header identifier into a related child form. Use it with header/line-item workflows.                                  |
| `notLineItemHeader` | boolean | `false` | Selects the header posting behavior for header/line-item workflows.                                                                                 |
| `useBlocker`        | boolean | `false` | Shows the scan blocker interaction in scan flows. A user must complete the blocker gesture before scanning is enabled.                              |

## Feature support

`featureSupport` is an object. The client reads these top-level capability keys:

| Key                 | Type              | Use                                                                                                                           |
| ------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `nfc`               | boolean           | Enables automatic NFC input for compatible scan fields.                                                                       |
| `scanner`           | boolean           | Enables scanner capability checks for the form.                                                                               |
| `location`          | boolean           | Requests location capture for the submitted form data.                                                                        |
| `camera`            | boolean           | Enables camera capability checks for the form.                                                                                |
| `usb`               | boolean           | Enables USB capability checks for the form.                                                                                   |
| `bluetooth`         | boolean           | Enables Bluetooth capability checks for the form.                                                                             |
| `printing`          | object            | Supplies printing configuration when the form workflow prints. Configure this with the Device Kit or FarmTrace administrator. |
| `facialRecognition` | object or boolean | Enables or configures facial recognition when that capability is available to the account.                                    |

For example:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "featureSupport": {
    "nfc": true,
    "location": true
  }
}
```

`hasLocation: true` remains available for older configurations. When location is enabled, Dsync adds `Location` only when a location value is available on the device.

## UI options

Use the `ui` object for bottom-sheet presentation:

| Key                     | Type    | Default | Use                                                      |
| ----------------------- | ------- | ------- | -------------------------------------------------------- |
| `ui.uploadButton`       | boolean | `true`  | Shows or hides the bottom-sheet upload/submit button.    |
| `ui.isSheetDismissable` | boolean | `true`  | Allows or prevents manual dismissal of the bottom sheet. |

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "formType": "bottom_sheet",
  "ui": {
    "uploadButton": false,
    "isSheetDismissable": false
  }
}
```

For existing configurations without `ui`, the client also reads the legacy flat keys `isSheetDismissable` and `disableSheetUploadButton`. Prefer the nested `ui` object for new setup.

## Form-level devices

The form can declare device profile IDs once for its device components. The client accepts a single string, a comma-separated string, or a JSON array under `device`, `devices`, or `deviceIds`.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "deviceIds": [
    "com.example.flow-meter"
  ],
  "components": [
    {
      "compType": "device",
      "deviceOperationName": "read-flow-meter",
      "dispMessage": "Flow meter"
    }
  ]
}
```

A device component can override the form-level declaration with its own `deviceIds` or `deviceOperations`. If a form declares multiple device IDs, use `deviceOperations` to map operations to their device instead of relying on an implicit target.

## Formulas

Each formula object uses `formulaId` as its name and `formula` as its expression:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "formulas": [
    {
      "formulaId": "display_label",
      "formula": "Concat([Code], \" - \", [Name])"
    }
  ]
}
```

Use a named formula from a component's `defaultValue` with `${display_label}`. See [Write your first formula](/getting-started/write-your-first-formula) for expression syntax.

## Keys intentionally excluded

`childIdColumn` and `allowNFC` are legacy values parsed into the local form model but are not used by the current function UI behavior. Do not add them to new function setup. Runtime values such as parent data, context, generated form IDs, and component state are also not setup keys.

## Continue

* [Component types](/dsync/function-setup/component-types)
* [Component fields](/dsync/function-setup/component-fields)