DEV Community

Cover image for Validating lists in Okyline: uniqueness, order, and cross-element rules
Pierre-Michel Bret
Pierre-Michel Bret

Posted on

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

#backend #tutorial #jsonschema #json

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
  }
}
Enter fullscreen mode Exit fullscreen mode

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"
      }
    ]
Enter fullscreen mode Exit fullscreen mode

[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"
    }
Enter fullscreen mode Exit fullscreen mode

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'"
    }
Enter fullscreen mode Exit fullscreen mode

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')"
    }
Enter fullscreen mode Exit fullscreen mode

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)"
Enter fullscreen mode Exit fullscreen mode

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"
  }
}
Enter fullscreen mode Exit fullscreen mode

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.

Top comments (0)