# UI Schema Reference

The **UI schema** is a JSON document that describes how to render a [schema](https://prismatic.io/docs/integrations/data-sources/json-forms/reference/schema.md). 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](https://prismatic.io/docs/integrations/data-sources/json-forms/reference/renderers.md). For the full catalog of `options` values, see the [options reference](https://prismatic.io/docs/integrations/data-sources/json-forms/reference/options.md).

## Common properties[​](#common-properties "Direct link to 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](https://prismatic.io/docs/integrations/data-sources/json-forms/reference/options.md)      |
| `rule`     | All elements                            | Conditionally show, hide, enable, or disable - see [rules reference](https://prismatic.io/docs/integrations/data-sources/json-forms/reference/rules.md) |
| `elements` | Layouts and categories                  | Child elements rendered inside this element                                                                                                             |

## `Control`[​](#control "Direct link to control")

A `Control` binds one schema property to an input.

Control

```json
{
  "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](https://prismatic.io/docs/integrations/data-sources/json-forms/reference/options.md) |
| `rule`    | No       | Conditional display - see [rules reference](https://prismatic.io/docs/integrations/data-sources/json-forms/reference/rules.md)           |

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

Array control at the root

```json
{
  "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](https://prismatic.io/docs/integrations/data-sources/json-forms/reference/renderers.md) for the full mapping.

## `VerticalLayout`[​](#verticallayout "Direct link to verticallayout")

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

VerticalLayout

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

```

## `HorizontalLayout`[​](#horizontallayout "Direct link to horizontallayout")

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

HorizontalLayout

```json
{
  "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`[​](#group "Direct link to group")

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

Group

```json
{
  "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`[​](#categorization "Direct link to categorization")

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

Categorization with tabs

```json
{
  "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"`](https://prismatic.io/docs/integrations/data-sources/json-forms/reference/options.md#variant) to render them as a stepper instead, with optional next and previous buttons from [`options.showNavButtons: true`](https://prismatic.io/docs/integrations/data-sources/json-forms/reference/options.md#shownavbuttons):

Categorization as a stepper

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

```

### `Category`[​](#category "Direct link to 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`[​](#label "Direct link to 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](https://prismatic.io/docs/integrations/data-sources/json-forms/form-validation.md)).

Label

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

```

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

## `ListWithDetail`[​](#listwithdetail "Direct link to 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

```json
{
  "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"`](https://prismatic.io/docs/integrations/data-sources/json-forms/reference/options.md#layout) or [`options.layout: "Table"`](https://prismatic.io/docs/integrations/data-sources/json-forms/reference/options.md#layout) instead.

## Arrays without `ListWithDetail`[​](#arrays-without-listwithdetail "Direct link to 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](https://prismatic.io/docs/integrations/data-sources/json-forms/reference/renderers.md#table)
* An `array` with `options.layout: "Accordion"` → [accordion](https://prismatic.io/docs/integrations/data-sources/json-forms/reference/renderers.md#accordion)
* An `array` with `options.layout: "Table"` → [table](https://prismatic.io/docs/integrations/data-sources/json-forms/reference/renderers.md#table) (explicit)
* An `array` of primitives → inline multi-input list

See the [renderers reference](https://prismatic.io/docs/integrations/data-sources/json-forms/reference/renderers.md#arrays) for details on each array renderer.

## Validation mode[​](#validation-mode "Direct link to 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](https://prismatic.io/docs/integrations/data-sources/json-forms/form-validation.md) instead of the schema's built-in messages.

## Data Source Reset[​](#data-source-reset "Direct link to 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](https://prismatic.io/docs/integrations/data-sources/json-forms/using-json-forms.md#configuring-data-source-reset-behavior) for screenshots and a worked example.

## Related pages[​](#related-pages "Direct link to Related pages")

* [Schema reference](https://prismatic.io/docs/integrations/data-sources/json-forms/reference/schema.md)
* [Renderers reference](https://prismatic.io/docs/integrations/data-sources/json-forms/reference/renderers.md)
* [Rules reference](https://prismatic.io/docs/integrations/data-sources/json-forms/reference/rules.md)
* [Options reference](https://prismatic.io/docs/integrations/data-sources/json-forms/reference/options.md)
* [JSON Forms UI schema docs](https://jsonforms.io/docs/uischema/)