Conditionals

Conditionals resolve a prop value by evaluating a condition and choosing a branch.

If/Then/Else

Binary conditional based on schema validation:

{
  "$if": { "$data": "/type" },
  "$matches": { "const": "business" },
  "$then": "Business",
  "$else": "Personal"
}

Required

• $if (expression): The value to test.
• $then: Value to use if the condition matches. Any value the prop accepts, including nested conditionals and maps.

Optional

• $matches (JSON Schema, draft 2020-12): The condition the tested value must match. When omitted, the condition matches when the value is exactly true (equivalent to { "const": true }).
• $else: Value to use if the condition does not match. Any value the prop accepts, including nested conditionals and maps.

Behavior

The subject is resolved, then validated against the condition. Format keywords assert: { "format": "email" } matches only well-formed emails. On a match the conditional resolves to $then, otherwise to $else; with no $else it resolves to undefined and the prop is treated as omitted. Only the selected branch is resolved: the untaken branch is never evaluated.

Examples

Conditional prop value:

{
  "type": "button",
  "props": {
    "label": {
      "$if": { "$data": "/type" },
      "$matches": { "const": "business" },
      "$then": "Business",
      "$else": "Personal"
    }
  }
}

Boolean condition, $matches omitted:

{
  "type": "text",
  "props": {
    "children": {
      "$if": { "$data": "/isVerified" },
      "$then": "Verified"
    }
  }
}

Conditional nested elements:

{
  "type": "section",
  "props": {
    "children": {
      "$if": { "$data": "/type" },
      "$matches": { "const": "business" },
      "$then": [
        { "type": "text", "props": { "children": "Company Name" } },
        { "type": "text", "props": { "children": "Tax ID" } }
      ],
      "$else": [{ "type": "text", "props": { "children": "Full Name" } }]
    }
  }
}

Switch/Case/Default

Multi-case conditional:

{
  "$switch": { "$data": "/frequency" },
  "$case": {
    "daily": "You will receive daily digest emails",
    "weekly": "You will receive weekly digest emails"
  },
  "$default": "You will receive monthly digest emails"
}

Required

• $switch (expression): The value to discriminate on.
• $case (object): Maps case values to any value the prop accepts, including nested conditionals and maps.

Optional

• $default: Value to use if no case matches. Any value the prop accepts, including nested conditionals and maps.

Behavior

The subject expression is resolved and compared against the case keys by its string representation: a string matches itself, a number its decimal form (the number 2 matches the key "2"), a boolean or null its literal ("true", "null"). Documents SHOULD only switch on subjects of those types; matching for objects and arrays is undefined. The matching case's value is used, or $default when no key matches. Only the selected value is resolved; with no matching case and no $default, the conditional resolves to undefined and the prop is treated as omitted.

Example

{
  "type": "text",
  "props": {
    "children": {
      "$switch": { "$data": "/theme" },
      "$case": {
        "light": "Light mode active",
        "dark": "Dark mode active"
      }
    }
  }
}