JSON Schema Forms

The JSON Schema Form field provides powerful capabilities for complex data structures that go beyond standard form fields.

When to Use JSON Schema Forms

Use this field type when you need:

• Nested Data Structures: Objects within objects (e.g., an address block inside a company object).
• Arrays of Objects: Lists of items where each item has multiple properties (e.g., a list of employees with name, role, and email).
• Complex Conditional Logic: Fields that appear based on the values of other fields within the same object (using dependencies or oneOf).
• Advanced Validation: Custom regex patterns, complex constraints, or cross-field validation.

Basic Configuration

A JSON Schema Form field requires two main properties:

1. Schema: A JSON object defining the data structure and validation rules (following the JSON Schema standard).
2. UI Schema: A JSON object defining how the fields should be rendered (following the react-jsonschema-form standard).

Example 1: Nested Data

{
  "type": "object",
  "properties": {
    "company": {
      "type": "object",
      "title": "Company Details",
      "properties": {
        "name": { "type": "string", "title": "Company Name" },
        "address": {
          "type": "object",
          "title": "Headquarters",
          "properties": {
            "street": { "type": "string", "title": "Street" },
            "city": { "type": "string", "title": "City" },
            "country": { "type": "string", "title": "Country" }
          }
        }
      }
    }
  }
}

Example 2: Arrays of Objects

{
  "type": "object",
  "properties": {
    "employees": {
      "type": "array",
      "title": "Team Members",
      "items": {
        "type": "object",
        "properties": {
          "name": { "type": "string", "title": "Name" },
          "role": { "type": "string", "title": "Role" },
          "email": { "type": "string", "format": "email", "title": "Email" }
        },
        "required": ["name", "role"]
      }
    }
  }
}

Example 3: Conditional Fields

This example shows how to change the available fields based on a selection.

{
  "type": "object",
  "properties": {
    "employment_status": {
      "type": "string",
      "enum": ["employed", "self-employed", "unemployed"],
      "title": "Employment Status"
    }
  },
  "dependencies": {
    "employment_status": {
      "oneOf": [
        {
          "properties": {
            "employment_status": { "enum": ["employed"] },
            "employer_name": { "type": "string", "title": "Employer Name" },
            "position": { "type": "string", "title": "Position" }
          },
          "required": ["employer_name"]
        },
        {
          "properties": {
            "employment_status": { "enum": ["self-employed"] },
            "business_name": { "type": "string", "title": "Business Name" },
            "years_in_business": {
              "type": "integer",
              "title": "Years in Business"
            }
          }
        }
      ]
    }
  }
}

UI Schema Customization

The UI Schema allows you to control the visual presentation of your fields.

{
  "email": {
    "ui:widget": "email",
    "ui:placeholder": "Enter your email"
  },
  "description": {
    "ui:widget": "textarea",
    "ui:options": {
      "rows": 5
    }
  },
  "subscribe": {
    "ui:widget": "radio"
  },
  "tags": {
    "ui:widget": "checkboxes"
  },
  "color": {
    "ui:widget": "color"
  }
}

Validation

JSON Schema supports robust validation rules:

{
  "type": "object",
  "properties": {
    "age": {
      "type": "integer",
      "minimum": 18,
      "maximum": 120,
      "title": "Age"
    },
    "email": {
      "type": "string",
      "format": "email",
      "title": "Email Address"
    },
    "website": {
      "type": "string",
      "format": "uri",
      "title": "Website"
    },
    "password": {
      "type": "string",
      "minLength": 8,
      "pattern": "^(?=.*[A-Za-z])(?=.*\\d)[A-Za-z\\d]{8,}$",
      "title": "Password"
    }
  }
}

Best Practices

1. Keep it Simple: Only use JSON Schema fields when standard fields cannot meet your requirements.
2. Use Titles: Always provide a title for your properties so they have user-friendly labels.
3. Test Validation: Verify that your validation rules work as expected, including edge cases.