Conditional Validation with if/then/else

Conditional Validation with if/then/else

The if/then/else keywords enable conditional logic in JSON Schema. Based on whether the data matches the if schema, either the then or else schema is applied as an additional constraint.

Basic Syntax

{
  "if": { /* condition schema */ },
  "then": { /* applied when if matches */ },
  "else": { /* applied when if does not match */ }
}

The if schema is evaluated against the data. If it validates successfully, the then schema is also applied. If it fails, the else schema is applied instead. The else keyword is optional.

How the Example Schema Works

The schema models a shipping form with conditional requirements based on the shipping type:

When shippingType is "international": The if schema matches (the shippingType property equals "international"), so the then schema applies:

• country and customsDeclaration become required.
• customsDeclaration must be exactly true — the shipper must confirm customs compliance.

When shippingType is "domestic": The if schema does not match, so the else schema applies:

• state and zipCode become required instead.

The test data sets shippingType to "international", provides country and customsDeclaration: true, satisfying all then requirements.

Important: if Does Not Reject

A crucial detail: the if schema does not cause validation failure on its own. Even if the data does not match the if condition, the overall validation does not fail — it simply falls through to else. The if keyword is purely a condition selector, not a constraint.

Chaining Multiple Conditions

For more than two branches, use allOf with multiple if/then pairs:

{
  "allOf": [
    {
      "if": { "properties": { "type": { "const": "A" } } },
      "then": { "required": ["fieldA"] }
    },
    {
      "if": { "properties": { "type": { "const": "B" } } },
      "then": { "required": ["fieldB"] }
    }
  ]
}

Each if/then pair is independent, and all are evaluated. This is the JSON Schema equivalent of a switch/case statement.

if/then vs. oneOf

Both can model conditional requirements, but they serve different purposes:

• if/then — best when one field determines the requirements for others. Clearer intent, better error messages.
• oneOf — best when the entire object shape varies between mutually exclusive alternatives. More declarative but harder error messages.