Expression contexts and availability

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.

KayanOS serial-format expression editor showing the roots and helpers available for a Citizen Service Request reference.

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`, `$member`	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	Detected acyclic `$.field_key` dependencies run first; no `$value` or `$statusTemplates`; each field runs once.
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.

$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, $relations, and $member, but consume results differently. $member is the member who is saving: { id }, where id is the qualified member id (members:<id>) — the same form member fields store. It is { id: null } when no member is acting, for example in system jobs. The record editor evaluates it as the signed-in member; the server repeats the check with the member who sent the request.

// only the assigned reviewer can edit the decision
$.reviewer == $member.id

// visibility or editability
$.requires_inspection == true

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

For a non-array multilingual text, long_text, or rich_text field, validation helpers with the value argument omitted—such as v.minLength(2)—run against every populated localized string. The first failing locale blocks the save in both the record editor and server validation. $value remains the complete localized object when the expression references it explicitly, so do not pass that object to a string helper and assume it represents one language. Test every maintained locale plus the all-empty case; a valid English value does not excuse an invalid Arabic value. 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 starts with source data and adds detected local calculated dependencies written as $.field_key after evaluating them. It exposes only configured direct/inverse relations, has no $value or $statusTemplates, and evaluates each field once. Cycles and their dependents run without calculated keys; bracket notation does not establish a local dependency.

// portable when both source values are ordinary, non-calculated record fields
$.requested_amount * $.fee_rate

Test calculated dependencies after background refresh, avoid cycles, and configure every relation needed by that path. See 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:

// 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

Identify the exact runtime in the matrix.
Confirm source key names and data types with a known safe record.
Test empty, normal, and exceptional data; for multilingual entity text, test every populated locale independently.
For dates, test the intended timezone boundary.
For lookups, test least-privileged data and do not display unnecessary fields.
Record the policy decision outside the expression when it affects access, approval, or public delivery.

Expression language

Expression helper reference

Practical reference

Expression contexts and availability

The context is part of the expression

Entity defaults

Entity rules and validations

Calculated fields: preview is not background processing

Error and empty-value behavior

Roots are data contracts, not convenience names

Review checklist

​The context is part of the expression

​Entity defaults

​Entity rules and validations

​Calculated fields: preview is not background processing

​Error and empty-value behavior

​Roots are data contracts, not convenience names

​Review checklist

​Related guides

The context is part of the expression

Entity defaults

Entity rules and validations

Calculated fields: preview is not background processing

Error and empty-value behavior

Roots are data contracts, not convenience names

Review checklist

Related guides