Skip to main content
UI Schema defines the layout and presentation of your form. It describes which elements to render, how to arrange them, and their visual properties.

​
Type hierarchy

​
UISchemaElement

Union type representing all possible UI schema elements.
​
UISchemaElement
BaseUISchemaElement | ControlElement | Layout | LabelElement | GroupLayout | Category | Categorization | VerticalLayout | HorizontalLayout
Base union type for all UI schema elements.

​
BaseUISchemaElement

Common base interface for all UI schema elements.
​
type
string
required
The type of UI schema element (e.g., Control, VerticalLayout, Group).
​
rule
Rule
Optional rule to control visibility or enablement based on data conditions.
​
options
{ [key: string]: any }
Additional configuration options specific to the element or renderer.

​
ControlElement

Represents a single form control bound to a data field.
​
type
'Control'
required
Must be Control.
​
scope
string
required
JSON Pointer to the data field this control is bound to (e.g., #/properties/name).
​
label
string | boolean | LabelDescription
Label configuration. Can be:
  • string: Custom label text
  • boolean: Show/hide label (uses schema title when true)
  • LabelDescription: Object with text and show properties
​
rule
Rule
Rule to dynamically control visibility or enablement.
​
options
{ [key: string]: any }
Renderer-specific options (e.g., { multi: true } for multiline text).
​
i18n
string
Base key for internationalization. Suffixed with .label, .description, etc.

​
Example

const control: ControlElement = {
  type: 'Control',
  scope: '#/properties/email',
  label: 'Email Address',
  options: {
    format: 'email'
  }
};

​
Layout

Base interface for layout elements that contain child elements.
​
type
string
required
Layout type identifier.
​
elements
UISchemaElement[]
required
Array of child UI schema elements.
​
rule
Rule
Rule to control layout visibility or enablement.
​
options
{ [key: string]: any }
Layout-specific options.

​
VerticalLayout

Arranges child elements vertically (top to bottom).
​
type
'VerticalLayout'
required
Must be VerticalLayout.
​
elements
UISchemaElement[]
required
Child elements to arrange vertically.

​
Example

const layout: VerticalLayout = {
  type: 'VerticalLayout',
  elements: [
    {
      type: 'Control',
      scope: '#/properties/firstName'
    },
    {
      type: 'Control',
      scope: '#/properties/lastName'
    }
  ]
};

​
HorizontalLayout

Arranges child elements horizontally (left to right).
​
type
'HorizontalLayout'
required
Must be HorizontalLayout.
​
elements
UISchemaElement[]
required
Child elements to arrange horizontally.

​
Example

const layout: HorizontalLayout = {
  type: 'HorizontalLayout',
  elements: [
    {
      type: 'Control',
      scope: '#/properties/city'
    },
    {
      type: 'Control',
      scope: '#/properties/zipCode'
    }
  ]
};

​
GroupLayout

Vertical layout with an optional label, useful for grouping related fields.
​
type
'Group'
required
Must be Group.
​
label
string
Group heading text.
​
elements
UISchemaElement[]
required
Child elements within the group.
​
i18n
string
Base key for internationalization.

​
Example

const group: GroupLayout = {
  type: 'Group',
  label: 'Personal Information',
  elements: [
    {
      type: 'Control',
      scope: '#/properties/firstName'
    },
    {
      type: 'Control',
      scope: '#/properties/lastName'
    }
  ]
};

​
LabelElement

Displays static text without binding to data.
​
type
'Label'
required
Must be Label.
​
text
string
required
Text content to display.
​
i18n
string
Internationalization key for the label text.

​
Example

const label: LabelElement = {
  type: 'Label',
  text: 'Please fill out all required fields'
};

​
Category

Represents a single category tab within a categorization.
​
type
'Category'
required
Must be Category.
​
label
string
required
Category tab label.
​
elements
UISchemaElement[]
required
Elements to display when this category is active.
​
i18n
string
Base key for internationalization.

​
Categorization

Creates a tabbed interface with categories. Supports nested categorizations for hierarchical navigation.
​
type
'Categorization'
required
Must be Categorization.
​
label
string
required
Categorization label.
​
elements
(Category | Categorization)[]
required
Array of categories or nested categorizations.
​
i18n
string
Base key for internationalization.

​
Example

const categorization: Categorization = {
  type: 'Categorization',
  label: 'User Profile',
  elements: [
    {
      type: 'Category',
      label: 'Personal',
      elements: [
        {
          type: 'Control',
          scope: '#/properties/firstName'
        },
        {
          type: 'Control',
          scope: '#/properties/lastName'
        }
      ]
    },
    {
      type: 'Category',
      label: 'Contact',
      elements: [
        {
          type: 'Control',
          scope: '#/properties/email'
        },
        {
          type: 'Control',
          scope: '#/properties/phone'
        }
      ]
    }
  ]
};

​
LabelDescription

Configuration object for control labels.
​
text
string
Label text to display.
​
show
boolean
Whether to show the label.

​
Rule

Defines conditional logic for showing/hiding or enabling/disabling UI elements.
​
effect
RuleEffect
required
The effect to apply when the condition is met: HIDE, SHOW, ENABLE, or DISABLE.
​
condition
Condition
required
The condition that must evaluate to true to trigger the effect.

​
Example

const rule: Rule = {
  effect: 'SHOW',
  condition: {
    scope: '#/properties/hasAddress',
    schema: { const: true }
  }
};

​
RuleEffect

Enum defining available rule effects.
​
HIDE
'HIDE'
Hides the associated element.
​
SHOW
'SHOW'
Shows the associated element.
​
ENABLE
'ENABLE'
Enables the associated element.
​
DISABLE
'DISABLE'
Disables the associated element.

​
Condition

Union type for all condition types.
​
Condition
BaseCondition | LeafCondition | OrCondition | AndCondition | SchemaBasedCondition | ValidateFunctionCondition
Represents a condition to be evaluated for rules.

​
LeafCondition

Simple condition that compares a data value to an expected value.
​
type
'LEAF'
required
Must be LEAF.
​
scope
string
required
JSON Pointer to the data to evaluate.
​
expectedValue
any
required
The value to compare against.

​
Example

const condition: LeafCondition = {
  type: 'LEAF',
  scope: '#/properties/country',
  expectedValue: 'USA'
};

​
SchemaBasedCondition

Condition that validates data against a JSON Schema.
​
scope
string
required
JSON Pointer to the data to validate.
​
schema
JsonSchema
required
Schema to validate against.
​
failWhenUndefined
boolean
If true, the condition fails when the scope resolves to undefined.

​
Example

const condition: SchemaBasedCondition = {
  scope: '#/properties/age',
  schema: {
    type: 'number',
    minimum: 18
  }
};

​
OrCondition

Condition that passes if any sub-condition passes.
​
type
'OR'
required
Must be OR.
​
conditions
Condition[]
required
Array of conditions to evaluate. Passes if any condition is true.

​
AndCondition

Condition that passes only if all sub-conditions pass.
​
type
'AND'
required
Must be AND.
​
conditions
Condition[]
required
Array of conditions to evaluate. Passes only if all conditions are true.

​
ValidateFunctionCondition

Condition evaluated by a custom validation function.
​
scope
string
required
JSON Pointer to the data to validate.
​
validate
(context: ValidateFunctionContext) => boolean
required
Function that validates the condition. Returns true if the condition is met.

​
ValidateFunctionContext

​
data
unknown
The resolved data scoped to the condition’s scope.
​
fullData
unknown
The complete form data.
​
path
string | undefined
Instance path when the data path cannot be inferred from scope alone.
​
uischemaElement
UISchemaElement
The UI schema element containing the rule.
​
config
unknown
The form configuration.

​
Helper interfaces

​
Scopable

​
scope
string
Optional JSON Pointer to a subschema.

​
Scoped

​
scope
string
required
Required JSON Pointer to a subschema.

​
Labelable

​
label
string | T
Optional label for the UI element.

​
Labeled

​
label
string | T
required
Required label for the UI element.

​
Internationalizable

​
i18n
string
Base key for internationalization messages.

Build docs developers (and LLMs) love

Get started for freeTalk to us