Okyline Annexes Quick Reference

Version: 1.6.0 Date: April 2026 Status: Draft

Companion to the Okyline Core Language Quick Reference. Covers: computed expressions ($compute), internal references ($defs/$ref), and virtual fields ($field).

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

D — Internal References ($defs / $ref)

Okyline supports reusable schema fragments to avoid duplicating the same structure across a document. You define templates once in $defs and reference them with $ref in two modes: property-level (a field whose type comes from a definition) or object-level (an object that includes all fields of a template). Included structures can be adapted with $override, $amend, or $remove.

D.1 Definition Repository — $defs

Declared at root level. Contains reusable schema fragments (objects or scalars):

{
  "$defs": {
    "Address": {
      "street|@ {2,100}": "12 rue du Saule",
      "city|@ {2,100}": "Lyon"
    },
    "Email|~$Email~ {5,100}": "user@example.com",
    "Percentage|(0..100)": 50
  }
}

Rules: First-level entries only (no nested paths). Resolution is case-sensitive.

D.2 Reference Syntax — &Name

&Address    → resolves to "Address" in $defs
&Email      → resolves to "Email" in $defs

↳ & = current document’s definition namespace. Unknown name → schema rejected.

D.3 Property-Level Reference — field | $ref

"address | $ref @": "&Address"

↳ address uses Address schema, required (@ is local)

List of referenced elements:

"addresses | $ref [1,10]": ["&Address"]

↳ Array of 1-10 elements, each validated against Address

Constraint categories:

"primaryEmail | $ref @": "&Email",
"backupEmail | $ref ?": "&Email"

↳ Same Email definition, different structural constraints per usage

D.4 Object-Level Reference — Structural Composition

{
  "$oky": {
    "Person": {
      "$ref": "&Address",
      "name|@ {2,50}": "Dupond"
    }
  }
}

↳ All Address fields injected into Person + local name field added

Rules: - $ref value = single reference string (one template only) - Object-level $ref MUST target an object definition - Object-level cycles → forbidden (detected at load time) - Property-level recursion → allowed - Field collision → must use $override or $amend (otherwise rejected)

D.5 Template Adaptation — $remove

{
  "AnonymousPerson": {
    "$ref": "&Person",
    "$remove": ["email", "ssn"]
  }
}

↳ Includes Person minus email and ssn

Rules: Array of field names. Each must exist in template. NOT permitted when template contains conditional rules or $compute.

D.6 Field Adaptation — $override / $amend

"fieldName | $override <constraints>": <value>
"fieldName | $amend <constraints>": <value>

Invariants preserved by both: field type, collection nature, $ref target.

{
  "Employee": {
    "$ref": "&Person",
    "name | $amend @": "John Doe",
    "salary|@ (>=0)": 3000
  }
}

↳ Person’s name|? {1,50} + $amend @ → effective name|@? {1,50} (added @, kept ? and {1,50})

D.7 Order of Application

1. Template injection — Resolve $ref, inject all fields
2. Removals — Apply $remove
3. Adaptations — Apply $override / $amend
4. Local additions — Add remaining local fields

F — Virtual Fields ($field)

Virtual fields inject computed properties into an object during validation, as if they were present in the JSON data — but they are derived from existing fields, not supplied by the producer. Typical use: compute a tier, a classification, or a flag, then use it as a trigger in conditional directives ($appliedIf, $requiredIf, etc.). They require $compute (Annex C).

F.1 Syntax

{
  "$oky": {
    "order": {
      "$field discountTier": "%CalculateTier",
      "total": 1500.00,
      "$appliedIf discountTier('GOLD')": {
        "loyaltyBonus|@": 50.00
      }
    }
  },
  "$compute": {
    "CalculateTier": "total >= 1000 ? 'GOLD' : 'STANDARD'"
  }
}

↳ discountTier is computed, exists only during validation, used as condition trigger

Syntax: "$field <name>": "%<ComputeName>"

F.2 Rules

• Value MUST be a %Name reference to $compute (no inline expressions)
• Name must not collide with data fields or $appliedIf payload fields
• Must not be used in $requiredIf/$forbiddenIf field lists (they are not data fields)
• Must not be used in IfExist directives (existence doesn’t apply to computed values)
• Declared at object level only, not inside $appliedIf payloads
• Forward references → schema error

F.3 Chaining

Virtual fields evaluate sequentially in declaration order. Each can reference previously declared ones:

"$field subtotal": "%ComputeSubtotal",
"$field tax": "%ComputeTax",
"$field total": "%ComputeTotal"

"ComputeSubtotal": "price * quantity",
"ComputeTax": "subtotal * 0.2",
"ComputeTotal": "subtotal + tax"

↳ tax uses subtotal, total uses both. Order matters.

Evaluation order: Parse → Virtual fields (in order) → Conditional directives → Field constraints

F.4 Usage in Conditionals

Null test: "$requiredIf computedField(null)": ["fallback"]

F.5 Scope

• Local only — visible within declaring object, not in nested objects or array elements
• No inheritance — not carried through $ref inclusion (must redeclare)
• No conflict — same name can be used in parent and child objects independently

F.6 $compute vs $field

Okyline® is a registered trademark of Akwatype.