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

# Expressions in the builder

> Use KayanOS expressions for calculated values, visibility rules, validation, labels, and controlled decisions.

## Use expressions to make a rule visible

An expression is appropriate when a value or decision can be derived consistently from fields that already exist. It is not a replacement for a workflow design, a permission model, or a review step.

Good builder uses include:

* calculating a service target from received date, category, and priority;
* showing a conditional section only when a request needs an inspection;
* validating that an amount is positive or a reference has a required format;
* constructing a readable document or notification line from structured fields;
* summarizing a related list for an internal reviewer.

Do not use an expression to conceal a critical decision, to bypass an approval, or to place a secret in a template.

## Choose the right place for the rule

| Need                             | Best fit                              | Example                                     |
| -------------------------------- | ------------------------------------- | ------------------------------------------- |
| Show a value derived from fields | Calculated field                      | estimated fee, elapsed days, combined label |
| Prevent invalid input            | Field validation                      | required reference, allowed value range     |
| Show or hide a section           | Layout or form condition              | display inspection details only when needed |
| Generate readable text           | Document template or label expression | service acknowledgement, case title         |
| Find permitted form data         | Form expression with `getRecords`     | show qualifying licenses in a staff form    |

Keep the rule near the decision it supports. A calculated service target belongs with the request fields; a document phrase belongs in the document template; a permission-sensitive lookup belongs only in its supported form context.

## Build a calculated field step by step

### 1. Define the result in plain language

For a permit request, write: “The target date is two days after receipt for urgent requests and seven days after receipt for all other requests.”

### 2. Confirm the source fields

You need a Date or Date-time field such as `received_at` and a controlled field such as `priority`. Do not rely on a visible label if the expression needs the field key.

### 3. Write the smallest expression

```txt theme={null}
$.priority == "urgent" ? addDays($.received_at, 2) : addDays($.received_at, 7)
```

### 4. Test normal and exceptional records

Test an urgent request, a normal request, and a request with no received date. Decide what the blank-date result should be before publishing. If a missing date must block work, use a validation rule; do not silently calculate an unreliable target.

## Four practical patterns

### Calculate a numeric result

Use normal fields for amounts and a calculated field for the final, reviewable result.

```txt theme={null}
round(($.base_fee + $.inspection_fee) * $.multiplier, 2)
```

Use this for fee estimates, quantities, progress percentages, or workload totals. Store the inputs separately so a reviewer can understand the result.

### Show a conditional section

Use a simple condition to avoid asking irrelevant questions.

```txt theme={null}
$.requires_inspection.value == true
```

For a licensing form, use this condition on the inspection section. The condition improves the entry experience; it does not grant access or change the record status.

### Validate a reference before saving

Validation expressions return `true` when valid and a localized message when invalid.

```txt theme={null}
v.required() and v.matchRegex("^LIC-[0-9]+$")
```

In a field-validation context, the current field value is supplied automatically when the first argument is omitted. Test a valid reference, an empty reference, and a value with the wrong prefix.

### Build a document sentence with a fallback

Use a template string to construct readable text without exposing missing data.

```txt theme={null}
`Request {{ $.serial_id }} is assigned to {{ $.owner.name || "the service team" }}`
```

Keep the data itself in fields. The template is for presentation, not the source of truth.

## Make expressions maintainable

* Name fields for their business meaning, not for a temporary screen label.
* Prefer one short expression per decision over a long expression that combines unrelated policy.
* Use parentheses around mixed arithmetic and comparisons.
* Treat `null`, empty text, and empty lists as expected states.
* Keep rule text and the user-facing field description aligned. If the policy changes, update both.
* Test with a non-production record after changing a field key, option value, relation, or template context.

## Diagnose a result before changing the expression

| Symptom                  | Check first                                                                        |
| ------------------------ | ---------------------------------------------------------------------------------- |
| Blank calculated value   | Is the source field present in this expression context?                            |
| Unexpected text or `NaN` | Is a number being read as text or an empty value?                                  |
| Condition never shows    | Does the controlled option use the exact stored value?                             |
| Validation never appears | Is the rule configured as validation and returning `true` or an error result?      |
| Template hides a name    | Does the relation expose the property in this context, and is a fallback intended? |

## Next steps

* Read the complete [expression language syntax](/reference/expressions/language-syntax).
* Browse all [registered helpers](/reference/expressions/helpers/math), each with a signature and example.
* Use [Entity fields and layouts](/build/entity-fields-and-layouts) to choose the right source data before writing a rule.

![KayanOS expression builder](https://kayanos.app/docs-images/en/build/expressions-in-builder.png)