Form expressions and lookups

When to use form expressions

Use a form expression to derive a default, control visibility or editability, compute a value, shape action text, or look up service data for the current form experience. It is not a server-side permission system and it is not a substitute for a workflow approval. The full callable catalog is in Form helpers and lookup filters. This guide explains how to use those helpers safely. KayanOS form field settings for the Citizen Service Intake form, including visibility, repeatable, and validation-expression controls.

KayanOS form field settings for the Citizen Service Intake form, including visibility, repeatable, and validation-expression controls.

Form roots

Root	Meaning
`$this`	The node currently evaluating the expression.
`$form`	The exposed form object.
`$values`	Raw variables and field answers in one consistent value-only tree. Prefer this root for new expressions.
`$`	Form variables directly, plus exposed child objects. Read a field answer through its `.value` property.
`$parent`, `$siblings`, `$grandparent`, `$uncles`	Nearby nodes in the form structure.
`$repeatables`, `$repeatable_instances`	Repeatable containers and the current instance map.
`$index`, `$item`	Current repeatable-loop index and item. `$index` falls back to `0`.
`$value`, `$defaultValue`	Current field value and configured default value.
`organizationId`, `formId`, `formVersionId`, `sessionId`, `initiatorId`, `currentMemberId`	Qualified identifiers for the active form/session/member.
`currentUserType`	`"public"`, `"member"`, or no value.

Use small, local expressions. A condition for one field should usually depend on that field’s siblings or a clear form value, not on a long path across several repeaters.

$values.status == "submitted" && $values.request_amount > 1000

Legacy $.status and $.request_amount.value expressions remain supported. The expression editor suggests their $values equivalents.

$siblings.requires_inspection.value == true

Repeatable patterns

In a looped repeatable, $item is the source loop item and $index is its zero-based position. In a user-controlled repeatable, use the instance/sibling values that exist in the current form structure.

`Inspection {{ $index + 1 }}: {{ $item.site_name || "site not supplied" }}`

Do not use a repeatable count as a hidden policy gate. Validate the actual field values that make a request eligible.

UI checks are not authorization

hasVerb, hasVerbOnRecord, hasScope, and hasAnyScope can adapt what a member sees in a form. They do not grant access. In particular, verb helpers return true during server evaluation, so an expression using them cannot be your only enforcement point.

hasVerb("review") && $.service_category.value == "regulated"

Use this to show a reviewer-oriented block. Keep actual authorization and state-transition rules in the relevant server-side service policy.

Record lookup: keep it narrow, private, and non-authoritative

getRecord and getRecords are form data conveniences. They can return an empty/null-like result when the form context is unavailable or a lookup times out. Their backing lookup runs through a system-level data path; it does not filter results using the current participant’s ordinary record or field permissions, role, or scope. It also has no lookup-limit argument, so a broad filter can load every matching record. That makes three boundaries explicit:

hasVerb* and hasScope* can change presentation only; they do not authorize an action.
getRecord and getRecords must never decide whether a participant is authorized or entitled to data.
A lookup result must never be rendered to a public or otherwise unauthorized participant. A hidden field is not an access-control mechanism.

Use a selective filter against an entity and fields deliberately designed for this purpose, then safely handle no result:

getRecords("licenses", f.and(
  f.eq("status", "approved"),
  f.eq("holder_id", $.applicant_id.value)
))

Do not copy this as a broad public lookup pattern. Do not query an entity that carries personal, financial, or operational data merely to decide visibility. Prefer a small purpose-built record with only the minimum non-sensitive fields, an equality filter tied to the current request, and an owner-reviewed output. Before publishing a public form, test with a public participant and prove that no value returned by a lookup is rendered, exported, or used to authorize an action for that participant.

Build filters with `f.`

The f. functions build a database filter object for getRecords; they do not filter an arbitrary list in memory. The most useful pattern is a small conjunction:

f.and(
  f.eq("status", "approved"),
  f.gte("score", 80),
  f._in("district", ["central", "north"])
)

Use f._in when a readable, unambiguous inclusion helper is preferred. Test the exact field keys and stored option values. Do not build a broad lookup and then hide results with a later expression.

Weekdays and service shifts

isWeekend(date, entityId?) and isWeekday(date, entityId?) can use configured shift work days when an applicable entity and service data are available. Without that data, they fall back to Saturday/Sunday. Treat them as online regular-form helpers and test the target organization’s schedule.

isWeekday($.appointment_date.value, $.assigned_position_id.value)

Offline form limits

Offline forms block getRecord, getRecords, hasVerbOnRecord, hasVerb, hasScope, and hasAnyScope. They also restrict several data-backed form features. Keep offline expressions self-contained: field values, simple conditions, and deterministic general helpers.

$.requires_inspection.value == true && isNotEmpty($.site_address.value)

Validate an offline form before publishing. Do not rely on a function that happens to be suggested by the editor if the offline validator blocks it.

Test matrix

Test	What to verify
Public/member	`currentUserType` produces the intended harmless UI difference.
Scope/verb	The UI adapts for the intended member, but server policy still rejects an unauthorized action.
Empty lookup	A lookup returning no rows leaves the form understandable and safe.
Public lookup safety	A public participant cannot see, export, or gain access from any returned lookup value.
Timeout	A slow lookup does not turn an unknown result into an approval.
Repeatable	`$index` and `$item` resolve for first, later, and empty loop items.
Offline	The form saves/publishes with no blocked data/permission function.

Expression language

Expression helper reference

Practical reference

When to use form expressions

Form roots

Repeatable patterns

UI checks are not authorization

Record lookup: keep it narrow, private, and non-authoritative

Build filters with `f.`

Weekdays and service shifts

Offline form limits

Test matrix

​When to use form expressions

​Form roots

​Repeatable patterns

​UI checks are not authorization

​Record lookup: keep it narrow, private, and non-authoritative

​Build filters with f.

​Weekdays and service shifts

​Offline form limits

​Test matrix

​Related guides

When to use form expressions

Form roots

Repeatable patterns

UI checks are not authorization

Record lookup: keep it narrow, private, and non-authoritative

Build filters with `f.`

Weekdays and service shifts

Offline form limits

Test matrix

Related guides