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

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

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

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