Okyline Annex C Quick Reference - Expression Language

Version: 1.7.0 Date: May 2026 Status: Draft

Companion to the Okyline Core Language Quick Reference. Covers the $compute expression language for cross-field business rules and computed validations.

C - Expression Language

Okyline includes a pure, deterministic expression language for computed validations. It lets you express cross-field business rules - e.g. total == subtotal * (1 + taxRate) - that cannot be captured by per-field constraints alone. Expressions are declared in a $compute block and attached to fields with (%Name).

C.1 $compute Block

Declared at root level, alongside $oky:

{
  "$compute": {
    "TaxAmount": "subtotal * taxRate",
    "ValidTotal": "total == subtotal + %TaxAmount"
  },
  "$oky": {
    "invoice": {
      "subtotal": 100.0,
      "taxRate": 0.2,
      "total|(%ValidTotal)": 120.0
    }
  }
}

↳ %TaxAmount references another expression; (%ValidTotal) validates the field. %Name.field.deep accesses members of the compute’s result.

Rules: - Expression names: start with letter, then letters/digits/underscores - Circular dependencies → parsing error - Expressions are evaluated lazily when referenced

Parameterized computes - suffix the name with a formal parameter list; call with matching arguments:

"$compute": {
  "CategoryCheck(cat)": "category != cat || rate > 0",
  "InRange(lo, hi)": "it >= lo && it <= hi"
},
"$oky": {
  "age|(%InRange(18, 120))": 30,
  "rateS|(%CategoryCheck('S'))": 20
}

↳ Params shadow sibling fields inside the body; use this.field to unshadow. Args on a field constraint must be literals or dotted paths; full expressions are allowed in compute bodies. Arity mismatch = load error. Params must not collide with special variables (it, parent, index, …). A parameter bound to an object exposes its members via p.field; a list parameter composes with firstOf/at/findFirst/sum/…

C.2 Field Constraint - (%Name)

"fieldName|(%ExpressionName)": exampleValue

Constraint exclusivity: (%Name) cannot combine with other (...) constraints (range, comparison). Include range checks inside the expression instead.

Evaluation order: Type → Standard constraints (@, {...}, ~...~) → Computed expression

Container vs element compute:

"field|@ [size] (%ContainerCheck) -> (%ElementCheck)": [10, 20]

↳ Before ->: evaluated once on collection (it = collection). After ->: evaluated per element (it = element).

C.3 Evaluation Context

Field resolution: direct name access, dot notation for nested (address.city), missing fields → null, null-safe navigation.

The it variable: - In field constraint: value of the field being validated - In aggregation lambda on scalars: current element - In aggregation lambda on objects: current object (rarely needed - use property names) - In aggregation lambda on nested collections: the inner collection (composable: sum(map(matrix, sum(it)))) - Outside any context: null

C.4 List Iteration Context (Lambda Only)

"$compute": {
  "IsUnique": "countIf(parent.items, id == origin.id) == 1"
}

↳ Inside the lambda: id = iteration element’s id, origin.id = validated element’s id

C.5 Operators

List literals: [a, b, c] - inline list, usable anywhere a value is expected.

Precedence (high to low): ?? → * / → + - → comparisons → equality → && → || → ? :

C.6 Date Functions

C.7 String Functions

String index handling: negative start → clamped to 0, negative length → 0, start > length → "", end > length → clamped. Never throws.

String ↔︎ List:

countIf(chars(name), in(it, ["a","e","i","o","u"]))  // count vowels
join(filter(split(csv, ","), it != ""), ",")           // clean CSV

C.8 Numeric Functions

Rounding modes: HALF_UP (default), HALF_DOWN, HALF_EVEN, UP, DOWN, CEILING, FLOOR

Precision: Exact decimal arithmetic within 6 decimal places (configurable via $decimalScale, see Core spec §7.3). No IEEE-754 artifacts (0.1 + 0.2 = 0.3 exactly). Division by zero → null.

Type promotion: int + int → int, int + decimal → decimal, int / int → decimal (division always returns decimal).

C.9 Aggregation & Utility Functions

sum(items, quantity * unitPrice)           // object collection
sum([10, 20, 30])                          // scalar collection
filter([1, 2, 3, 4], it > 2)              // → [3, 4]
map(items, toUpperCase(code))              // transform

Membership - in:

↳ null value → false. List as first arg → containsAll semantics.

Lookup - lookup:

lookup(currency, rates)                    // get value by key from map
lookup(key, src) ?? defaultValue           // with fallback
join(map(chars(code), lookup(it, charMap) ?? it), "")  // char-by-char transform

Compute reference - %Name:

"$compute": {
  "LineTotal": "netAmount * (1 + vat)",
  "InvoiceTotal": "sum(lines, %LineTotal)"
}

↳ %LineTotal evaluates LineTotal for each element in the aggregation

List element access - retrieve a single element (null-safe):

Member access on any expression - chain .field after a function call or parenthesized expression:

firstOf(items).amount
findFirst(lines, cat == 'S').amount
%getParty('S').address.city
at(payments, 0).status

↳ Dotted paths on bare identifiers (parent.x.y) are unchanged - the postfix .field applies after ) or ]. Resolution on null base → null.

C.10 Null Handling Summary

Okyline® is a registered trademark of Akwatype.