UI Schema Reference

The UI schema is a JSON document that describes how to render a schema. It's a tree of elements - each element has a type that identifies what kind of UI it produces.

This page documents every UI schema element type Prismatic supports, along with properties that apply to every element. For per-renderer behavior, see the renderers reference. For the full catalog of options values, see the options reference.

Common properties

These properties can appear on most UI schema elements:

Property	Applies to	Description
`type`	All elements	Identifies the element kind (`Control`, `VerticalLayout`, and so on)
`scope`	`Control`	JSON Pointer into the schema - typically `#/properties/propertyName`
`label`	`Control`, `Group`, `Category`, `Label`	Overrides the auto-generated label. Set `false` to hide on controls.
`options`	All elements	Object of renderer-specific options - see options reference
`rule`	All elements	Conditionally show, hide, enable, or disable - see rules reference
`elements`	Layouts and categories	Child elements rendered inside this element

`Control`

A Control binds one schema property to an input.

Control
{
  "type": "Control",
  "scope": "#/properties/companyName",
  "label": "Company Name"
}

Property	Required	Description
`scope`	Yes	JSON Pointer referencing the schema property (e.g. `#/properties/name`)
`label`	No	Override the derived label. `false` hides the label.
`options`	No	Renderer-specific options - see options reference
`rule`	No	Conditional display - see rules reference

When the schema is a root array, you can reference the whole array with scope: "#":

Array control at the root
{
  "type": "Control",
  "scope": "#",
  "options": { "showSortButtons": true }
}

JSON Forms picks the renderer for a Control based on the schema type, format, and options at the pointed-to location. See the renderers reference for the full mapping.

`VerticalLayout`

Stacks child elements vertically. This is the most common top-level layout.

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

`HorizontalLayout`

Arranges child elements side by side, splitting horizontal space evenly between them.

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

For n children, each occupies 1/n of the row. Horizontal layouts work best for short inputs that belong together semantically - like a first name and last name, or a date range.

`Group`

A vertical layout with a labeled container around it. Use Group to visually bundle related inputs.

Group
{
  "type": "Group",
  "label": "Address",
  "elements": [
    { "type": "Control", "scope": "#/properties/street" },
    { "type": "Control", "scope": "#/properties/city" }
  ]
}

Property	Required	Description
`label`	Yes	Heading displayed above the group
`elements`	Yes	Child elements rendered inside the group

`Categorization`

Splits the form into multiple tabbed or stepped pages. A Categorization contains only Category elements.

Categorization with tabs
{
  "type": "Categorization",
  "elements": [
    {
      "type": "Category",
      "label": "Contacts",
      "elements": [{ "type": "Control", "scope": "#/properties/contacts" }]
    },
    {
      "type": "Category",
      "label": "Leads",
      "elements": [{ "type": "Control", "scope": "#/properties/leads" }]
    }
  ]
}

By default, categories render as tabs at the top of the form. Set options.variant: "stepper" to render them as a stepper instead, with optional next and previous buttons from options.showNavButtons: true:

Categorization as a stepper
{
  "type": "Categorization",
  "elements": [
    {
      "type": "Category",
      "label": "Step 1",
      "elements": [
        /* ... */
      ]
    },
    {
      "type": "Category",
      "label": "Step 2",
      "elements": [
        /* ... */
      ]
    }
  ],
  "options": {
    "variant": "stepper",
    "showNavButtons": true
  }
}

`Category`

Contained by a Categorization. Represents one tab or step.

Property	Required	Description
`label`	Yes	Tab or step label
`elements`	Yes	Child elements rendered in this category
`rule`	No	Hide or disable the category conditionally

`Label`

Renders static text in the form. Useful for inline instructions, separators, or validation messages generated by a downstream data source (see JSON Form Validation).

Label
{
  "type": "Label",
  "text": "Enter your primary contact information below."
}

Property	Required	Description
`text`	Yes	Text to display
`rule`	No	Conditional display

`ListWithDetail`

Renders an array as a master list on the left and a per-item detail form on the right. Use it when the array has many fields per item and you want the customer to focus on one item at a time.

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

Property	Required	Description
`scope`	Yes	JSON Pointer to the array property
`options`	No	`options.detail` controls the detail UI schema

For lighter-weight array rendering, use a Control scoped to the array and set options.layout: "Accordion" or options.layout: "Table" instead.

Arrays without `ListWithDetail`

You'll usually render arrays with a plain Control, not ListWithDetail. Prismatic chooses the default array renderer based on the schema and options:

An array of objects with no options.layout → table
An array with options.layout: "Accordion" → accordion
An array with options.layout: "Table" → table (explicit)
An array of primitives → inline multi-input list

See the renderers reference for details on each array renderer.

Validation mode

You set Validation Mode on the config variable in the integration designer, not in the UI schema itself. It controls when schema-generated validation errors appear to the customer.

Mode	Description
`ValidateAndShow`	Validates input and displays errors. This is the default.
`ValidateAndHide`	Validates input and emits errors to the form, but does not display them.
`NoValidation`	Skips validation entirely.

Use ValidateAndHide when you want to rely on a custom validator data source instead of the schema's built-in messages.

Data Source Reset

Data Source Reset is a Prismatic setting on the config variable, not a JSON Forms feature.

When a JSON Forms data source re-runs (for example, because an upstream connection or parameter changed), the config variable may already contain data the customer entered previously. Data Source Reset controls how Prismatic reconciles the new default data with the existing customer data:

Mode	Behavior
`never`	Prismatic preserves the customer's existing data and ignores new defaults. This is the default.
`prompt`	Prismatic asks the customer whether to reset the form to the new defaults.
`always`	Prismatic overwrites the customer's data with the new defaults automatically.

See Configuring data source reset behavior for screenshots and a worked example.

Common properties​

Control​

VerticalLayout​

HorizontalLayout​

Group​

Categorization​

Category​

Label​

ListWithDetail​

Arrays without ListWithDetail​

Validation mode​

Data Source Reset​

Related pages​