JSON Schema Explained

tSM forms are driven by JSON Schema, a structured format that defines:

• The data model of a form
• Validation rules (e.g., required fields, formats, constraints)
• The UI layout via extended fields like layout, widget, and config

tSM uses standard JSON Schema v7 as a base and extends it with form-rendering capabilities to bridge data and design in one place.

Core Sections of a Form Schema

{
  "type": "object",
  "properties": {
    "firstName": {
      "type": "string",
      "widget": { "type": "text" }
    }
  },
  "required": ["firstName"],
  "layout": [
    {
      "type": "layout",
      "items": ["firstName"],
      "widget": { "type": "dtl-fluent-section" },
      "config": { "legend": "Enter your name" }
    }
  ]
}

Breakdown

Key	Description
type	Defines the structure: "object" = form with fields
properties	Field definitions: name, type, widget
required	List of fields that must be filled in
layout	UI composition: groupings, tabs, sections
widget	UI rendering type (e.g., text, checkbox, LOV)
config	Extended behavior: visibility, legends, columns, styling, JEXL logic

Field Definition Example

"email": {
  "type": "string",
  "widget": {
    "type": "text",
    "placeholder": "Enter email",
    "validationMessages": {
      "required": "Email is mandatory"
    }
  }
}

• type controls the data
• widget controls the UI
• validationMessages override default error messages

Common Field-Level Properties

Property	Purpose
default	Pre-filled value
readonly	Disables editing
hidden	Hides field entirely
enum	Allowed list of values
minLength, maxLength	Validation for strings
pattern	Regex validation

Layout-Level Configuration

{
  "type": "layout",
  "widget": { "type": "dtl-fluent-columns" },
  "config": {
    "columns": [
      { "width": 6, "content": ["fieldA"] },
      { "width": 6, "content": ["fieldB"] }
    ]
  }
}

• widget defines layout structure
• config sets behavior, such as column widths
• Can include conditionals like config.hidden using JEXL

tSM-Specific Extensions

Field	Description
widget	Defines how the data is rendered in the UI
config	Custom layout logic, styles, conditions, or data sources
layout	Determines grouping and placement of fields and nested blocks

These fields go beyond standard JSON Schema and are interpreted by the tSM form engine.

Advanced: Conditional Display with JEXL

"config": {
  "hidden": "${$context.form.customerType != 'B2B'}"
}

• Dynamically hides a section or field
• Evaluated at runtime using the form's current context

Notes & Best Practices

• Always define type: "object" at the top level
• Use camelCase for field keys
• Keep layout definitions clean and modular
• Don’t repeat layout references (each field once per layout)
• Test hidden/read-only expressions in live preview