Computed business rules in Okyline: what JSON Schema cannot validate

In the first article of this series, we introduced Okyline with an e-commerce order. In the second, we added conditional logic on a hotel reservation.

This time, we're tackling something different: validating that computed values in your payload are actually correct. The goal is to validate the business invariants that depend solely on the data to be validated.

Think about it. Does lineTotal really equal quantity × unitPrice? Does totalAmount match the sum of all line totals with tax applied? Every invoice system has these rules, but they almost never live in the data contract. They end up as handwritten checks buried in the code, duplicated across services, and nobody remembers which version is the right one.

Okyline has $compute.

The starting point

Back to e-commerce. Here's a simple invoice payload:

{
  "$oky": {
    "invoiceId": "INV-2025-001",
    "items": [
      {
        "sku": "WIDGET-42",
        "description": "Standard Widget",
        "quantity": 3,
        "unitPrice": 29.99,
        "lineTotal": 89.97
      }
    ],
    "totalBeforeTax": 89.97,
    "taxRate": 0.2,
    "totalAmount": 107.96
  }
}

As it stands, nothing prevents someone from sending lineTotal: 9999 with quantity: 3 and unitPrice: 29.99. The contract would accept it without blinking.

Step 1: Validating a line total

Each line item has a lineTotal that should equal quantity × unitPrice. Here's how you express that:

    "items|@ [1,50] → !|Invoice lines": [
      {
        "sku|@ #|SKU": "WIDGET-42",
        "description|@ {1,200}|Description": "Standard Widget",
        "quantity|@ (1..999)|Quantity": 3,
        "unitPrice|@ (>0)|Unit price": 29.99,
        "lineTotal|@ (%CheckLineTotal)|Line total": 89.97
      }
    ],

    "$compute": {
      "CheckLineTotal": "lineTotal == quantity * unitPrice"
    }

(%CheckLineTotal) on the field tells the engine to validate it using that compute rule. The rule is a boolean expression: false means validation fails.

One thing to note: the compute runs in the context of the current line item. So quantity, unitPrice, and lineTotal refer to that specific item's values. Ten items in the array? The rule runs ten times.

Step 2: Summing across a list

Now, does totalBeforeTax actually match the sum of all line totals?

    "totalBeforeTax|@ (%CheckTotalBT)|Total before tax": 89.97,

    "$compute": {
      "CheckLineTotal": "lineTotal == quantity * unitPrice",
      "CheckTotalBT": "totalBeforeTax == sum(items, lineTotal)"
    }

sum(items, lineTotal) does what you'd expect: iterate over items, sum up lineTotal. No loop to write, no accumulator variable.

Step 3: Total with tax

The total amount should equal totalBeforeTax × (1 + taxRate):

    "taxRate|@ (0.05,0.15,0.2)|Tax rate": 0.2,
    "totalAmount|@ (%CheckTotal)|Total amount": 107.96,

    "$compute": {
      "CheckLineTotal": "lineTotal == quantity * unitPrice",
      "CheckTotalBT": "totalBeforeTax == sum(items, lineTotal)",
      "CheckTotal": "totalAmount == totalBeforeTax * (1 + taxRate)"
    }

Three rules, three invariants. If any of them fails, the validation error tells you which rule and which field.

Step 4: Reusing computes with references

Notice that the expression quantity * unitPrice appears in both CheckLineTotal and could be needed again in CheckTotalBT. Instead of duplicating it, you can define it once and reference it using %:

    "$compute": {
      "LineAmount": "quantity * unitPrice",
      "CheckLineTotal": "lineTotal == %LineAmount",
      "CheckTotalBT": "totalBeforeTax == sum(items, %LineAmount)",
      "CheckTotal": "totalAmount == totalBeforeTax * (1 + taxRate)"
    }

Now sum(items, %LineAmount) evaluates quantity * unitPrice for each item and sums the results. The validation checks against what the values should be, not what they claim to be. Combined with CheckLineTotal, you get two independent checks that catch different categories of errors.

The decimal precision problem

If you've worked with money in code, you know this one:

0.1 + 0.2 = 0.30000000000000004

IEEE 754 floating-point. JavaScript, Python, Java, they all do it. The problem is direct: 29.99 * 3 might return 89.96999999999999 instead of 89.97, and your lineTotal == quantity * unitPrice check fails on perfectly correct data.

Okyline uses exact decimal arithmetic, designed for financial-grade calculations (6 decimal places by default, adjustable to 8, 10 or more as needed). 0.1 + 0.2 equals 0.3, as you'd expect from a calculator. No epsilon comparison, no rounding hacks. When you write lineTotal == quantity * unitPrice, it just works.

If you deal with money, this alone is worth paying attention to.

The JSON Schema comparison

There isn't one.

JSON Schema cannot express lineTotal == quantity * unitPrice. It has no way to compute sums across arrays or validate relationships between fields. The spec wasn't designed for this.

So what do teams do? They write custom validation code, scatter it across services, sometimes test it, sometimes don't. Or they just trust the data and deal with the consequences.

With $compute, these rules are in the contract. Documented, versioned, enforced. When the tax formula changes, you update one line in the schema instead of hunting through three microservices.

The complete contract

Here's the full invoice contract with all compute rules in place:

{
  "$oky": {
    "invoiceId|@ ~$InvoiceId~|Invoice identifier": "INV-2025-001",
    "invoiceDate|@ ~$Date~|Invoice date": "2025-06-15",
    "items|@ [1,50] → !|Invoice lines": [
      {
        "sku|@ #|SKU": "WIDGET-42",
        "description|@ {1,200}|Description": "Standard Widget",
        "quantity|@ (1..999)|Quantity": 3,
        "unitPrice|@ (>0)|Unit price": 29.99,
        "lineTotal|@ (%CheckLineTotal)|Line total": 89.97
      }
    ],
    "totalBeforeTax|@ (%CheckTotalBT)|Total before tax": 89.97,
    "taxRate|@ (0.05,0.15,0.2)|Tax rate": 0.2,
    "totalAmount|@ (%CheckTotal)|Total amount": 107.96
  },
  "$compute": {
    "CheckLineTotal": "lineTotal == quantity * unitPrice",
    "LineAmount": "quantity * unitPrice",
    "CheckTotalBT": "totalBeforeTax == sum(items, %LineAmount)",
    "CheckTotal": "totalAmount == totalBeforeTax * (1 + taxRate)"
  },
  "$format": {
    "InvoiceId": "^INV-[0-9]{4}-[0-9]{3}$"
  }
}

30 lines. Structure, types, constraints, and business rules all in one place. Try changing totalAmount to 999.99 in the Studio and you'll see CheckTotal fail with a clear message pointing to the exact field.

Going further: IBAN validation in pure declarative

Invoice math is the obvious use case for $compute, but the expression language can do much more. Here's one which I find really interesting: full IBAN validation using the ISO 7064 modulo-97 algorithm.

The standard check works like this: move the first 4 characters to the end, convert letters to numbers (A=10, B=11, ... Z=35), verify that the result modulo 97 equals 1, and check that the first 2 characters match a valid ISO 3166 country code.

{
  "$oky": {
    "name": "BNP PARIBAS",
    "IBAN|(%CheckIBANFull)": "FR7630004000031234567890143"
  },
  "$nomenclature": {
    "COUNTRY_ISO3166_15": "DE,FR,GB,ES,IT,NL,BE,CH,SA,AE,MA,BR,TR,PL,LU",
    "IbanLetters": "A:10,B:11,C:12,D:13,E:14,F:15,G:16,H:17,I:18,J:19,K:20,L:21,M:22,N:23,O:24,P:25,Q:26,R:27,S:28,T:29,U:30,V:31,W:32,X:33,Y:34,Z:35"
  },
  "$compute": {
    "IbanRearranged": "substring(IBAN, 4, 99) + substring(IBAN, 0, 4)",
    "IbanEncoded": "join(map(chars(%IbanRearranged), lookup(it, '$IbanLetters') ?? it), '')",
    "CheckIBANFull": "mod(%IbanEncoded, 97) == 1 && in(substring(IBAN, 0, 2), '$COUNTRY_ISO3166_15')"
  }
}

Step by step:

IbanRearranged moves the country code and check digits to the end.
IbanEncoded converts each character: letters get their numeric value via lookup in the nomenclature, digits stay as-is (the ?? it fallback). Everything is joined into one numeric string.
CheckIBANFull does the mod-97 check and verifies the country code.

Three computes, zero code, full IBAN validation. Change one digit and it fails. This kind of rule usually lives in a utility class somewhere, copy-pasted between projects. Here it's in the contract where everyone can see it.

What's next

In the next article, we'll look at list validation: uniqueness by key fields, iteration with prev, next, first, last, and rules like "each date must come after the previous one".

👉 Try it now: community.studio.okyline.io

Paste the contract above, change the amounts, break the rules. See what happens.

👉 Full documentation and open specification

This is Part 3 of the series Okyline - JSON validation by example. Built by Akwatype.

推荐订阅源

DEV Community