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.
Top comments (0)