JSON Schema Reference

Complete reference for JSON Schema properties and keywords

This guide documents all JSON Schema features supported in Cascade Platform for form validation and UI rendering.

Schema Keywords

Type Keywords


{
  "type": "string"           // string, number, integer, boolean, array, object, null
}

Supported Types:

string - Text values
number - Decimal numbers (float)
integer - Whole numbers
boolean - true/false
array - Lists of items
object - Key-value objects
null - Null value

String Constraints


{
  "type": "string",
  "minLength": 1,           // Minimum length
  "maxLength": 100,         // Maximum length
  "pattern": "^[A-Z]",      // Regex pattern
  "format": "email",        // Predefined format
  "enum": ["a", "b", "c"],  // Allowed values
  "default": "value"        // Default value
}

Keyword	Purpose	Example
`minLength`	Minimum characters	`minLength: 3`
`maxLength`	Maximum characters	`maxLength: 50`
`pattern`	Regex validation	`pattern: "^[0-9]{5}$"`
`format`	Type hint	`format: "email"`
`enum`	Allowed values	`enum: ["a", "b"]`
`default`	Default value	`default: "example"`

Formats:

email - Email address
date - ISO 8601 date (YYYY-MM-DD)
time - ISO 8601 time
datetime - ISO 8601 datetime
uri - URI/URL
hostname - Hostname

Number Constraints


{
  "type": "number",
  "minimum": 0,             // Minimum value (inclusive)
  "maximum": 100,           // Maximum value (inclusive)
  "exclusiveMinimum": 0,    // Minimum (exclusive)
  "exclusiveMaximum": 100,  // Maximum (exclusive)
  "multipleOf": 5           // Must be multiple of
}

Examples:


// Age: 0-150
{"type": "integer", "minimum": 0, "maximum": 150}
 
// Price: > 0, up to 10000
{"type": "number", "exclusiveMinimum": 0, "maximum": 10000}
 
// Quantity: multiple of 5
{"type": "integer", "multipleOf": 5}

Array Keywords


{
  "type": "array",
  "items": {               // Item schema
    "type": "string"
  },
  "minItems": 1,          // Minimum array length
  "maxItems": 100,        // Maximum array length
  "uniqueItems": true     // All items unique
}

Examples:


// List of tags (1-10 items, each string)
{
  "type": "array",
  "items": {"type": "string"},
  "minItems": 1,
  "maxItems": 10,
  "uniqueItems": true
}
 
// Array of objects
{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "id": {"type": "string"},
      "amount": {"type": "number"}
    }
  }
}

Object Keywords


{
  "type": "object",
  "properties": {           // Field definitions
    "name": {"type": "string"},
    "age": {"type": "integer"}
  },
  "required": ["name"],    // Mandatory fields
  "additionalProperties": false  // No extra fields
}

Keyword	Purpose
`properties`	Define object fields
`required`	Which fields are mandatory
`additionalProperties`	Allow/reject extra fields

UI Extension Keywords

These keywords control form rendering (Cascade-specific).

UI Hints


{
  "x-ui-type": "textarea",          // Input type
  "x-ui-rows": 5,                   // Rows (for textarea)
  "x-ui-placeholder": "Enter text", // Placeholder
  "x-ui-help": "Help text",         // Help message
  "x-ui-visible-if": "{{ condition }}", // Conditional display
  "x-ui-disabled-if": "{{ condition }}"  // Conditional disable
}

UI Types:

text - Single-line text (default)
textarea - Multi-line text
number - Number input
date - Date picker
time - Time picker
select - Dropdown
multi-select - Multiple select
checkbox - Checkbox
radio - Radio buttons
file - File upload
tag-input - Tag input

Example: Dynamic Form


{
  "type": "object",
  "properties": {
    "employment_type": {
      "type": "string",
      "enum": ["w2", "contractor"],
      "title": "Employment Type"
    },
    "ssn": {
      "type": "string",
      "title": "Social Security Number",
      "x-ui-visible-if": "{{ form.employment_type === 'w2' }}"
    }
  }
}

Title & Description


{
  "type": "object",
  "title": "Loan Application",
  "description": "Complete this form to apply for a loan",
  "properties": {
    "amount": {
      "type": "number",
      "title": "Requested Amount",
      "description": "Amount in USD"
    }
  }
}

Schema Composition

Using $ref


{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "definitions": {
    "address": {
      "type": "object",
      "properties": {
        "street": {"type": "string"},
        "city": {"type": "string"}
      }
    }
  },
  "type": "object",
  "properties": {
    "home": {"$ref": "#/definitions/address"},
    "work": {"$ref": "#/definitions/address"}
  }
}

Common Patterns

Email Input


{
  "type": "string",
  "format": "email",
  "title": "Email Address"
}


{
  "type": "string",
  "enum": ["option1", "option2", "option3"],
  "x-ui-type": "select",
  "title": "Choose Option"
}

Multi-select


{
  "type": "array",
  "items": {"type": "string", "enum": ["a", "b", "c"]},
  "x-ui-type": "multi-select",
  "title": "Select Items"
}

Nested Object


{
  "type": "object",
  "properties": {
    "applicant": {
      "type": "object",
      "properties": {
        "first_name": {"type": "string"},
        "last_name": {"type": "string"}
      },
      "required": ["first_name", "last_name"]
    }
  }
}

Conditional Field


{
  "type": "object",
  "properties": {
    "has_mortgage": {"type": "boolean"},
    "mortgage_amount": {
      "type": "number",
      "x-ui-visible-if": "{{ form.has_mortgage === true }}"
    }
  }
}

Best Practices

✅ DO:

Use semantic type names
Add descriptions
Set min/max constraints
Use additionalProperties: false
Version schemas
Test with sample data

❌ DON’T:

Mix multiple types
Nest too deeply (>3 levels)
Use overly permissive schemas
Skip validation
Hard-code forms

Updated: October 29, 2025
Version: 1.0
Spec: JSON Schema Draft 7