Annex C - Okyline Expression Language (Normative)

Version: 1.8.0 Date: September 2026 Status: Draft

License: This annex is part of the Open Okyline Language Specification and is subject to the same license terms (CC BY-SA 4.0). See the Core Specification for full license details.

This annex defines the Okyline Expression Language, a pure and deterministic language for expressing computed validations. It enables business invariants such as cross-field calculations (e.g., total == subtotal * (1 + taxRate)) and conditional logic based on field values. Expressions are declared in a $compute block and referenced in field constraints using the (%ExpressionName) syntax.

Relation to the Core Specification

This annex defines the Okyline Expression Language, used inside $compute blocks and computed field constraints.

It specifies:

• the declaration of computed expressions ($compute block)
• the syntax for referencing expressions in field constraints ((%Name))
• the grammar, operators, and evaluation semantics of expressions

Implementations claiming conformance to this annex MUST implement the rules it describes (Core, Conformance).

The Expression Language is an integral component of Okyline, not a separate language. It extends the core validation model with computation and conditional logic while remaining pure, deterministic, and side-effect-free.

Although this annex is part of the Okyline 1.8.0 Draft specification, the expression language defined here is considered stable for practical use.

C.1 Overview

The Okyline Expression Language defines the grammar and semantics used in $compute blocks and computed constraints.

This annex is normative, meaning its contents define the expected behavior of conforming implementations of Okyline 1.8.0.

Expressions are pure, deterministic, and evaluated within the context of the object where they appear. All functions are null-safe and side-effect free.

C.2 Computed Expression Block - $compute

Okyline reserves the special block $compute as a container for named expressions. It is declared at the root level, alongside $oky.

C.2.1 Syntax

{
  "$compute": {
    "ExpressionName": "expression body"
  },
  "$oky": {
    ...
  }
}

Examples:

A computed validation: total is checked against the expression ValidTotal.

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

The same check with an intermediate compute: ValidTotal reuses %TaxAmount, which is never a constraint by itself.

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

C.2.2 Normative Rules

• $compute is declared at the root level, not inside $oky.
• $compute is optional; when present, it MUST be a JSON object.
• Keys are expression names; values are expression strings.
• Expression names MUST be valid identifiers:
  • Start with a letter (a-z, A-Z)
  • Contain only letters, digits (0-9), and underscores (_)
• A key MAY carry a label after a |: "ItemTotal | Line amount incl. VAT": "quantity * unitPrice". The name is the identifier; the label is read by documentation tools only, and everything after the first | is the label. The parameter list of a parameterized compute (§C.2.3) belongs to the name, before the |.
• Circular dependencies MUST be detected at schema load time and cause a parsing error.
• Expressions are evaluated lazily when referenced.

C.2.3 Parameterized Computes

A compute may declare formal parameters by suffixing its name with a parenthesized, comma-separated list of parameter names, each a single segment (§C.5.1). Parameters are bound to call-site values and are visible only inside the body of that compute.

"$compute": {
  "CategoryCheck(cat)": "category != cat || rate > 0",
  "InRange(lo, hi)": "it >= lo && it <= hi"
}

Call syntax: %Name(arg1, arg2, ...). Argument count MUST equal the declared arity; a mismatch is a schema load error. When called from a field constraint (e.g. "field|(%Name(arg))"), arguments are limited to literals or dotted identifier paths; the full expression form is available when calling from within another compute body.

"age|(%InRange(18, 120))": 30
"rate|(%CategoryCheck('S'))": 20

Scope rules:

• Parameter names MUST be valid identifiers and MUST NOT collide with the reserved special variables listed in §C.4.3 to §C.4.5 (it, this, root, parent, index, size, prev, next, first, last, origin, isOrigin, isFirst, isLast).
• Inside the body, a parameter shadows a sibling field of the same name. The schema field remains accessible via this.<field> (see §C.4.3).
• Parameters are local to the compute that declares them; they do not propagate to invoked computes. Each invoked compute receives only what is passed explicitly at its call site.
• A compute with arity N MUST be called with N arguments; a bare %Name reference is reserved for arity 0.

Parameter value shape. An argument is evaluated at the call site and bound to its parameter as-is - scalar, object, or list. Inside the body:

• Scalar: use the parameter name directly (p).
• Object / map: access members via p.field (and cascade for nested paths: p.address.city).
• List: use the list-element access functions of §C.10.3 (firstOf(p), at(p, 0), findFirst(p, pred), etc.) or iterate with aggregations (sum(p, ...), filter(p, ...), …).

"$compute": {
  "GetAddress":    "customer.address",
  "CheckCity(a)":  "a.city == 'Paris'",
  "CheckDeep(a)":  "a.region.country == 'FR'",
  "Total(lines)":  "sum(lines, LineExtensionAmount)"
}

Canonical name: the identifier before the ( is the canonical name used in collision checks, references, and error reporting. Declaring both "F" and "F(a)" in the same $compute block is a schema load error.

C.3 Usage in Field Constraints - (%Name)

To validate a field using a computed expression, reference it with the (%ExpressionName) syntax in the field’s constraint declaration. The same reference serves as the operand of a condition, fieldName(%ExpressionName) (Core §6.3.22).

C.3.1 Syntax

"fieldName|(%ExpressionName)": exampleValue

Example:

{
  "$oky": {
    "order": {
      "quantity|(>0)": 5,
      "unitPrice|(>0)": 20.0,
      "total|(%CheckTotal)": 100.0
    }
  },
  "$compute": {
    "CheckTotal": "total == quantity * unitPrice"
  }
}

C.3.2 Validation Semantics

When a field references a computed expression:

• The expression is evaluated in the field’s parent object context.
• The result determines validation outcome:

Error reporting SHOULD include:

• Field path (e.g., order.total)
• Expression name (e.g., CheckTotal)
• Failure detail (sub-expression that failed, or type violation)

C.3.3 Combining with Other Constraints

(%Name) can be combined with other constraint types:

"email|@ (%ValidEmail) ~^[^@]+@[^@]+$~|Contact email": "[email protected]"

The field email must satisfy all constraints:

1. Required (@)
2. Pass the ValidEmail expression ((%ValidEmail))
3. Match the regex pattern (~...~)

Constraint type exclusivity:

Since each constraint type can appear only once per field, (%Name) cannot be combined with other parenthetical constraints like (>0) or (<100). Both use the (...) syntax and occupy the same constraint slot.

// INVALID - two parenthetical constraints
"total|@ (>0) (%ValidTotal)": 120.0

// VALID - numeric check must be inside the expression
"total|@ (%ValidTotal)": 120.0

If you need both a range check and a computed validation, include the range check within the computed expression itself:

"$compute": {
  "ValidTotal": "total > 0 && total == subtotal * (1 + taxRate)"
}

Constraint evaluation order:

1. Type validation (inferred from example)
2. Standard constraints (@, {...}, ~...~)
3. Computed expression validation ((%Name))

C.3.4 Collection Fields - Container and Element Compute

(%Name) can be applied to collection fields (scalar lists, object lists, and maps). When combined with the -> separator (Core §5.2.2), it distinguishes container-level and element-level evaluation:

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

• Before ->: evaluated once on the collection as a whole. it references the collection.
• After ->: evaluated once per element. it references the current element value.

The separation is strict: container constraints are never applied to individual elements, and element constraints are never applied to the collection. Either side is optional.

Container errors are reported on the collection path (e.g., 'scores'); element errors on the element path (e.g., 'scores[0]').

Example:

"scores|@ [*] (%CheckTotal) -> (%CheckElement)": [10, 20, 35]

"CheckTotal": "100 == sum(scores)",
"CheckElement": "it >= 10"

C.4 Evaluation Context

Expressions are evaluated in the context of a JSON object. All fields of the current object are accessible by name.

C.4.1 Object Context

For a field constraint (%ExpressionName), the expression is evaluated in the context of the parent object containing that field.

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

In this example, ValidTotal is evaluated with access to:

• subtotal → 100.0
• taxRate → 0.2
• total → 120.0

Field resolution rules:

• Fields are accessed by name directly: subtotal, taxRate
• Nested field access uses dot notation: address.city
• Missing fields resolve to null
• Accessing a field on a null value returns null (null-safe navigation)

C.4.2 Collection Context (Aggregations)

When using aggregation functions (sum, average, min, max, etc.), the second parameter expression is evaluated for each element in the collection.

{
  "$oky": {
    "order": {
      "items|[1,100]": [
        {"qty": 2, "price": 10.0},
        {"qty": 3, "price": 15.0}
      ],
      "total|(%CheckTotal)": 65.0
    }
  },
  "$compute": {
    "LineTotal": "qty * price",
    "CheckTotal": "total == sum(items, %LineTotal)"
  }
}

In this example:

• LineTotal is evaluated in the context of each item (has access to qty and price)
• CheckTotal is evaluated in the context of order (has access to items and total)
• sum(items, %LineTotal) iterates over items, evaluates %LineTotal for each, and returns the sum

C.4.3 Path Expressions

Expressions support path expressions to access fields beyond the immediate validation context.

Path expression syntax and resolution rules are defined in §6.3.20 Field Path Expressions of the core specification.

Example:

{
  "$compute": {
    "ValidDiscount": "discount <= parent.maxDiscount"
  }
}

C.4.4 The it Variable

When an expression is evaluated as a field constraint ((%Name)), the variable it references the value of the field being validated; as a condition operand (Core §6.3.22), it references the value of the trigger field.

Example:

{
  "$compute": {
    "IsPositive": "it > 0"
  },
  "$oky": {
    "quantity|(%IsPositive)": 10,
    "price|(%IsPositive)": 99.99
  }
}

Scope: it is defined in the constraint expression and propagates to any referenced expression (%Name).

Rebinding inside aggregation lambdas. When an expression is evaluated as the lambda body of an aggregation function (map, filter, countIf, exists, notExists, sumIf, sum, average, min, max), it is rebound to the current iteration element for each evaluation of the body. This rebinding is local to the lambda - once the aggregation completes, it reverts to its outer value (the field being validated).

When the aggregation operates on a scalar collection (numbers, strings, booleans), the lambda body uses it to reference the current scalar element directly:

map([1, 2, 3], it + 10)             // → [11, 12, 13]
filter([1, 2, 3, 4], it > 2)        // → [3, 4]
exists(["a", "b", "c"], it == "b")  // → true
countIf(chars(name), it == "a")     // → number of 'a' characters in name

When the aggregation operates on an object collection, the lambda body references the object’s properties by name (the established 1.4.0 form); it then refers to the current object as a whole and is rarely needed:

map(items, code)                    // existing form (named property)
map(items, toUpperCase(code))       // existing form
filter(items, active == true)       // existing form

Nested collection items. When the iterated element is itself a collection (a list of lists, a map of lists, etc.), it rebinds to that inner collection and can be passed to another aggregation function. This enables explicit nested-collection traversal without an implicit flatten:

sum(map(matrix, sum(it)))           // total of all numbers in a list of lists
map(groups, sum(it))                // sum of each list value of a map of lists
countIf(map(rows, count(it)), it >= 3)   // count rows with at least 3 elements

In each example, the outer lambda iterates the parent collection and it is the inner collection (a list); the inner aggregation then reduces that list. Composition is explicit at every level - Okyline never flattens silently.

In contexts where it is not defined (standalone evaluations outside any constraint or lambda), referencing it resolves to null.

C.4.5 List Iteration Context

When an expression is evaluated inside the lambda of an aggregation function (countIf, exists, notExists, filter, sum, etc.), the following context variables are available in addition to the implicit current element:

All variables support dotted navigation: origin.amount, prev.date, first.id, last.status.

These variables are only defined inside aggregation lambdas. Outside this context, they resolve to null.

Positional predicates:

In addition to the navigation variables above, the following predicates are available inside aggregation lambdas:

These predicates are only defined inside aggregation lambdas. Outside this context, they resolve to null.

Implicit element access vs. origin:

Inside an aggregation lambda, unqualified field names (amount, status) refer to the current iteration element. origin refers to the element whose field constraint triggered the aggregation. These are distinct objects.

Example:

{
  "$compute": {
    "IsUnique": "countIf(parent.items, id == origin.id) == 1"
  },
  "$oky": {
    "items|[*]": [{
      "id|@ (%IsUnique)": "A001"
    }]
  }
}

When validating items[0].id, the expression iterates over all items. For each iteration element, id is the element’s id and origin.id is items[0].id. The count equals 1 only if the id is unique.

C.5 Grammar

C.5.1 Simplified EBNF

expression       ::= conditional
conditional      ::= logical_or ( "?" expression ":" expression )?
logical_or       ::= logical_and ( "||" logical_and )*
logical_and      ::= equality ( "&&" equality )*
equality         ::= comparison ( ("==" | "!=") comparison )*
comparison       ::= addition ( (">" | "<" | ">=" | "<=") addition )*
addition         ::= multiplication ( ("+" | "-") multiplication )*
multiplication   ::= null_coalescing ( ("*" | "/") null_coalescing )*
null_coalescing  ::= unary ( "??" unary )*
unary            ::= ("!" | "+" | "-") primary | primary
primary          ::= ( literal | identifier | compute_ref | function_call | list_literal | "(" expression ")" ) member_access*
member_access    ::= "." identifier
compute_ref      ::= "%" identifier [ "(" [ arguments ] ")" ]
function_call    ::= identifier "(" [ arguments ] ")"
list_literal     ::= "[" [ arguments ] "]"
arguments        ::= expression ( "," expression )*
literal          ::= number | string | boolean | null
identifier       ::= segment ( "." segment )*
segment          ::= ( letter | "_" | "@" | "$" ) ( letter | digit | "_" )*

Unary operators. At most one leading unary operator per operand: !x, -x, +x are valid; !!x, --x, +-x are not. Two additive operators MUST NOT be adjacent (a + -b); parenthesize instead: a + (-b).

Member access. A .identifier postfix retrieves a named field from an object returned by any expression: firstOf(items).amount, %getParty('S').name, findFirst(lines, cat == 'S').id. Dotted paths on bare identifiers (e.g. parent.x.y) are tokenized as a single identifier and resolved via the path-navigation rules of §C.4.3; the member_access postfix only applies when a . follows an expression terminator (), ]) or another member_access. Resolution on a null base yields null. A bare $NAME in an expression is a field name; a nomenclature is referenced as a quoted string, '$NAME' (§C.10.1).

List literals. A bracketed comma-separated sequence of expressions produces an in-memory list. List literals can appear anywhere a value is expected, including as arguments to aggregation functions and to in(). The empty list [] is allowed.

sum([1, 2, 3])                       // → 6
in(status, ["DRAFT", "SENT", "PAID"]) // → true if status is one of the listed values
join(["a", "b", "c"], "-")           // → "a-b-c"
count([])                            // → 0

C.6 Operators

In case of any discrepancy, the operator precedence defined in the grammar (§C.5) MUST take precedence.

C.6.1 Null Coalescing Operator

Precedence: The ?? operator has high precedence, binding tighter than both comparison operators and arithmetic operators.

Short-circuit evaluation: The right operand is not evaluated if the left operand is non-null.

Examples:

// If price is null, use default of 10
finalPrice = price ?? 10

// Chain multiple coalescings
value = a ?? b ?? c ?? 0  // First non-null value or 0

// In arithmetic context
total = (price ?? 0) * (quantity ?? 1)

C.6.2 Equality on Lists and Objects

== and != compare values at every depth, by the nature of the operands:

A member present with the value null is not an absent member: { "a": null } == { } is false.

C.7 Date Functions

C.8 String Functions

C.8.1 String ↔︎ List Functions

These functions bridge strings and lists, enabling expressive transformation pipelines when combined with the aggregation functions on scalar lists (§C.10).

Composability. The identity join(chars(s), "") == s holds for any non-null string. Combined with map/filter over scalar lists, these primitives enable expressive transformations:

// Uppercase each char of a string (equivalent to toUpperCase(s))
join(map(chars(s), toUpperCase(it)), "")

// Count vowels in a string
countIf(chars(name), in(it, ["a","e","i","o","u"]))

// Extract digits and sum them
sum(map(filter(chars(code), it >= "0" && it <= "9"), toNum(it)))

// Split a CSV, keep non-empty fields, rejoin
join(filter(split(csv, ","), it != ""), ",")

C.8.2 String Index Handling

String functions use defensive index handling to prevent runtime errors and ensure deterministic behavior.

Rules

• Negative start indices are clamped to 0.
• Negative lengths are treated as 0 (the result is an empty string).
• A start index greater than the string length returns an empty string.
• End indices beyond the string length are clamped to length().
• Functions never throw exceptions for out-of-bounds access.
• When applicable, functions return safe default values (e.g., empty string "", index -1, etc.).

Examples

substring("Hello", -10, 3)   → "Hel"    // negative start clamped to 0
substring("Hello", 1, -5)    → ""       // negative length treated as 0
substring("Hello", 100, 5)   → ""       // start beyond length → empty
substring("Hello", 1, 999)   → "ello"   // end clamped to string length
substring("Hello", 2, 0)     → ""       // zero length → empty
indexOf("abc", "z")          → -1       // not found
padStart("Hi", 1, "x")       → "Hi"     // already long enough (no truncation)

Notes

• The third parameter of substring(s, start, length) is interpreted as a length, not an end index.
• Negative lengths are not treated as “counting from the end” - they are simply clamped to zero.
• This ensures that all string operations remain null-safe, exception-free, and consistent across implementations.

C.8.3 Format Matching Function - matches

The matches function tests whether a string conforms to a named format - either a $format declared in the contract or an Okyline built-in format. It exposes the same format vocabulary as a field’s ~$Format~ constraint to the expression language.

Form:

Semantics:

• The format reference MUST be a string literal prefixed with $ (mirroring in(value, '$Nomenclature')). A second argument that is not such a literal, or that names a format the contract does not know, MUST be rejected when the schema is loaded.
• $FormatName resolves with the same precedence as a field’s ~$Format~ constraint: a contract $format takes precedence over a built-in of the same name.
• Built-in formats: $Email, $Date, $DateTime, $Time, $Uri, $Ipv4, $Ipv6, $Uuid, $Hostname.
• Returns false when value is null.
• Non-string values are compared by their string form.

Example:

// A field whose value must be a well-formed email
// $compute: { "IsEmail": "matches(it, '$Email')" }
email|@ (%IsEmail)

// Reusing a contract $format
// $format:  { "Code": "^[A-Z]{3}[0-9]{3}$" }
// $compute: { "IsCode": "matches(it, '$Code')" }
reference|@ (%IsCode)

C.9 Numeric Functions

Transcendental functions. sqrt, log, log10, and pow when its exponent is not an integer within ±999, cannot be computed exactly in decimal. Their result is rounded to 15 significant digits before the fixed-point rule of §C.11.1 applies, so that two conforming implementations publish the same value. pow with an integer exponent within ±999 is computed exactly and is not concerned.

Outside their mathematical domain - sqrt of a negative number, log or log10 of zero or of a negative number, pow whose result is not finite - these functions yield null, never an infinity nor an error, consistently with division by zero (§C.11).

C.10 Aggregation & Utility Functions

Aggregation functions operate on collections - JSON arrays, JSON objects used as maps, or list literals (§C.5.1). When the collection contains objects, the lambda expression typically references object properties by name. When the collection contains scalar values (numbers, strings, booleans), the lambda expression references the current element via it (see §C.4.4).

The first argument can be a JSON array, a JSON object used as a map ([*:*]), or any list literal ([...]). For maps, values are iterated; keys are ignored for aggregation purposes.

Scalar vs object collections. When iterating over a scalar collection, the lambda body uses it to reference the current element (see §C.4.4 Rebinding inside aggregation lambdas). When iterating over an object collection, the lambda body references the object’s properties by name (the established 1.4.0 form). Both forms can be mixed in nested aggregations.

// Object collection: existing 1.4.0 form
sum(items, quantity * unitPrice)

// Scalar collection: new 1.5.0 form
sum([10, 20, 30])
sum(map(chars(code), toNum(it)))    // sum of digit characters

// Mixed: scalar lambda inside an object lambda
sum(items, sum(map(chars(reference), toNum(it))))

Note: The %identifier syntax is not a function but a reference operator for accessing compute expressions. See C.10.4 Compute Reference Syntax for details.

C.10.1 Membership Function - in

The in function tests whether a value belongs to a set of allowed values.

Forms:

Semantics:

• Returns true if the value is found in the target set, false otherwise.
• null value → false.
• When the first argument is itself a list, every element of that list must be present in the target (containsAll semantics). An empty list → true.
• Comparison uses the same equality rules as == (§C.6.2).

The inline variadic form in(value, 'A', 'B', 'C') was removed in 1.6.0. Use in(value, ['A', 'B', 'C']).

C.10.2 Lookup Function - lookup

The lookup function retrieves a value from a key/value source by key.

Form:

Semantics:

• Returns the value associated with key in the source, or null if the key is absent.
• null key → null. null source → null. Non-object source → null.
• The returned value is the raw value as it appears in the source (no type coercion). Use toNum, toStr, etc. for explicit conversion.
• Combine with the null-coalescing operator ?? for fallback semantics: lookup(key, src) ?? defaultValue.

Example - char-by-char transformation pipeline:

// Transform each char of a string using a map field, with passthrough for unknown chars
join(map(chars(code), lookup(it, charMap) ?? it), "")

C.10.3 List Element Access

Five functions retrieve a single element from a collection (as opposed to aggregating, filtering, or mapping). They are complementary to filter/map/sum and compose naturally with the member-access postfix (§C.5.1).

Semantics:

• null collection → null; empty collection → null.
• The predicate in findFirst/findLast is evaluated in the item context of §C.4.2 and §C.4.5 (all list-iteration variables are available).
• findLast iterates from the end so it returns on the first match encountered; no full pass when the match is near the tail.
• at(collection, index) (numeric) uses 0-based indexing. Negative indices return null (use lastOf for the last element). On a map, returns the value at that positional offset (insertion order).
• at(map, key) (string) returns the value associated with key, or null if the key is absent. Only valid on a map: at(list, "0") returns null (no implicit String→Integer coercion).
• Returned elements are raw values, composable with the member-access postfix:

firstOf(Lines).Amount > 100
findFirst(Payments, status == 'OK').id
lastOf(Events).timestamp
at(Lines, 0).price == at(Lines, 1).price
findLast(Events, type == 'UPDATE').timestamp

Equivalences:

• at(list, 0) ≡ firstOf(list) when the list is non-empty.
• firstOf(filter(list, pred)) ≡ findFirst(list, pred).
• findFirst(list, true) ≡ firstOf(list) on a non-empty list.

C.10.4 Compute Reference Syntax

Referencing Compute Expressions: %identifier

The %identifier syntax allows expressions to reference other computed expressions defined in the same $compute block.

Syntax:

%<identifier>

Where <identifier> is the name of a compute expression defined in the same $compute block.

Semantics:

• %ComputeName evaluates the expression named ComputeName from the current $compute block
• The % prefix distinguishes compute references from field accesses
• Circular dependencies are detected at schema load time and are a schema error
• References are resolved in the context where the compute expression is evaluated

Examples:

{
  "$compute": {
    "BasePrice": "1000",
    "Tax": "%BasePrice * 0.2",
    "Total": "%BasePrice + %Tax"
  }
}

In this example:

• Tax references BasePrice using %BasePrice
• Total references both BasePrice and Tax using %BasePrice and %Tax
• All references are resolved when the expressions are evaluated

Aggregation Functions:

When using aggregation functions (such as sum, map, filter), the second parameter can be:

• A field reference (direct access to a field in each collection element)
• An inline expression (evaluated for each element)
• A compute reference (using %identifier to reference a compute expression)

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

%Name.field.deep accesses members of the compute’s result. Example: "DocCurrency": "%DocRoot.DocumentCurrencyCode".

Benefits:

• Clear visual distinction between field access (fieldName) and compute references (%ComputeName)
• No ambiguity in aggregation functions
• Consistent with validation constraint syntax (field|(%ComputeName))
• Readable and concise expressions
• Reduces visual noise in complex compute chains

Constraints:

• % must be followed immediately by a valid identifier
• The referenced identifier must exist in the current $compute block
• Circular references are a schema error, detected at schema load time
• Compute references are resolved before evaluation begins

C.11 Evaluation Rules

• Expressions are evaluated in the context of the enclosing object (fields accessible by name).
• Missing fields resolve to null.
• Type coercion MUST NOT be implicit except where explicitly defined by helper functions (toNum, toStr, etc.).
• Division by zero returns null.
• Comparisons with null evaluate to false unless explicitly tested.
• Implementations MUST guarantee deterministic results for the same input; today() is the one function whose result depends on the moment of evaluation.
• Functions MUST NOT have side effects.
• Execution errors SHOULD be reported as a Compute error carrying the expression name and the cause.

C.11.1 Numeric Precision

The Okyline Expression Language guarantees exact decimal arithmetic suitable for financial calculations.

Fixed-point arithmetic. Every numeric value, whether read from the document, written as a literal or produced by an operation, carries at most $decimalScale fractional digits (Core §7.3; 6 when the contract declares none). Every operation whose exact result would need more rounds it to that scale, HALF_UP, before it is used further; operations between integers are exact.

Consequences an author MUST expect:

• + and - are exact and associative: their operands are already at scale.
• * is not associative: a product carries twice the scale and is rounded. At scale 2, (1.11 * 1.11) * 100 yields 123.00 while 1.11 * (1.11 * 100) yields 123.21.
• / rounds, so a quotient does not multiply back into its dividend: (10 / 3) * 3 yields 9.99 at scale 2.
• No IEEE 754 artifact ever appears: 0.1 + 0.2 is exactly 0.3. Implementations MUST NOT carry intermediate results in binary floating point.

Errors are therefore bounded to one unit of the last place per operation, and reproducible: two conforming implementations yield the same result.

Examples (scale 6 unless stated):

0.1 + 0.2                 → 0.3       // exact, not 0.30000000000000004
19.99 * 3                 → 59.97     // exact
100.00 / 3                → 33.333333 // rounded to the scale
1000 * 0.196              → 196       // exact
(1.11 * 1.11) * 100       → 123.00    // scale 2: the product was rounded first
1.11 * (1.11 * 100)       → 123.21    // scale 2: it was not
(10 / 3) * 3              → 9.99      // scale 2: a quotient does not round-trip

Note - choosing the scale. Declare $decimalScale above the precision of the data, so that intermediate products are not rounded away; then, where a business value is defined at fewer decimals than the scale, round explicitly to that precision, round(x, n), before comparing it.

Manual Rounding Control:

When finer control over rounding is required, use the round(x, scale?, mode?) function to explicitly specify the number of decimal places and rounding mode.

// Default: 6 decimals, HALF_UP
total * vatRate                        → 196.000000

// Explicit rounding to 2 decimals for display
round(total * vatRate, 2)              → 196.00

// Banker's rounding (HALF_EVEN) for financial compliance
round(amount, 2, "HALF_EVEN")          → 2.50

// Round down for conservative estimates
round(estimate, 0, "DOWN")             → 99

Available rounding modes: HALF_UP (default), HALF_DOWN, HALF_EVEN, UP, DOWN, CEILING, FLOOR.

When the mode is written as a literal, a name outside these seven MUST be rejected when the schema is loaded. A mode computed at run time - a parameter of a parameterized compute, a field - that is not one of them yields null.

C.11.2 Type Promotion

Type promotion concerns the kind of a value - integer or decimal - as seen by type guards (_Integer_, _Number_), conversions and rendering. It does not change the arithmetic of C.11.1, and 12 == 12.0 holds (C.12.3).

Rules:

Examples:

5 + 7           → 12       // int + int → int
5 + 7.0         → 12.0     // int + decimal → decimal
5.0 + 7.0       → 12.0     // decimal + decimal → decimal
6 / 2           → 3.0      // division always returns decimal
6 * 2           → 12       // int * int → int
6 * 2.0         → 12.0     // int * decimal → decimal

C.12 Null Handling Rules

C.12.1 Arithmetic Operations (Null Propagation)

Arithmetic operations (+, -, *, /) follow three-valued logic (similar to SQL semantics):

• If any operand is null, the result is null (null propagates).
• Exception: String concatenation with + treats null as the empty string "".

Examples:

10 + null     → null
null * 5      → null
null / 2      → null
100 - null    → null

// String concatenation exception
"Hello" + null     → "Hello"
null + " World"    → " World"

C.12.2 Comparison Operations

Comparison operators (<, <=, >, >=) return false if either operand is null.

10 > null      → false
null <= 5      → false
null > null    → false

C.12.3 Equality Operations

Equality operators have specific null handling:

• null == null → true
• null != null → false
• null == <any-value> → false
• null != <any-value> → true

Numeric equality. Numbers carry exactly $decimalScale fractional digits (§C.11.1); == compares them exactly at that scale, with no further rounding. Raising the scale therefore tightens equality: 1.004 == 1.00 holds at scale 2, where both are 1.00, and fails at scale 3. Values that must agree at a coarser precision are compared through round(x, n).

C.12.4 Logical Operations

Boolean operations require boolean operands:

• null is treated as false in boolean contexts.
• Non-boolean values are also treated as false.

null && true   → false
null || true   → true
!null          → true

C.12.5 Function Arguments

Functions handle null arguments according to their specific semantics:

• String functions: Most treat null as empty string "".
• Numeric functions: Most propagate null (return null if input is null).
• Date functions: Null dates typically return null.
• See each function’s documentation for specific behavior.

C.12.6 Field Resolution

• Missing fields resolve to null.
• Accessing a field on a null value returns null (null-safe navigation).

user.address.city  → null  // if user or address is null

Rationale for Null Propagation

The null propagation semantics for arithmetic operations follow SQL/database conventions, where operations involving unknown values (null) produce unknown results (null). This prevents silent calculation errors and makes null handling explicit via the ?? operator.

C.13 Summary

Declaration and Usage

Validation Results

Operator Categories

Function Categories

Null Propagation

C.14 Complete Example

{
  "$version": "1.0.0",
  "$title": "Invoice Schema with Computed Validation",

  "$oky": {
    "invoice": {
      "invoiceId|@ ~$InvoiceId~": "INV-2025-0001",
      "issueDate|@ ~$Date~": "2025-06-15",
      "dueDate|@ ~$Date~ (%DueDateAfterIssue)": "2025-07-15",

      "customer": {
        "name|@ {2,100}": "Acme Corporation",
        "email|@ ~$Email~": "[email protected]"
      },

      "lines|@ [1,100]": [
        {
          "description|@ {2,200}": "Consulting services",
          "quantity|@ (1..1000)": 10,
          "unitPrice|@ (>0)": 150.00,
          "lineTotal|@ (%CheckLineTotal)": 1500.00
        },
        {
          "description|@ {2,200}": "Travel expenses",
          "quantity|@ (1..1000)": 1,
          "unitPrice|@ (>0)": 350.00,
          "lineTotal|@ (%CheckLineTotal)": 350.00
        }
      ],

      "subtotal|@ (%CheckSubtotal)": 1850.00,
      "taxRate|@ (0..0.5)": 0.20,
      "taxAmount|@ (%CheckTaxAmount)": 370.00,
      "total|@ (%CheckTotal)": 2220.00,

      "amountPaid|(>=0)": 0.00,
      "balance|(%CheckBalance)": 2220.00,

      "status|@ ($INVOICE_STATUS)": "DRAFT",

      "$requiredIf status('PAID')": ["paymentDate"],
      "paymentDate|~$Date~": "2025-07-10"
    }
  },

  "$compute": {
    "CheckLineTotal": "lineTotal == round(quantity * unitPrice, 2)",
    "CheckSubtotal": "subtotal == sum(lines, lineTotal)",
    "CheckTaxAmount": "taxAmount == round(subtotal * taxRate, 2)",
    "CheckTotal": "total == subtotal + taxAmount",
    "CheckBalance": "balance == total - (amountPaid ?? 0)",
    "DueDateAfterIssue": "daysBetween(issueDate, dueDate) >= 0"
  },

  "$format": {
    "InvoiceId": "^INV-[0-9]{4}-[0-9]{4}$"
  },

  "$nomenclature": {
    "INVOICE_STATUS": "DRAFT,SENT,PAID,OVERDUE,CANCELLED"
  }
}

Explanation

1. Line-level validation: Each lineTotal must equal quantity × unitPrice (rounded to 2 decimals)
2. Aggregation: subtotal must equal the sum of all lineTotal values
3. Tax calculation: taxAmount validated against subtotal × taxRate
4. Total validation: total must equal subtotal + taxAmount
5. Balance with null safety: Uses ?? to default amountPaid to 0 if null
6. Date validation: dueDate must be on or after issueDate
7. Conditional requirement: paymentDate is required only when status is 'PAID'

Valid Instance

{
  "invoice": {
    "invoiceId": "INV-2025-0042",
    "issueDate": "2025-06-15",
    "dueDate": "2025-07-15",
    "customer": {
      "name": "Tech Solutions Ltd",
      "email": "[email protected]"
    },
    "lines": [
      {
        "description": "Software development",
        "quantity": 40,
        "unitPrice": 125.00,
        "lineTotal": 5000.00
      }
    ],
    "subtotal": 5000.00,
    "taxRate": 0.20,
    "taxAmount": 1000.00,
    "total": 6000.00,
    "amountPaid": 3000.00,
    "balance": 3000.00,
    "status": "SENT"
  }
}

Changelog

• v1.8.0 (2026-09): matches(value, '$Format') string function tests a value against a named format - a contract $format or an Okyline built-in - with the same resolution precedence as a field’s ~$Format~ constraint (§C.8.3). === and !== are withdrawn from the grammar (§C.5.1, §C.6): equality is == / != only. == compares lists element by element and objects member by member, in any member order; a null member is not an absent one (§C.6.2). Transcendental functions round to 15 significant digits and yield null outside their domain (§C.9). A literal rounding mode outside the seven names is a schema error at load time (§C.11.1). A compute key accepts a label after | (§C.2.2). Identifier segments may start with @ or $ (§C.5.1). Arithmetic is fixed-point per operation, and == compares exactly at the scale (§C.11.1, §C.12.3); 1.7.0 described precision-preserving chains and implicit rounding at equality.
• v1.7.0 (2026-05): it rebinds to the inner collection inside an aggregation lambda when the iterated element is itself a list or map, enabling explicit nested-collection traversal such as sum(map(matrix, sum(it))) (§C.4.4). at(map, "key") retrieves a value by string key on a map; at(...) no longer coerces String→Integer, so at(list, "0") returns null (§C.10.3). Grammar: unary operators no longer chain and two additive operators may not be adjacent (§C.5.1).
• v1.6.0 (2026-04): Parameterized computes (§C.2.3) with call syntax %Name(args), parameter scoping rules, and member access on object/list parameters (p.field); list element access functions firstOf, lastOf, findFirst, findLast, at (§C.10.3); member-access postfix expr.field on any expression (§C.5.1); dotted access on compute references %Name.field (§C.10.4); hasValue(v) as strict opposite of isNull (§C.8).
• v1.5.0 (2026-04): List literal syntax [a, b, c] (§C.5); map/filter/countIf/exists/notExists/sumIf on scalar collections with it rebinding (§C.4.4, §C.10); index and size variables in aggregation lambdas (§C.4.5); chars, split, join string ↔︎ list primitives (§C.8.1); lookup function for key-value retrieval (§C.10.2); inline variadic form of in() removed; toNum now preserves arbitrary precision as an exact decimal.
• v1.4.0 (2026-04): List context navigation (origin, prev, next, first, last) and positional predicates (isOrigin, isFirst, isLast); membership function in(); aggregation functions sumIf, map, filter; date functions dayOfWeek, dayOfYear, weekOfYear, quarter, semester, before, after, equals; string functions substringBeforeLast, substringAfterLast, replaceFirst, replaceLast, ltrim, rtrim, removePrefix, removeSuffix, removeRange, indexOfFirst, isNull; short-circuit evaluation for &&/||; revised operator precedence.

End of Annex C - Okyline Expression Language (Normative)