Expression language syntax

Start with the execution context

An expression returns a value. The feature that evaluates it decides whether that value becomes a calculated field, a visibility decision, a validation result, form text, a serial number, or document output. The same spelling is not automatically valid everywhere: available root variables and context-specific functions differ. Before writing an expression, identify all four of these facts:

The feature that evaluates it: entity default, entity rule, calculated field, form, serial configuration, or document template.
The exact field key or context root, rather than a visible label.
The required output type: Boolean, Number, text, date, validation result, or list.
How an empty value, lookup failure, or error should behave.

Read expression contexts and availability before copying a working expression into another feature.

Values and paths

Literals

Value	Example	Use
Text	`"received"` or `'received'`	Quote literal option values and output text.
Number	`1250.5`	Keep arithmetic inputs in Number fields where possible.
Boolean	`true`, `false`	Use for conditions and explicit choices.
Missing value	`null`, `undefined`	Handle deliberately; they are not interchangeable with an empty string.
List	`["normal", "urgent"]`	Pass a local collection to a helper or membership test.
Object	`{ code: "CSR", priority: "high" }`	Use sparingly for local logic; model operational data as fields.

Read a value

The root comes from the context. Entity rules commonly expose the current record as $; document templates expose it as $record.

$.requested_amount
$record.request_id

Use dot access for ordinary keys and brackets for a numeric index or a key that is not a simple identifier:

$.inspections[0].result
$.metadata["source-system"]
$record.attachments[0]

Do not guess a key from its translated title. A robust expression refers to the stable field key configured in the builder.

Filter a list

Relative filters use . for the item currently being considered:

$.inspections[.result == "pass"]
$.inspections[.result == "pass"].scheduled_at

Treat an empty result as normal. Test it before using a list as the basis for a critical decision:

isNotEmpty($.inspections[.result == "pass"])

Operators and precedence

Use parentheses whenever arithmetic, comparison, and logical decisions are mixed. They make policy review easier and prevent accidental reliance on precedence.

Purpose	Syntax	Example	Runtime meaning
Unary values	`!`, `+`, `-`	`!$.documents_complete`	logical not, numeric sign/coercion
Power	`**`, `^`	`2 ** 3`	both are exponentiation
Remainder	`%`	`$.sequence % 2`	evaluated before multiplication/division
Multiply/divide	`*`, `/`, `//`	`17 // 5`	`//` is floor division
Add/subtract	`+`, `-`	`$.base_fee + $.inspection_fee`	`+` can also concatenate text
Strict comparison	`==`, `!=`	`$.status == "approved"`	binary equality is strict; types must match
Numeric tolerance	`~=`, `!~=`	`$.score ~= 7.5`	within / outside `0.01`
Ordered comparison	`>`, `>=`, `<`, `<=`	`$.requested_days <= 30`	compare compatible types
Membership	`in`	`$.priority in ["high", "urgent"]`	supports lists and structured values
Short-circuit AND	`&&`	`$.owner_id && $.due_date`	only evaluates the right side if needed
Short-circuit OR	logical OR	fallback owner name	returns the first usable branch
Ternary choice	`? :`	`$.priority == "urgent" ? "same-day" : "standard"`	choose one value

For a fallback, write the logical-OR operator in an expression block rather than placing its two pipe characters inside a Markdown table cell:

$.owner_name || "Unassigned"

The helper eq(left, right) intentionally uses loose equality, while binary == does not. Prefer binary == for stored option values; use eq only when deliberate type coercion is part of the policy.

Textual `and`, `or`, and `xor`

Textual operators exist for validation-oriented expressions, but their validation-message behavior differs between the shared builder runtime and document-template runtime. They are not a portable way to aggregate several human-facing errors. For ordinary Boolean/value logic, prefer && and ||. For field validation, use the validation helpers in the exact validation context and test the returned message.

Functions and pipe transforms

Most general helpers have two equivalent forms. A function receives all arguments explicitly:

round($.requested_amount, 2)

A transform receives the value to the left of | as its first argument:

$.requested_amount | round(2)

Use the version that reads best. Validation functions, form lookup/filter helpers, and the document-template lookup helper are function calls only. Form-only and serial-only helpers are not general calculated-field APIs; their availability is stated on each reference page. Browse the complete reference by task:

Templates, lists, and objects

Backtick templates combine fixed text and evaluated values. Put the evaluated expression inside {{ and }}:

`Request {{ $.request_id }} is assigned to {{ $.owner_name || "the service team" }}`

An interpolation that resolves to null or undefined becomes an empty string. That avoids displaying the word undefined, but it can hide missing data. Add an explicit fallback for any public-facing sentence. You can create a small list or object for local logic:

$.priority in ["high", "urgent"]
{ request_id: $.request_id, status: $.status }

Spread syntax can combine an already structured value with a new item:

[...$.selected_categories, "other"]

Keep these structures local to the expression. If staff must search, approve, report on, or audit a value, store it in a normal field instead.

Validation expressions are not ordinary conditions

Validation helpers return true when valid and a localized error result when invalid. In a field-validation context, helpers such as v.required() can receive the current field value automatically through $value.

v.required() and v.minLength(3)
v.greaterThan($.requested_amount, 0)

Entity validation and form validation do not consume every return value in exactly the same way. A form, for example, treats true, null, undefined, and an empty string as valid; an expression error can be handled differently from an entity validation error. See validation helpers and expression contexts before publishing a rule.

Determinism, dates, and safe use

Avoid random, shuffle, sample, and sampleSize in serial formats, persisted calculated fields, or auditable decisions. Avoid relying on the live clock without a refresh policy: now(), isToday, isTomorrow, isYesterday, and getAge can change without a record edit. Date helpers do not all use one timezone model. Some calendar helpers use local date setters while dateAdd, comparison units, component extraction, and dateFormat use UTC-oriented behavior. Use an ISO-like source value, state the intended timezone in the field description, and test values around midnight and daylight-saving boundaries when applicable. dateFormat uses YYYY, MM, DD, HH, mm, ss, and SSS. This is different from the smaller serialDate vocabulary (yyyy, yy, MM, dd).

Test and troubleshoot

Symptom	First check	Safe response
Blank result	Is this root available in this feature?	Compare the expression with the context table and test a record with known data.
Condition always false	Are stored option values and types exact?	Use strict `==` with the stored value, not a translated label.
`NaN` or unexpected text	Is a Number field actually carrying text/null?	Check the source and explicitly convert or reject invalid input.
Date moves by one day	Is a local/UTC boundary involved?	Test an ISO value near midnight in the target timezone.
Green editor, failed runtime	Is a context-only helper being used elsewhere?	Treat editor status as syntax feedback; test in the real feature.
Lookup returns nothing	Is this a form or template lookup with an approved query and mode?	Check scope, context, filter keys, timeout behavior, and data-exposure policy.

KayanOS Automations does not provide this expression runtime as a general trigger/action configuration language. Use this reference only where a KayanOS builder field explicitly supports expressions.