DEV Community: Pierre-Michel Bret

Validating lists in Okyline: uniqueness, order, and cross-element rules

Pierre-Michel Bret — Tue, 26 May 2026 15:37:01 +0000

In the previous articles of this series, we introduced Okyline with an e-commerce order, added conditional logic, and covered computed business rules.

This time, we're looking at lists: no duplicate entries by business key, elements in chronological order, rules that depend on what comes before or after, checks that span the whole collection.

We'll use a delivery tracking system as our running example.

The starting point

A simple order with tracking steps:

{
  "$oky": {
    "orderId": "ORD-20250715-042",
    "customer": "Alice Martin",
    "trackingSteps": [
      {
        "step": "CREATED",
        "timestamp": "2025-07-15T08:00:00",
        "location": "Online order"
      }
    ],
    "actualStep": "CREATED",
    "isShipped": false
  }
}

As with the previous articles, this bare JSON wrapped in $oky is already a valid contract. Types are inferred, structure is enforced. But nothing prevents someone from sending two SHIPPED steps, or timestamps in the wrong order, or claiming the order is delivered when no shipment ever happened.

Let's add those rules.

Step 1: No duplicate steps

Each tracking step should appear at most once. You can't have two SHIPPED entries or two DELIVERED entries in the same tracking history.

In JSON Schema, uniqueItems compares entire objects. Two steps with the same name but different timestamps would pass validation, because the objects aren't identical. That's not what we want.

In Okyline, # marks the business key and ! enforces uniqueness by that key:

    "trackingSteps|@ [1,10] -> !|Tracking steps": [
      {
        "step|@ # ($TRACKING_STEP)|Step": "CREATED",
        "timestamp|@ ~$DateTime~|Step timestamp": "2025-07-15T08:00:00",
        "location|@ {2,100}|Location": "Online order"
      }
    ]

[1,10] means 1 to 10 elements. -> ! means each element must be unique. # on step says: uniqueness is determined by this field. Two entries with step: "SHIPPED" will fail validation, regardless of their other fields.

Step 2: Chronological order

Tracking steps must be in chronological order. Each step's timestamp must be later than the previous one.

Okyline provides iteration context variables inside compute expressions. Here, we need isFirst and prev:

    "timestamp|@ ~$DateTime~ (%StepsChronological)|Step timestamp": "2025-07-15T08:00:00",

    "$compute": {
      "StepsChronological": "isFirst || timestamp > prev.timestamp"
    }

isFirst is true for the first element of the array. prev refers to the previous element. So the rule reads: either this is the first step, or its timestamp is after the previous step's timestamp.

If someone sends steps with timestamps out of order, validation fails. The error points to the exact element and the exact rule.

Step 3: Checking the first element of the list

Every delivery tracking starts with a CREATED step. This is a business invariant: you can't pick or ship something that was never created.

Okyline has first, which refers to the first element of the collection:

    "trackingSteps|@ [1,10] (%FirstIsCreated) -> !|Tracking steps": [
      ...
    ],

    "$compute": {
      "FirstIsCreated": "size > 0 && first.step == 'CREATED'"
    }

first.step accesses the step field of the first element. size gives the total number of elements. The compute is attached to the array field itself with (%FirstIsCreated), because it's a rule about the collection, not about a single element. If we attached it to a field inside the element, the check would run once per element, which is unnecessary.

Step 4: Cross-collection checks

The order has an actualStep field that should match the last tracking step. And an isShipped boolean that should be true if and only if a SHIPPED step exists in the list.

These are rules that cross the boundary between a field and a collection. Okyline handles them with lastOf and exists:

    "actualStep|@ (%CheckActualStep)|Current step": "CREATED",
    "isShipped|(%CheckIsShipped)": false,

    "$compute": {
      "CheckActualStep": "actualStep == lastOf(trackingSteps).step",
      "CheckIsShipped": "isShipped == exists(trackingSteps, step == 'SHIPPED')"
    }

lastOf(trackingSteps).step gets the step field of the last element. exists(trackingSteps, step == 'SHIPPED') returns true if any element has step equal to "SHIPPED". The validation ensures that these derived values are consistent with the list content.

If someone adds a SHIPPED step but forgets to update isShipped to true, validation catches it.

Two ways to work with lists

There are two distinct ways to validate a list in Okyline, depending on where you stand.

From the outside: querying the collection

When a compute is attached to a field at the same level as the list (a sibling), the list is a parameter you pass to a function. You're asking questions about the collection as a whole:

Function	What it does	Example from our contract
`lastOf(list)`	Last element	`lastOf(trackingSteps).step`
`firstOf(list)`	First element	`firstOf(trackingSteps).timestamp`
`findFirst(list, pred)`	First match	`findFirst(trackingSteps, step == 'SHIPPED')`
`exists(list, pred)`	Any match?	`exists(trackingSteps, step == 'SHIPPED')`
`notExists(list, pred)`	No match?	`notExists(trackingSteps, step == 'CANCELLED')`
`count(list)`	How many elements	`count(trackingSteps)`
`countIf(list, pred)`	How many match	`countIf(trackingSteps, step == 'SHIPPED')`
`sum(list, field)`	Sum a field	`sum(items, lineTotal)`

This is an extract. The full set includes average, min, max, sumIf, filter, map, and more. map is worth mentioning: it transforms each element and returns a new list, which you can then pass to sum, join, or any other function.

This is the level used by CheckActualStep and CheckIsShipped in our contract. The compute lives on a sibling field and interrogates the list from the outside.

From the inside: exploring from the element being validated

When a compute is attached to a field inside a list element, you're inside the iteration. The engine validates each element in turn, and you can look around:

Variable	Resolves to
`prev`	Element before the current one
`next`	Element after the current one
`first`	First element of the collection
`last`	Last element of the collection
`index`	0-based position of the current element
`size`	Total number of elements
`origin`	The element whose validation triggered the aggregation
`isFirst`	True if current element is first
`isLast`	True if current element is last

This is the level used by StepsChronological: the compute is on timestamp inside the element, and it compares with prev.timestamp. It's also where FirstIsCreated lives, using first.step and size.

Combining both levels

You can also combine both levels. From inside an element, you can query the full collection using exists, countIf, or filter with origin to refer back to the current element.

For example, in a real production contract I use for sewer inspection data (EN 13508-2), each observation has a distance from the start of the pipe. When a continuous defect starts (code 'S'), there must be a matching end (code 'F') with the same observation type at a greater distance:

"CheckSF": "exists(parent.observations, code == 'F' && type == origin.type && distance > origin.distance)"

Here, origin refers to the element currently being validated. So each element is asking its siblings: "does anyone else in this list complete what I started?" — same type, greater distance.

The complete contract

Here's the full delivery tracking contract:

{
  "$oky": {
    "orderId|@ ~$OrderId~|Order identifier": "ORD-20250715-042",
    "customer|@ {2,100}|Customer name": "Alice Martin",
    "trackingSteps|@ [1,10] (%FirstIsCreated) -> !|Tracking steps": [
      {
        "step|@ # ($TRACKING_STEP)|Step": "CREATED",
        "timestamp|@ ~$DateTime~ (%StepsChronological)|Step timestamp": "2025-07-15T08:00:00",
        "location|@ {2,100}|Location": "Online order"
      }
    ],
    "actualStep|@ (%CheckActualStep)|Current step": "CREATED",
    "isShipped|(%CheckIsShipped)": false
  },
  "$compute": {
    "StepsChronological": "isFirst || timestamp > prev.timestamp",
    "FirstIsCreated": "size > 0 && first.step == 'CREATED'",
    "CheckActualStep": "actualStep == lastOf(trackingSteps).step",
    "CheckIsShipped": "isShipped == exists(trackingSteps, step == 'SHIPPED')"
  },
  "$format": {
    "OrderId": "^ORD-[0-9]{8}-[0-9]{3}$"
  },
  "$nomenclature": {
    "TRACKING_STEP": "CREATED, PICKED, PACKED, SHIPPED, IN_TRANSIT, OUT_FOR_DELIVERY, DELIVERED"
  }
}

28 lines. Uniqueness by business key, chronological order, first-element check, cross-collection consistency. All declarative, all in one document.

Try adding a second SHIPPED step, or swapping two timestamps, or setting isShipped to true without a SHIPPED step. Each case produces a clear, targeted error message.

What's next

In the next article, we'll explore virtual fields: computed values that don't exist in the validated payload but can drive conditional logic. Think of a loyalty tier calculated from the order amount, that then determines which fields are required.

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

Paste the contract above, add tracking steps, break the rules. See what happens.

👉 Full documentation and open specification

This is Part 4 of the series Okyline — JSON validation by example. Built by Akwatype.

Computed business rules in Okyline: what JSON Schema cannot validate

Pierre-Michel Bret — Fri, 15 May 2026 14:48:40 +0000

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.

Conditional logic in data contracts: Okyline vs JSON Schema

Pierre-Michel Bret — Tue, 12 May 2026 15:42:20 +0000

In the first article of this series, we introduced Okyline — a JSON validation language where your examples become your schemas. We walked through an e-commerce order, from a bare JSON payload to a fully constrained contract with computed business rules.

This time, we're going deeper into one specific area: conditional logic. The rules that say "this field is required when that field has this value" or "these fields change depending on the variant". The kind of rules every real-world API has, and the kind that turn JSON Schema into something nobody wants to read.

We'll use a hotel reservation as a running example and build the contract step by step.

The starting point

Here's a simplified hotel reservation payload. No constraints yet — just a JSON example wrapped in $oky:

{
  "$oky": {
    "reservationId": "RES-20250615-001",
    "guest": {
      "firstName": "Alice",
      "lastName": "Martin",
      "email": "alice.martin@example.com",
      "phone": "+33612345678"
    },
    "roomType": "SUITE",
    "checkIn": "2025-07-15",
    "checkOut": "2025-07-18",
    "status": "CONFIRMED",
    "paymentMethod": "CARD"
  }
}

As we saw in the first article, this bare example is already a valid contract — the engine infers types from values and validates structure automatically. From here, you can add constraints one field at a time: @ for required, {2,50} for string length, ~$Email~ for format, ($ROOM_TYPE) for enums. We won't repeat all of that here (see Part 1 for the full walkthrough).

Let's assume we've added those basic constraints and jump straight to what this article is about: what happens when your fields depend on each other.

Step 1 — Different room types, different fields

A STANDARD room just has a bed type. A SUITE has a floor and a lounge option. A FAMILY has the number of children and whether extra beds are needed.

In JSON Schema, this requires nested allOf/if/then/else chains. Here's what it looks like — scroll through, you don't need to read it:

{
  "allOf": [
    {
      "if": {
        "properties": {
          "roomType": { "const": "STANDARD" }
        },
        "required": ["roomType"]
      },
      "then": {
        "properties": {
          "bedType": {
            "type": "string",
            "title": "Bed type",
            "examples": ["DOUBLE"],
            "enum": ["SINGLE", "DOUBLE", "TWIN"]
          }
        },
        "required": ["bedType"]
      }
    },
    {
      "if": {
        "properties": {
          "roomType": { "const": "SUITE" }
        },
        "required": ["roomType"]
      },
      "then": {
        "properties": {
          "floor": {
            "type": "integer",
            "title": "Floor number",
            "examples": [12],
            "minimum": 1,
            "maximum": 30
          },
          "hasLounge": {
            "type": "boolean",
            "title": "Lounge included",
            "examples": [true]
          }
        },
        "required": ["floor", "hasLounge"]
      }
    },
    {
      "if": {
        "properties": {
          "roomType": { "const": "FAMILY" }
        },
        "required": ["roomType"]
      },
      "then": {
        "properties": {
          "numberOfChildren": {
            "type": "integer",
            "title": "Number of children",
            "examples": [2],
            "minimum": 1,
            "maximum": 6
          },
          "extraBeds": {
            "type": "boolean",
            "title": "Extra beds needed",
            "examples": [true]
          }
        },
        "required": ["numberOfChildren", "extraBeds"]
      }
    }
  ]
}

That's 70 lines just for the conditional part. Now the same conditional logic in Okyline:

    "roomType|@ ($ROOM_TYPE)|Room type": "SUITE",
    "$appliedIf roomType": {
      "('STANDARD')": {
        "bedType|@ ($BED_TYPE)|Bed type": "DOUBLE"
      },
      "('SUITE')": {
        "floor|@ (1..30)|Floor number": 12,
        "hasLounge|@|Lounge included": true
      },
      "('FAMILY')": {
        "numberOfChildren|@ (1..6)|Number of children": 2,
        "extraBeds|@|Extra beds needed": true
      }
    }

15 lines vs 70. Same fields, same constraints, same labels, same examples, same validation behavior. $appliedIf roomType with three branches — each branch declares the fields that apply to that variant, with their own constraints and examples. You read it top to bottom. A business analyst can follow this without help.

Step 2 — Required fields based on a value

Payment by card requires a card number and an expiry date. Payment by transfer requires an IBAN. Cash requires nothing extra.

    "paymentMethod|@ ($PAYMENT_METHOD)|Payment method": "CARD",
    "cardNumber|{16}|Card number": "4111111111111111",
    "cardExpiry|~^(0[1-9]|1[0-2])/[0-9]{2}$~|Card expiry": "12/26",

    "$requiredIf paymentMethod('CARD')": ["cardNumber", "cardExpiry"]

One line. Pay by card → card number and expiry are mandatory. Other payment methods → these fields can still be present, but they're not required.

And that last point is exactly why we use $requiredIf here instead of $appliedIf. With $appliedIf, the fields only exist inside the branch — they're part of a variant. Here, cardNumber, cardExpiry and iban are always valid fields on a reservation. A system might store them regardless of the payment method. What changes is whether they're mandatory — and that's what $requiredIf expresses.

Step 3 — Forbidden fields based on a value

A PENDING reservation should not have an invoice number or a room key code. You don't invoice what isn't confirmed, and you don't assign a room to a guest who hasn't committed.

This is $forbiddenIf:

    "invoiceNumber|~^INV-[0-9]{6}$~|Invoice number": "INV-042789",
    "roomKeyCode|{8,8}|Room key code": "KEY8A3F2",

    "$forbiddenIf status('PENDING')": ["invoiceNumber", "roomKeyCode"]

One line. If the reservation is pending, these fields must not appear. If someone sends a payload with a room key on a pending reservation, validation catches it immediately.

In JSON Schema, you'd need a conditional block that uses not with required — doable, but not something most developers write correctly on the first try.

Step 4 — At least one of these fields

The guest must provide at least one way to be contacted: email, phone, or WhatsApp. Any combination works, but at least one is mandatory.

This is $atLeastOne:

    "guest|@|Guest information": {
      "firstName|@ {2,50}": "Alice",
      "lastName|@ {2,50}": "Martin",
      "email|~$Email~": "alice.martin@example.com",
      "phone|~^\\+[0-9]{10,15}$~": "+33612345678",
      "whatsapp|~^\\+[0-9]{10,15}$~": "+33612345678",

      "$atLeastOne": ["email", "phone", "whatsapp"]
    }

Notice that email, phone and whatsapp are no longer marked @ (required) individually — they're all optional on their own, but the group constraint ensures at least one is present.

Try expressing this in JSON Schema. You'd need an anyOf with three branches, each testing for the existence of one field, each containing a full required block. It's verbose and fragile.

The complete contract

Here's the full reservation contract with all four conditional mechanisms in place:

{
  "$oky": {
    "reservationId|@ ~$ReservationId~|Reservation identifier": "RES-20250615-001",
    "guest|@|Guest information": {
      "firstName|@ {2,50}": "Alice",
      "lastName|@ {2,50}": "Martin",
      "email|~$Email~": "alice.martin@example.com",
      "phone|~^\\+[0-9]{10,15}$~": "+33612345678",
      "whatsapp|~^\\+[0-9]{10,15}$~": "+33612345678",
      "$atLeastOne": ["email", "phone", "whatsapp"]
    },
    "roomType|@ ($ROOM_TYPE)|Room type": "SUITE",
    "$appliedIf roomType": {
      "('STANDARD')": {
        "bedType|@ ($BED_TYPE)|Bed type": "DOUBLE"
      },
      "('SUITE')": {
        "floor|@ (1..30)|Floor number": 12,
        "hasLounge|@|Lounge included": true
      },
      "('FAMILY')": {
        "numberOfChildren|@ (1..6)|Number of children": 2,
        "extraBeds|@|Extra beds needed": true
      }
    },
    "checkIn|@ ~$Date~|Check-in date": "2025-07-15",
    "checkOut|@ ~$Date~|Check-out date": "2025-07-18",
    "nights|(>=1)|Number of nights": 3,
    "status|@ ($RESERVATION_STATUS)|Reservation status": "CONFIRMED",
    "paymentMethod|@ ($PAYMENT_METHOD)|Payment method": "CARD",
    "cardNumber|{16}|Card number": "4111111111111111",
    "cardExpiry|~^(0[1-9]|1[0-2])/[0-9]{2}$~|Card expiry": "12/26",
    "iban|{15,34}|IBAN": "FR7630006000011234567890189",
    "invoiceNumber|~^INV-[0-9]{6}$~|Invoice number": "INV-042789",
    "roomKeyCode|{8}|Room key code": "KEY8A3F2",

    "$requiredIf paymentMethod('CARD')": ["cardNumber", "cardExpiry"],
    "$requiredIf paymentMethod('TRANSFER')": ["iban"],
    "$forbiddenIf status('PENDING')": ["invoiceNumber", "roomKeyCode"]
  },
  "$format": {
    "ReservationId": "^RES-[0-9]{8}-[0-9]{3}$"
  },
  "$nomenclature": {
    "ROOM_TYPE": "STANDARD, SUITE, FAMILY",
    "BED_TYPE": "SINGLE, DOUBLE, TWIN",
    "RESERVATION_STATUS": "PENDING, CONFIRMED, CHECKED_IN, CANCELLED",
    "PAYMENT_METHOD": "CARD, TRANSFER, CASH"
  }
}

50 lines. Structure, types, enums, conditional fields, forbidden fields, group constraints — all in one readable document. A new developer joining the team can understand the business rules by reading the contract. No need to reverse-engineer code or trace through the 250+ lines of allOf/if/then/else chains that the equivalent JSON Schema would require.

Beyond these four: what else Okyline offers

The conditional directives we covered are the most common, but Okyline provides a complete toolkit. Here are a few more, each shown in one line:

$requiredIfExist — If a companion is listed, their name is required:

"$requiredIfExist companion": ["companionName"]

$exactlyOne — Exactly one form of ID must be provided:

"$exactlyOne": ["passportNumber", "nationalIdNumber", "driverLicenseNumber"]

$allOrNone — Billing address: all fields or none:

"$allOrNone": ["billingStreet", "billingCity", "billingPostalCode", "billingCountry"]

Each of these would take 10-20 lines of JSON Schema. In Okyline, one line, one intent.

What's next

In the next article, we'll tackle something JSON Schema cannot do at all: computed business rules. What if nights must equal the difference between checkOut and checkIn? What if the total price must match the room rate multiplied by the number of nights? These are validation rules every booking system needs, and no schema language except Okyline can express them declaratively.

👉 Try it in the browser — community.studio.okyline.io

No backend. No signup. Paste the contract above, test it with different payloads, break it on purpose.

👉 Full documentation and open specification

Built by Akwatype. Questions or feedback welcome.

Tired of validating data with JSON Schema? We built an alternative

Pierre-Michel Bret — Tue, 05 May 2026 13:25:04 +0000

We've been there. JSON Schema gets hard to write as soon as your payload is non-trivial. Conditional logic, cross-field rules, business invariants, and at some point we stop writing contracts at all. We go code-first, generate the schema from annotations, and end up with 200 lines very few understand, and error messages referencing paths like #/properties/items/allOf/0/then/Then that map to nothing in our mental model.

So we built Okyline. A contract is just an annotated JSON example: you describe your data the way you'd explain it to a colleague. The engine derives all validation automatically.

Here's what progressive adoption looks like in practice, using an e-commerce order as a running example.

Step 1 - Your JSON is already a contract

No syntax to learn. Wrap your payload in $oky and you have a contract:

{
  "$oky": {
    "orderId": "ORD-20250107",
    "customer": {
      "id": 42,
      "email": "alice@example.com"
    },
    "items": [
      {
        "sku": "PRD-00123",
        "quantity": 2,
        "unitPrice": 79.99,
        "lineTotal": 159.98
      }
    ],
    "total": 170.36
  }
}

That's it. The engine infers types from the values, id is an integer, email is a string, unitPrice is a number, items is an array of objects with a specific shape.

What this already gives you: structure validation and type checking on every payload. No missing fields slipping through as null, no string arriving where you expected a number. A whole class of bugs, gone, for zero effort.

Step 2 - Add constraints one field at a time

Annotations go on the field name, not in a separate block. The value stays as the example.

{
  "$oky": {
    "orderId|@ ~$OrderId~|Order identifier": "ORD-20250107",
    "customer|@": {
      "id|@ # (>0)": 42,
      "email|@ ~$Email~": "alice@example.com"
    },
    "items|@ [1,50] -> !": [
      {
        "sku|@ # ~$Sku~": "PRD-00123",
        "quantity|@ (1..999)": 2,
        "unitPrice|@ (>0)": 79.99,
        "lineTotal|(>0)": 159.98
      }
    ],
    "total|@ (>0)": 170.36
  },
  "$format": {
    "OrderId": "^ORD-[0-9]{8}$",
    "Sku": "^[A-Z]{3}-[0-9]{5}$"
  }
}

Reading each field left to right:

orderId|@ ~$OrderId~|Order identifier, required (@), must match the named pattern $OrderId defined in the $format section at the bottom of the contract, labelled "Order identifier".

items|@ [1,50] -> !, required (@), an array of objects, between 1 and 50 items. The -> operator introduces constraints on the elements of the array — here ! means each element must be unique by key fields (#).

That last part matters more than it looks. JSON Schema has uniqueItems: true but it compares whole objects. Two lines with the same SKU but different quantities? JSON Schema considers them unique and lets them through. Your stock gets decremented twice, your invoice is wrong, and no schema violation was reported. With Okyline, same SKU twice → validation error, regardless of the other fields.

quantity|@ (1..999), required, integer between 1 and 999. One line.

The contract still reads like the original payload. A business analyst can follow it. A developer can modify it without reading documentation first.

The core syntax fits on one screen. 9 symbols cover most use cases. The language goes much further when you need it.

Step 3 - Conditional logic that stays readable

Real payloads have variants. A PREMIUM customer has loyalty points and a discount rate. A BUSINESS customer has a company name and a VAT number. In JSON Schema, this means nested allOf/if/then/else chains. In Okyline, it's $appliedIf:

{
  "$oky": {
    "orderId|@ ~$OrderId~|Order identifier": "ORD-20250107",
    "customer|@": {
      "id|@ # (>0)": 42,
      "email|@ ~$Email~": "alice@example.com",
      "type|@ ($CUSTOMER_TYPE)": "PREMIUM",
      "$appliedIf type": {
        "('PREMIUM')": {
          "loyaltyPoints|@ (>=0)": 1500,
          "discountRate|@ (0..30)": 15
        },
        "('BUSINESS')": {
          "companyName|@ {2,100}": "Acme Corp",
          "vatNumber|@ ~$VatNumber~": "FR12345678901"
        }
      }
    },
    "items|@ [1,50] -> !": [
      {
        "sku|@ # ~$Sku~": "PRD-00123",
        "quantity|@ (1..999)": 2,
        "unitPrice|@ (>0)": 79.99,
        "lineTotal|(>0)": 159.98
      }
    ],
    "total|@ (>0)": 170.36
  },
  "$format": {
    "OrderId": "^ORD-[0-9]{8}$",
    "Sku": "^[A-Z]{3}-[0-9]{5}$",
    "VatNumber": "^[A-Z]{2}[0-9]{9,12}$"
  },
  "$nomenclature": {
    "CUSTOMER_TYPE": "STANDARD, PREMIUM, BUSINESS"
  }
}

Two customer types, two branches. You can follow the logic without a whiteboard. Nomenclatures are defined once in $nomenclature and referenced everywhere. When the list of valid customer types changes, you change it in one place.

Step 4 - Business invariants that JSON Schema simply cannot express

This is where JSON Schema stops entirely.

lineTotal must equal quantity * unitPrice. total must equal the sum of all lineTotal across the items array. These are business rules every e-commerce system has. JSON Schema cannot express either of them. You end up with post-validation code, or nothing, and a class of bugs that slips through to production.

In Okyline, two lines in $compute. No new fields, no change to the payload structure:

{
  "$oky": {
    "orderId|@ ~$OrderId~|Order identifier": "ORD-20250107",
    "customer|@": {
      "id|@ # (>0)": 42,
      "email|@ ~$Email~": "alice@example.com",
      "type|@ ($CUSTOMER_TYPE)": "PREMIUM",
      "$appliedIf type": {
        "('PREMIUM')": {
          "loyaltyPoints|@ (>=0)": 1500,
          "discountRate|@ (0..30)": 15
        },
        "('BUSINESS')": {
          "companyName|@ {2,100}": "Acme Corp",
          "vatNumber|@ ~$VatNumber~": "FR12345678901"
        }
      }
    },
    "items|@ [1,50] -> !": [
      {
        "sku|@ # ~$Sku~": "PRD-00123",
        "quantity|@ (1..999)": 2,
        "unitPrice|@ (>0)": 79.99,
        "lineTotal|@ (%LineTotal)": 159.98
      }
    ],
    "total|@ (%Total)": 170.36
  },
  "$format": {
    "OrderId": "^ORD-[0-9]{8}$",
    "Sku": "^[A-Z]{3}-[0-9]{5}$",
    "VatNumber": "^[A-Z]{2}[0-9]{9,12}$"
  },
  "$nomenclature": {
    "CUSTOMER_TYPE": "STANDARD, PREMIUM, BUSINESS"
  },
  "$compute": {
    "LineTotal": "lineTotal == quantity * unitPrice",
    "Total": "total == sum(items, lineTotal)"
  }
}

The engine validates types, constraints, conditions, and computed invariants, all from the same contract. Nothing to wire up separately.

What does this look like in JSON Schema?

Here's the equivalent contract in JSON Schema (draft-07).
It's 143 lines. Scroll through it, you don't need to read it.

You don't have to write this by hand neither. The Okyline Studio Free generates the equivalent JSON Schema automatically from your contract — that's where the 143 lines above come from. Edit a field on the left, watch the JSON Schema update in real time on the right.

{
  "$schema": "http://json-schema.org/draft-07/schema",
  "x-oky-generated-from": "okyline",
  "type": "object",
  "properties": {
    "orderId": {
      "type": "string",
      "title": "Order identifier",
      "examples": ["ORD-20250107"],
      "pattern": "^ORD-[0-9]{8}$"
    },
    "customer": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "examples": [42],
          "exclusiveMinimum": 0,
          "x-oky-keyField": true
        },
        "email": {
          "type": "string",
          "examples": ["alice@example.com"],
          "format": "email"
        },
        "type": {
          "type": "string",
          "examples": ["PREMIUM"],
          "enum": [
            "STANDARD", "PREMIUM", "BUSINESS"
          ]
        }
      },
      "required": [
        "id", "email", "type"
      ],
      "if": {
        "properties": {
          "type": {
            "const": "PREMIUM"
          }
        },
        "required": ["type"]
      },
      "then": {
        "properties": {
          "loyaltyPoints": {
            "type": "integer",
            "examples": [1500],
            "minimum": 0
          },
          "discountRate": {
            "type": "integer",
            "examples": [15],
            "minimum": 0,
            "maximum": 30
          }
        },
        "required": [
          "loyaltyPoints", "discountRate"
        ]
      },
      "else": {
        "if": {
          "properties": {
            "type": {
              "const": "BUSINESS"
            }
          },
          "required": ["type"]
        },
        "then": {
          "properties": {
            "companyName": {
              "type": "string",
              "examples": ["Acme Corp"],
              "minLength": 2,
              "maxLength": 100
            },
            "vatNumber": {
              "type": "string",
              "examples": ["FR12345678901"],
              "pattern": "^[A-Z]{2}[0-9]{9,12}$"
            }
          },
          "required": [
            "companyName", "vatNumber"
          ]
        }
      }
    },
    "items": {
      "type": "array",
      "minItems": 1,
      "maxItems": 50,
      "items": {
        "type": "object",
        "properties": {
          "sku": {
            "type": "string",
            "examples": ["PRD-00123"],
            "pattern": "^[A-Z]{3}-[0-9]{5}$",
            "x-oky-keyField": true
          },
          "quantity": {
            "type": "integer",
            "examples": [2],
            "minimum": 1,
            "maximum": 999
          },
          "unitPrice": {
            "type": "number",
            "examples": [79.99],
            "exclusiveMinimum": 0
          },
          "lineTotal": {
            "type": "number",
            "examples": [159.98],
            "x-oky-compute": "LineTotal"
          }
        },
        "required": [
          "sku", "quantity", "unitPrice", "lineTotal"
        ],
        "additionalProperties": false
      },
      "x-oky-uniqueByKeyFields": true
    },
    "total": {
      "type": "number",
      "examples": [170.36],
      "x-oky-compute": "Total"
    }
  },
  "required": [
    "orderId", "customer", "items", "total"
  ],
  "additionalProperties": false,
  "x-oky-compute-expressions": {
    "LineTotal": "lineTotal == quantity * unitPrice",
    "Total": "total == sum(items, lineTotal)"
  }
}

Done scrolling? Notice the x-oky- fields, x-oky-compute, x-oky-keyField, x-oky-uniqueByKeyFields. Those are Okyline extensions. A standard JSON Schema validator silently ignores them.
The key-field uniqueness, the computed business rules, the cross-field invariants, none of it actually executes. The Okyline contract above is 41 lines and everything executes.

5 errors in the payload: invalid email, missing conditional field, wrong line total, duplicate SKU, wrong order total. All caught, all explained in plain language.

👉 Try it in the browser, community.studio.okyline.io

Running it in Java

The library is free for any use — development, production, commercial products, no limits. No license key, no registration, no usage cap. The license is perpetual and irrevocable for any version you adopt. Zero transitive dependencies. Under 800 KB. Thread-safe. Your schemas remain your intellectual property. Available on Maven Central.

The Okyline language specification itself is open, published under CC BY-SA 4.0. Anyone can implement it independently. You're adopting a format, not just an implementation.

<dependency>
  <groupId>io.akwatype</groupId>
  <artifactId>okyline</artifactId>
  <version>1.6.1</version>
</dependency>

import io.akwatype.okyline.api.OkylineApi;
import java.util.List;

OkylineApi okyline = new OkylineApi();

// Load and compile the contract once
List<String> schemaErrors = okyline.loadSchema(schema);
if (!schemaErrors.isEmpty()) {
    schemaErrors.forEach(System.err::println);
    return;
}

// Validate any payload
List<String> errors = okyline.validate(json);
if (errors.isEmpty()) {
    System.out.println("Valid ✓");
} else {
    errors.forEach(System.err::println);
}

Errors are precise and actionable:

The string 'alice@exa@mple.com' at 'customer.email' does not match okyline built-in validation '$Email'
Field 'customer.loyaltyPoints' must be present due to APPLIED_IF on 'type'
Value: 80.01 at: 'items[1].lineTotal' does not match (%LineTotal) : '80.01 == 80' failed
Object item at 'items[1]' has a duplicate key: PRD-00123
Value: 239.98 at: 'total' does not match (%Total) : '239.98 == 239.99' failed

Where to go from here

The e-commerce example covers Steps 1 through 4. For more complex payloads, IoT sensor streams, booking systems, financial transactions, the gap with JSON Schema widens further. The Studio ships with more than 10 built-in examples ranging from simple to complex, all editable and runnable in the browser.

Okyline is designed for progressive adoption. You stop where your use case stops. Step 1 alone is already useful. Step 4 covers what JSON Schema cannot reach.

👉 Try it in the browser, community.studio.okyline.io

No backend. No signup. Paste your contract, validate your payload, see errors in real time.

👉 Full documentation and open specification, community.okyline.design-hub.okyline.io

Built by Akwatype. Questions or feedback welcome.