Clearing and Resetting

The usual clear action makes a dependent field blank. For arrays and composed controls, choose the mode before writing the effect: the choice also changes pristine/dirty state and whether defaults may return.

clear

clear changes a control according to its mode. The default mode is empty.

{"type": "clear", "field": "statusDescription", "mode": "empty"}

Mode	Runtime behavior	Use it when
empty	Scalars become null; arrays keep their rows and recursively empty their leaf values by default; and each direct child of a group becomes null. The control is dirty, which blocks default reapplication.	The value should stay explicitly blank.
unset	Releases the explicit value and makes the control pristine. Defaults may apply later, but this does not guarantee an immediate reset.	User input should be discarded and reactive default behavior restored.
reset	Makes the control pristine, then re-evaluates and applies defaults using the current context. Arrays use the array default, then numberOfRows, then the stored default; composed controls resolve their whole value or child defaults through their owner.	The value should return to its default.

The modes affect form state as well as the visible value. empty is therefore not interchangeable with unset.

Array behavior for an empty clear

For an array target, arrayBehavior selects what an empty clear does:

arrayBehavior	Result
clearValues	The default when arrayBehavior is omitted. Keeps every current row control with its identity and order, and explicitly empties every leaf value recursively.
removeRows	Explicitly removes every array row.

arrayBehavior is considered only when mode is empty or omitted. It has no meaning for unset or reset; the Form Designer and schema validator do not offer it for those modes. unset retains its legacy behavior: it releases the explicit array value, marks the control pristine, and allows defaults to apply later without guaranteeing an immediate reset. reset deliberately re-evaluates and applies schema defaults, using stored control defaults as a fallback.

An empty clear with either array behavior keeps the target explicitly cleared, so defaults and numberOfRows do not refill it, regardless of how its current rows were initially created. With the default clearValues, the existing controls are not recreated: three filled rows become three empty rows, not the numberOfRows value. An already empty array stays empty. This also applies to a root array rendered through an inner form.

On reset, an explicit whole-array default (including []) wins and restores its exact row count and values. Without a whole-array default, config.numberOfRows.value restores exactly that many rows using item/field defaults or empty values; onlyForEmpty does not limit reset, even when old rows exist. Without either source, the legacy stored default applies. Defaults on the array's items schema alone do not determine how many rows exist.

Resetting a composed inner form or characteristic

All three CLEAR modes apply to the real inner controls as well as the wrapper:

Mode	Composed object result
empty or omitted	The wrapper is null; inner leaf values are emptied and marked as programmatic changes. Defaults remain blocked. Nested array rows stay unless arrayBehavior: "removeRows" is explicit.
unset	The wrapper and inner leaves are undefined and pristine. Current nested array rows remain; defaults are allowed again, without forcing their immediate evaluation.
reset	Re-evaluates the current default snapshot, including nested arrays, and makes the wrapper and inner tree pristine together.

reset of a fluent-inner-form or tsm-characteristic is an owner-aware composed reset. It is neither an ordinary undefined write nor an empty clear. The runtime resolves defaults with the owner's current expression context: an authored whole-object default takes precedence; if no such default exists, it recursively resolves each child schema default and uses an empty value for a child without one. Nested arrays retain the same array-default, numberOfRows, then stored-default fallback.

Datasource-backed defaults settle before one coordinated pristine result is shown in both the real inner tree and its outer wrapper. If the owner context changes and a newer reset starts, a pending older result is superseded rather than applying stale defaults. This holds for cold datasource loading and for already-warm datasource values.

For example, after an account selector changes, reset an account-detail inner form only with the newly selected account as its current context. If its default needs a datasource, the reset waits on a cold load; with a warm source it resolves immediately from that same current context. A delayed result for a previous account is not applied.

For example, with ten current rows, config.numberOfRows.value: 5, and no whole-array default, empty preserves ten empty rows, explicit removeRows leaves zero rows, and reset restores five rows with defaults or empty values.

{
  "type": "clear",
  "field": "items"
}

The omitted mode above means empty, and the omitted arrayBehavior means clearValues. Use it when the row structure must remain visible for continued data entry. To clear an array by removing rows, set arrayBehavior explicitly:

{
  "type": "clear",
  "field": "items",
  "mode": "empty",
  "arrayBehavior": "removeRows"
}

For example, if an array has a whole-array default containing two rows and the current form has four filled rows, the following outcomes apply:

Action	Result
empty with omitted arrayBehavior	The same four row controls remain, with all leaf values empty.
empty with arrayBehavior: "removeRows"	The array has zero rows.
reset	The default's two rows, including their default values, are restored.

Existing effects that must remove rows

An omitted arrayBehavior preserves array rows. Review existing array clear effects and set arrayBehavior: "removeRows" wherever deleting rows is the intended result. The saved schema cannot reveal that intent automatically.

arrayBehavior applies to array controls, including arrays rendered by dtl-fluent-array, dtl-fluent-accordion-array, dtl-fluent-editgrid, and dtl-fluent-fieldset/inner forms. It does not change whole-object clearing; clear the array path itself when selecting an array behavior is required.