Schema

The JSON Schema defines the data structure, types, and validation rules for dynamic forms. It follows the JSON Schema specification.

Structure

A schema defines an object with properties. Each property specifies its type and validation constraints:

{
  "type": "object",
  "properties": {
    "firstName": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "age": {
      "type": "number"
    }
  },
  "required": ["firstName"]
}

The required array lists properties that must be provided when submitting the form.

Steps

Root-level properties in the schema represent steps — logical groupings of related questions. Each step is an object containing the fields the user needs to complete.

A form with one step:

{
  "type": "object",
  "properties": {
    "personalInfo": {
      "type": "object",
      "properties": {
        "firstName": { "type": "string" },
        "lastName": { "type": "string" }
      }
    }
  }
}

A form with two steps:

{
  "type": "object",
  "properties": {
    "personalInfo": {
      "type": "object",
      "properties": {
        "firstName": { "type": "string" },
        "lastName": { "type": "string" }
      }
    },
    "contactInfo": {
      "type": "object",
      "properties": {
        "email": { "type": "string" },
        "phone": { "type": "string" }
      }
    }
  }
}

Progressive disclosure

Steps enable progressive disclosure — as the user completes one step and submits their answers, the API may return an updated schema with new steps revealed. This means the schema grows dynamically based on previous answers, allowing you to guide users through a multi-step flow without showing all questions upfront.

Types

String

Text values, typically rendered as text inputs.

{
  "type": "string"
}

Number

Numeric values, typically rendered as number inputs.

{
  "type": "number"
}

Boolean

True/false values, typically rendered as checkboxes or toggles.

{
  "type": "boolean"
}

Array

Lists of items, typically rendered as multi-selects or repeatable sections.

{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "country": { "type": "string" },
      "taxId": { "type": "string" }
    }
  },
  "minItems": 1,
  "maxItems": 5
}

Object

Nested structures with their own properties.

{
  "type": "object",
  "properties": {
    "street": { "type": "string" },
    "city": { "type": "string" },
    "postalCode": { "type": "string" }
  }
}

Formats

The format keyword provides semantic meaning to string values.

Date

Date values, typically rendered as date pickers.

{
  "type": "string",
  "format": "date"
}

Validation keywords

String validation

Keyword	Description
minLength	Minimum number of characters
maxLength	Maximum number of characters
pattern	Regular expression the value must match

{
  "type": "string",
  "pattern": "^[A-Z]{2}[0-9]{9}$",
  "minLength": 11,
  "maxLength": 11
}

Array validation

Keyword	Description
minItems	Minimum number of items
maxItems	Maximum number of items
uniqueItems	When true, all items must be unique
contains	At least one item must match the specified schema

{
  "type": "array",
  "minItems": 1,
  "maxItems": 10,
  "uniqueItems": true
}

Enumeration and constants

enum

Restricts a property to a predefined list of allowed values.

{
  "type": "string",
  "enum": ["employed", "self-employed", "retired", "student", "unemployed"]
}

const

Restricts a property to a single fixed value.

{
  "type": "string",
  "const": "agreed"
}

oneOf

Allows a value to match one of several schemas. Often used for conditional validation based on a previous answer.

{
  "oneOf": [
    {
      "properties": {
        "employmentStatus": { "const": "employed" },
        "employerName": { "type": "string" }
      },
      "required": ["employerName"]
    },
    {
      "properties": {
        "employmentStatus": { "const": "self-employed" },
        "businessName": { "type": "string" }
      },
      "required": ["businessName"]
    },
    {
      "properties": {
        "employmentStatus": { "enum": ["retired", "student", "unemployed"] }
      }
    }
  ]
}

In this example, users who select “employed” must provide an employer name, those who select “self-employed” must provide a business name, and other statuses require no additional information.

Next steps

UI Schema

Learn how to render forms with layouts, controls, and rules.

Rendering

Implementation guidance and best practices.