# What are JSON Forms?

JSON Forms help you customize the deployment experience for your customers. They allow you to add one or many custom fields to the [configuration wizard](https://prismatic.io/docs/integrations/config-wizard.md) by defining a JSON schema and UI schema.

With JSON Forms, you can create rich form experiences that go beyond simple text inputs. You can build complex field mappers, multi-step forms with tabs, dynamic dropdowns, and conditional fields that show or hide based on user input.

For hands-on examples, check out the [JSON Forms Playground](https://prismatic.io/docs/jsonforms/playground). Additional examples are available in the JSON Forms project [documentation](https://jsonforms.io/).

## Why use JSON Forms?[​](#why-use-json-forms "Direct link to Why use JSON Forms?")

JSON Forms are particularly useful when you need to:

* **Collect structured data** from your customers during deployment
* **Build field mappers** between your app and third-party systems
* **Create dynamic forms** with conditional fields that adapt to user selections
* **Provide dropdown menus** populated from third-party APIs
* **Validate user input** with custom rules and formats

Instead of using multiple separate config variables, JSON Forms let you group related fields together and create sophisticated form experiences within a single config variable.

## How JSON Forms work[​](#how-json-forms-work "Direct link to How JSON Forms work")

A JSON Form is defined by two main components:

* **Schema**: The data model that describes the shape of data you expect to collect
* **UI schema**: The presentation layer that describes how input fields should be rendered

### Schema: defining your data model[​](#schema-defining-your-data-model "Direct link to Schema: defining your data model")

The schema uses [JSON Schema](https://json-schema.org/) syntax to define the structure and validation rules for your form data.

Here's a simple schema example:

Example JSON Schema

```json
{
  "type": "object",
  "properties": {
    "companyName": {
      "type": "string"
    },
    "companyDescription": {
      "type": "string",
      "description": "You can enter multiple lines here"
    },
    "numEmployees": {
      "type": "integer",
      "description": "Include employees in all offices"
    },
    "continent": {
      "type": "string",
      "enum": [
        "North America",
        "South America",
        "Europe",
        "Asia",
        "Africa",
        "Australia"
      ]
    },
    "biDirectionalSync": {
      "type": "boolean"
    }
  },
  "required": ["companyName"]
}

```

In this schema:

* The form will return an **object** with five properties
* `companyName` is **required**, while other fields are optional
* `companyDescription` is a string field with a helpful description
* `numEmployees` accepts only integer values
* `continent` uses an `enum` to restrict values to a predefined list
* `biDirectionalSync` is a boolean (true/false) field

When a customer completes this form, your integration receives data like this:

Example JSON Form data

```json
{
  "companyName": "Acme Corp",
  "companyDescription": "We make everything",
  "numEmployees": 100,
  "continent": "North America",
  "biDirectionalSync": true
}

```

### UI schema: defining the presentation[​](#ui-schema-defining-the-presentation "Direct link to UI schema: defining the presentation")

The UI schema controls how Prismatic displays and organizes your form fields. It determines the layout, labels, and rendering options for each field.

Here's a UI schema for the form above:

Simple UI Schema

```json
{
  "type": "VerticalLayout",
  "elements": [
    {
      "type": "Control",
      "scope": "#/properties/companyName"
    },
    {
      "type": "Control",
      "scope": "#/properties/companyDescription",
      "options": {
        "multi": true
      }
    },
    {
      "type": "Control",
      "label": "Employee Count",
      "scope": "#/properties/numEmployees"
    },
    {
      "type": "Control",
      "scope": "#/properties/continent"
    },
    {
      "type": "Control",
      "label": "Sync Data Bi-Directionally?",
      "scope": "#/properties/biDirectionalSync"
    }
  ]
}

```

Key UI schema concepts:

* **Layout types**: Organize fields vertically, horizontally, or in groups
* **Control elements**: Reference specific properties from the schema using `scope`
* **Labels**: Override default labels derived from property names
* **Options**: Customize rendering behavior (like `multi: true` for multi-line text)

This combination of schema and UI schema produces a form like this:

![Screenshot of a basic JSON form](/docs/assets/images/basic-form-8ccc4ce937307dff826daab208dbccba.png)

[See example in playground](https://prismatic.io/docs/jsonforms/playground?key=basic)

## Field types in JSON Forms[​](#field-types-in-json-forms "Direct link to Field types in JSON Forms")

JSON Forms support several field types out of the box:

* **String fields**: Plain text inputs
* **Number and integer fields**: Numeric inputs with optional min/max constraints
* **Boolean fields**: Checkboxes or toggle switches
* **Date and time fields**: Date pickers, time pickers, and datetime pickers
* **Dropdown menus**: Using `enum` or `oneOf` for predefined options
* **Arrays**: Repeating sets of fields for collecting multiple items

Time and datetime fields are defined as `string` type with a `format` property:

Date and time field examples

```json
{
  "date": {
    "type": "string",
    "format": "date"
  },
  "time": {
    "type": "string",
    "format": "time"
  },
  "dateTime": {
    "type": "string",
    "format": "date-time"
  }
}

```

## Static vs dynamic JSON Forms[​](#static-vs-dynamic-json-forms "Direct link to Static vs dynamic JSON Forms")

You can implement JSON Forms in two ways:

### Static JSON Forms[​](#static-json-forms "Direct link to Static JSON Forms")

For forms with predefined fields that don't change based on third-party data, you can use the [JSONForms component](https://prismatic.io/docs/components/jsonforms.md) directly. You provide fixed `schema` and `uiSchema` values, and Prismatic renders the form.

### Dynamic JSON Forms[​](#dynamic-json-forms "Direct link to Dynamic JSON Forms")

For forms that need to fetch data from third-party apps (like populating dropdown menus with Salesforce objects or Slack channels), you can build JSON Forms in a custom component. See the [custom component data sources documentation](https://prismatic.io/docs/custom-connectors/data-sources.md#json-forms-data-sources) for details.

## Next steps[​](#next-steps "Direct link to Next steps")

Now that you understand what JSON Forms are and how they work, you can:

* **Learn practical techniques**: See [Using JSON Forms](https://prismatic.io/docs/integrations/data-sources/json-forms/using-json-forms.md) for how-to guides on layouts, arrays, validation, and more
* **Look up schema and UI schema details**: See the [JSON Forms Reference](https://prismatic.io/docs/integrations/data-sources/json-forms/reference.md) for full coverage of the schema, UI schema, renderers, rules, and options Prismatic supports
* **Build a field mapper**: Follow the [Building a Field Mapper Data Source](https://prismatic.io/docs/integrations/data-sources/field-mapping/salesforce-field-mapper.md) tutorial
* **Add custom validation**: Learn about [JSON Form Validation](https://prismatic.io/docs/integrations/data-sources/json-forms/form-validation.md)
* **Explore examples**: Try the [JSON Forms Playground](https://prismatic.io/docs/jsonforms/playground)