Annex C — Okyline Expression Language (Normative)

Version: 1.2.0 Date: January 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 Okyline 1.2.0 Level 3 conformance (computed business invariants) MUST implement the rules described in this annex.

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.2.0 Draft specification, the expression language defined here is considered stable for practical use.

Non-normative note

The Expression Language can be used independently of validation, for example in documentation tools or template generators, but only the behaviors defined in this annex are considered part of the Okyline 1.2.0 normative model.

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.2.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": {
    ...
  }
}

Example:

{
  "$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 (_)
• Circular dependencies MUST be detected at schema load time and cause a parsing error.
• Expressions are evaluated lazily when referenced.

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.

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:

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

Error reporting SHOULD include:

• Field path (e.g., order.total)
• Expression name (e.g., CheckTotal)
• Evaluated result

C.3.3 Combining with Other Constraints

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

"email|@ (%ValidEmail) ~^[^@]+@[^@]+$~|Contact email": "user@example.com"

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

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). In contexts where it is not defined (aggregations, standalone evaluations), referencing it resolves to null.

C.5 Grammar

C.5.1 Simplified EBNF

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

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.7 Date Functions

C.8 String Functions

C.8.1 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.9 Numeric Functions

C.10 Aggregation & Utility Functions

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

C.10.1 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 result in a validation 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)"
  }
}

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 result in a validation error at schema load time
• Compute references are resolved before evaluation begins

Implementation Note:

The parser transforms %identifier into an internal representation at parse time. The exact internal mechanism is implementation-defined, but the observable behavior must match the semantics described above.

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.
• Functions MUST NOT have side effects.
• Execution errors SHOULD return a structured error (COMPUTE_ERROR, INVALID_ARGUMENT, etc.).

C.11.1 Numeric Precision

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

Guaranteed behaviors:

• Decimal operations are exact within 6 decimal places
• No IEEE 754 floating-point artifacts: 0.1 + 0.2 = 0.3 (exactly)
• Financial calculations produce predictable, auditable results
• Chained operations preserve precision: (0.1 + 0.2) * 3 = 0.9 (exactly)

Examples:

0.1 + 0.2           → 0.3       // exact, not 0.30000000000000004
19.99 * 3           → 59.97     // exact
100.00 / 3          → 33.333333 // rounded to 6 decimals
1000 * 0.196        → 196       // exact

Rationale:

Financial and business applications require deterministic decimal arithmetic. Implementations MUST NOT rely on binary floating-point (IEEE 754) for intermediate calculations, as this produces rounding artifacts unacceptable in financial contexts.

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.

C.11.2 Type Promotion

Arithmetic operations follow standard type promotion rules, preserving the most precise type from the operands.

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

Rationale:

This behavior mirrors standard programming language conventions (Java, Python, SQL) and ensures predictable results. Integer operations remain integers when possible, preserving the semantic meaning of whole numbers.

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 null if either operand is null.

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

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

Note: For numeric equality (==), values are compared with implicit rounding to 6 decimal places using HALF_UP rounding mode.

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

{
  "$okylineVersion": "1.2.0",
  "$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~": "billing@acme.com"
      },

      "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|@ ('DRAFT','SENT','PAID','OVERDUE')": "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": "accounts@techsolutions.com"
    },
    "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"
  }
}

End of Annex C — Okyline Expression Language (Normative)