Skip to main content

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 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. Additional examples are available in the JSON Forms project documentation.

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​

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​

The schema uses JSON Schema syntax to define the structure and validation rules for your form data.

Here's a simple schema example:

Example JSON Schema
{
  "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 user completes this form, the data returned looks like this:

Example JSON Form data
{
  "companyName": "Acme Corp",
  "companyDescription": "We make everything",
  "numEmployees": 100,
  "continent": "North America",
  "biDirectionalSync": true
}

UI schema: defining the presentation​

The UI schema controls how your form fields are displayed and organized. It determines the layout, labels, and rendering options for each field.

Here's a UI schema for the form above:

Simple UI Schema
{
  "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

See example in playground

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
{
  "date": {
    "type": "string",
    "format": "date"
  },
  "time": {
    "type": "string",
    "format": "time"
  },
  "dateTime": {
    "type": "string",
    "format": "date-time"
  }
}

Static vs dynamic JSON Forms​

You can implement JSON Forms in two ways:

Static JSON Forms​

For forms with predefined fields that don't change based on third-party data, you can use the JSONForms component directly. You provide fixed schema and uiSchema values, and Prismatic renders the form.

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 for details.

Next steps​

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