Designing the UI schema

This page explains how to design the UI Schema used to control layout, grouping, labels, and behaviors of forms in nullplatform. It works together with your JSON Schema, which defines the data structure and validation rules.

💡 The UI schema controls how forms look and how users interact with them.

Where the UI Schema fits

Add a uiSchema object under your specification’s attributes.schema to control layout and behavior.

{
  "attributes": {
    "schema": {
      "type": "object",
      "properties": {
        "name": { "type": "string" }
      },
      "uiSchema": {
        "type": "VerticalLayout",
        "elements": [
          { "type": "Control", "scope": "#/properties/name" }
        ]
      }
    }
  }
}

UI Schema building blocks

UI schemas are built from layout and control elements. These do not change your data model — they only affect how fields render in the UI.

Type	Purpose	Examples
Layouts	Structure and position fields	`VerticalLayout`, `HorizontalLayout`, `Group`, `Categorization`
Controls	Bind UI elements to JSON Schema fields	`Control`, `ListWithDetail`
Display	Read-only presentation	`Label`, `chip`
Rules	Dynamic behavior	`SHOW`, `HIDE`, `APPLY`, `DISABLE`

Scope patterns (JSON Pointer quick reference)

Use JSON Pointers to bind controls to schema fields.

Root property → #/properties/name → data.name
Nested → #/properties/address/properties/street → data.address.street
Array (inside an item editor) → #/properties/name → data.items[i].name

Example:

{ "type": "Control", "scope": "#/properties/address/properties/zipCode" }

Layout elements

Use layouts to organize the form. Layouts don’t bind data; they arrange other elements.

VerticalLayout

Stack children vertically.

{ "type": "VerticalLayout", "elements": [ { "type": "Control", "scope": "#/properties/name" } ] }

HorizontalLayout

Place children in a row (auto‑wraps on small screens).

{ "type": "HorizontalLayout", "elements": [
  { "type": "Control", "scope": "#/properties/firstName" },
  { "type": "Control", "scope": "#/properties/lastName" }
]}

Group

Group related fields with an optional card and title.

{ "type": "Group", "label": "Credentials", "elements": [
  { "type": "Control", "scope": "#/properties/username" },
  { "type": "Control", "scope": "#/properties/password", "options": { "format": "password" } }
]}

Categorization and Category

Render content as tabs or as a stepper.

{
  "type": "Categorization",
  "options": { "variant": "stepper", "showNavButtons": true },
  "elements": [
    { "type": "Category", "label": "General", "elements": [
      { "type": "Control", "scope": "#/properties/name" }
    ]},
    { "type": "Category", "label": "Advanced", "elements": [
      { "type": "Control", "scope": "#/properties/toggles" }
    ]}
  ]
}

Controls (bind to schema properties)

Controls display/edit values defined in your JSON Schema.

Control

Generic control for any property. Common options: label, focus, trim, hideRequiredAsterisk, showUnfocusedDescription.

{ "type": "Control", "scope": "#/properties/email", "label": "Email" }

String controls

Text (single/multi‑line)

{ "type": "Control", "scope": "#/properties/description", "options": { "multi": true } }

Password

{ "type": "Control", "scope": "#/properties/secret", "options": { "format": "password" } }

Enum (select / autocomplete)

{ "type": "Control", "scope": "#/properties/country", "options": { "autocomplete": true, "placeholder": "Select a country" } }

Radio group (inline/stacked)

{ "type": "Control", "scope": "#/properties/plan", "options": { "format": "radio", "direction": "vertical" } }

Radio cards

{ "type": "Control", "scope": "#/properties/plan", "options": { "format": "radio-cards" } }

Chip display for values (mapping supported)

{ "type": "Control", "scope": "#/properties/status", "options": {
  "format": "chip",
  "mapping": {
    "active": { "label": "Active", "color": "success", "icon": "ic:outline-check" },
    "pending": { "label": "Pending", "color": "warning" }
  }
}}

Number / Integer controls

Numeric input / slider

{ "type": "Control", "scope": "#/properties/threshold" }

{ "type": "Control", "scope": "#/properties/volume", "options": { "valueLabelDisplay": "on" } }

Boolean controls

Checkbox / Toggle

{ "type": "Control", "scope": "#/properties/maintenanceMode" }

{ "type": "Control", "scope": "#/properties/notifications", "options": { "toggle": true } }

Date / Time controls

{ "type": "Control", "scope": "#/properties/birthDate", "options": { "dateFormat": "YYYY-MM-DD" } }

{ "type": "Control", "scope": "#/properties/appointmentTime", "options": { "ampm": true } }

{ "type": "Control", "scope": "#/properties/eventDateTime", "options": { "dateTimeFormat": "YYYY-MM-DD HH:mm" } }

anyOf / oneOf controls (select/autocomplete/radio)

{ "type": "Control", "scope": "#/properties/animal", "options": { "autocomplete": true } }

Arrays and tables

Arrays can be rendered in different patterns depending on your UX needs.

Array layout (accordion with per‑item editors)

{ "type": "Control", "scope": "#/properties/contacts", "options": {
  "elementLabelProp": "name",
  "showArrayLayoutSortButtons": true
}}

Table

{ "type": "Control", "scope": "#/properties/products", "options": {
  "showArrayTableSortButtons": true
}}

List with detail (master‑detail)

{ "type": "ListWithDetail", "scope": "#/properties/contacts", "options": { "elementLabelProp": "name" } }

Display (read‑only) patterns

Use display elements to show values without inputs.

{ "type": "Control", "scope": "#/properties/apiKey", "options": { "direction": "row", "icon": "key" } }

Supported displays: text, link (URL), number, boolean, array/object summaries, and oneOf read‑only labels.

Rules (conditional UI)

Rules let you show/hide or enable/disable elements, and with the extended APPLY effect, patch labels/options dynamically.

{
  "type": "Control",
  "scope": "#/properties/ssn",
  "rule": {
    "effect": "SHOW",
    "condition": { "scope": "#/properties/country", "schema": { "const": "USA" } }
  }
}

👉 For complex behavior see Advanced UI Schema.

Common options (quick table)

Option	Type	Use
`showUnfocusedDescription`	boolean	Always show the description (not only on focus)
`hideRequiredAsterisk`	boolean	Hide the * on required labels
`trim`	boolean	Fixed width (e.g., text size by `maxLength`)
`focus`	boolean	Autofocus this element on mount
`elementLabelProp`	string	Property used as item label in arrays
`disableAdd` / `disableRemove`	boolean	Disable add/remove in arrays
`showArrayLayoutSortButtons`	boolean	Sorting arrows for array layout
`showArrayTableSortButtons`	boolean	Sorting arrows for array table
`variant`	string	`stepper` for Categorization; `filled`/`outlined` for chips
`ampm`, `views`, `dateFormat`, `timeFormat`	various	Date/time formats and views

Where the UI Schema fits​

UI Schema building blocks​

Scope patterns (JSON Pointer quick reference)​

Layout elements​

VerticalLayout​

HorizontalLayout​

Group​

Categorization and Category​

Controls (bind to schema properties)​

Control​

String controls​

Number / Integer controls​

Boolean controls​

Date / Time controls​

anyOf / oneOf controls (select/autocomplete/radio)​

Arrays and tables​

Array layout (accordion with per‑item editors)​

Table​

List with detail (master‑detail)​

Display (read‑only) patterns​

Rules (conditional UI)​

Common options (quick table)​