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

# Expression contexts and availability

> Know exactly which roots, helpers, failure behavior, and data limits apply before reusing a KayanOS expression.

## The context is part of the expression

An expression has no universal data model. A line that is correct in a calculated field can be blank, unsafe, or silently misleading in a form, serial format, or document template. Use this matrix before you reuse an expression.

![KayanOS serial-format expression editor showing the roots and helpers available for a Citizen Service Request reference.](https://kayanos.app/docs-images/en/reference/expressions-contexts.png)

| Where it runs                           | Primary roots                                                                                                | Context-specific helpers             | Important limit                                                                                           |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
| Entity default                          | `$record`, `$organizationId`, `$entityKey`, `$now`                                                           | general helpers                      | `$` is not the default root here.                                                                         |
| Entity condition/editability/validation | `$`, `$value`, `$relations`                                                                                  | general + validation helpers         | A visibility rule, editability rule, and validation result fail differently.                              |
| Synchronous calculated field            | `$`, `$value`, `$relations`, `$inverseRelations`, `$statusTemplates`                                         | general helpers                      | Only the current calculated output is removed from `$`; multiple passes can settle dependencies.          |
| Background calculated field             | `$`, `$relations`, `$inverseRelations`                                                                       | general helpers                      | All calculated outputs are removed; no `$value` or `$statusTemplates`; one pass.                          |
| Entity serial ID                        | `$`, `$record`, `$organizationId`, `$entityKey`, `$fieldKey`, `$timezone`, `$now`, `$namespace`, `$sequence` | `serialPad`, `serialDate`            | Use deterministic formatting only.                                                                        |
| Regular form                            | `$this`, `$form`, `$`, repeatable roots, `$value`, member/session roots                                      | form helpers, `f.*`, weekday helpers | UI/data convenience is not authorization.                                                                 |
| Offline form                            | local form roots only                                                                                        | no data/permission helpers           | `getRecord`, `getRecords`, verb/scope helpers are blocked.                                                |
| Form numbering                          | saved-state/field/initiator roots plus sequence roots                                                        | `serialPad`, `serialDate`            | Root names differ from entity serial IDs.                                                                 |
| Document template                       | `$record`, `$inverseRelations`, `$organization`, `$member`, `$now`                                           | template `getRecords`                | `$relations` is presently an empty reserved object; lookup contract and execution mode differ from forms. |
| KayanOS Automations                     | not a general expression runtime                                                                             | none asserted here                   | Do not paste builder expressions unless that exact input documents support.                               |

## Entity defaults

Entity defaults use `$record`, not `$`. The server evaluates a configured default only when the corresponding value is absent or empty.

```jexl theme={null}
$record.service_category == "urgent" ? "priority" : "standard"
```

Use defaults to provide an initial value, not to prove that a person reviewed a decision. Keep an important confirmation as an explicit field or action condition.

## Entity rules and validations

Entity field visibility, editability, and custom validation share `$`, `$value`, and `$relations`, but consume results differently.

```jexl theme={null}
// visibility or editability
$.requires_inspection == true

// custom validation
v.greaterThan($value, 0)
```

The server treats an evaluation failure in a visibility rule differently from an evaluation failure in an editability or validation rule. Do not use a malformed expression as a policy mechanism. Test the visible, editable, and invalid paths separately with a non-production record.

## Calculated fields: preview is not background processing

The interactive/synchronous calculation path can expose `$value`, configured direct relations, an empty inverse relation object, and status templates. It can iterate through calculated fields. The background job strips every calculated output from `$`, exposes only configured direct/inverse relations, has no `$value` or `$statusTemplates`, and evaluates each field once.

```jexl theme={null}
// portable when both source values are ordinary, non-calculated record fields
$.requested_amount * $.fee_rate
```

Avoid a calculation that needs another calculated output or a relation that is not configured for the background path. See [Calculated fields](/build/calculated-fields) for the full execution model.

## Error and empty-value behavior

| Consumer                 | A passing result                                    | What to avoid                                                    |
| ------------------------ | --------------------------------------------------- | ---------------------------------------------------------------- |
| Entity custom validation | `true`, `null`, or `undefined`                      | Returning a display object that is not a localized error object. |
| Form validation          | `true`, `null`, `undefined`, or `""`                | Assuming an evaluation error will necessarily block a form.      |
| Visibility/editability   | Boolean coercion                                    | Depending on an error fallback to enforce a business rule.       |
| Calculated field         | any defined value                                   | Using an error/blank result as evidence of zero.                 |
| Template interpolation   | text form of the value; null/undefined become blank | Letting a missing public value disappear without a fallback.     |

## Roots are data contracts, not convenience names

Use a context root that is actually provided. For example:

```jexl theme={null}
// entity rule
$.status == "received"

// entity default
$record.status == "received"

// document template
$record.status == "received"
```

The first expression is not automatically a valid default or document-template expression. Use the editor as syntax assistance, then validate the result in the real feature.

## Review checklist

1. Identify the exact runtime in the matrix.
2. Confirm source key names and data types with a known safe record.
3. Test empty, normal, and exceptional data.
4. For dates, test the intended timezone boundary.
5. For lookups, test least-privileged data and do not display unnecessary fields.
6. Record the policy decision outside the expression when it affects access, approval, or public delivery.

## Related guides

* [Expression language syntax](/reference/expressions/language-syntax)
* [Form expressions and lookups](/reference/expressions/forms-and-lookups)
* [Serial and form-number expressions](/reference/expressions/serial-and-numbering)
* [Document-template expression context](/reference/expressions/document-template-context)