Cheat Sheet

Use the cheat sheet to determine how you could configure the data and UI schemas to render specific form elements.

Note: in some UI schemas you will see “ComponentProps” in the options element. Component props are passed directly to the underlying Design Systems components to alter their behaviour, See their documentation for a complete list of properties that can be managed this way.

TOC

Common data formats

Here are some out-of-the-box formats that not only render with the correct input widget, but ensure that the data provided by users is valid.

Format JSON schema UI schema
Date 

{
  "dateOfBirth": {
    "type": "string",
    "format": "date"
  }
}
    

{
  "type": "Control",
  "scope": "#/properties/dateOfBirth",
}
Integer 

{
  "numberOfChildren": {
    "type": "integer"
  }
}
    

{
  "type": "Control",
  "scope": "#/properties/numberOfChildren",
  "options": {
    "componentProps": {
      "min": 10,
      "max": 200,
      "step": 5
    }
  }
}
Number 

{
  "averageYearlyRainfall": {
    "type": "number"
  }
}
    

{
  "type": "Control",
  "scope": "#/properties/averageYearlyRainfall"
}
Limited Text 

{
  "firstName": {
    "type": "string"
  }
}
    

{
  "type": "Control",
  "scope": "#/properties/firstName"
}
Text Box 

{
  "reasonForApplying": {
    "type": "string"
  }
}
    

{
  "type": "Control",
  "scope": "#/properties/reasonForApplying"
  "options": {
  "multi": true,
  "componentProps": {
    "rows": 10,
    "placeholder": "multi line input"
    }
  }
}
Boolean (yes,no) 

{
  "isOver18": {
    "type": "boolean"
  }
}
    

{
  "type": "Control",
  "scope": "#/properties/isOver18"
  "label": "Are you over 18 years of age?",
  "options": {
    "format": "radio",
    "textForTrue": "Yes",
    "textForFalse": "No"
  }
}

Selectors

For when the user must select from a limited set of answers.

Feature JSON schema UI schema
Dropdown menu 

{
  "colour": {
    "type": "string",
    "enum": ["red", "blue", "green"]
  }
}
    

{
  "type": "Control",
  "scope": "#/properties/colour"
  "label": "What's your favorite colour?",
}
Radio Button 

{
  "colour": {
    "type": "string",
    "enum": ["red", "blue", "green"]
  }
}
    

{
  "type": "Control",
  "scope": "#/properties/colour",
  "label": "What's your favorite colour?",
  "options": {
    "format": "radio",
    "componentProps": {
      "orientation": "horizontal"
    }
  }
}
Checkbox 

{
  "colour": {
    "type": "string",
    "enum": ["red", "blue", "green"]
  }
}
    

{
  "type": "Control",
  "scope": "#/properties/colour",
  "label": "What are your favorite colours?",
  "options": {
    "format": checkbox,
    "componentProps": {
      "orientation": "vertical"
    }
  }
}

Form Layout

Layouts let you organize input fields they way you want them. You can lay out the fields in rows (horizontally), in columns (vertically), or in a mixture of both.

Feature JSON schema UI schema
Vertical Layout (columns) 

{
  "type": "object",
  "properties": {
    "firstName": {
      "type": "string"
    },
    "lastName": {
      "type": "string"
    }
  }
}
    

{
  "type": "VerticalLayout",
  "elements": [
    {
      "type": "Control",
      "scope": "#/properties/firstName"
    },
    {
      "type": "Control",
      "scope": "#/properties/lastName"
    }
  ]
}
Horizontal Layout (rows) 

{
  "type": "object",
  "properties": {
    "firstName": {
      "type": "string"
    },
    "lastName": {
      "type": "string"
    }
  }
}
    

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

{
  "type": "object",
  "properties": {
    "firstName": {
      "type": "string"
    },
    "lastName": {
      "type": "string"
    },
    "reasonForLeaving": {
      "type": "string"
    }
  }
}
    

{
  "type": "VerticalLayout",
  "elements": [
    {
      "type": "HorizontalLayout",
      "elements": [
        {
          "type": "Control",
          "scope": "#/properties/firstName"
        },
        {
          "type": "Control",
          "scope": "#/properties/lastName"
        }
      ]
    },
    {
      "type": "Control",
      "scope": "#/properties/reasonForLeaving",
      "options": {
        "multi": true
      }
    },
  ]
}
Groups 

{
  "type": "object",
  "properties": {
    "firstName": {
      "type": "string"
    },
    "lastName": {
      "type": "string"
    },
    "initial": {
      "type": "string",
      "maxLength": 1
    }
  }
}
    

{
  "type": "Group",
  "label": "Group Name",
  "elements": [
    {
      "type": "Control",
      "scope": "#/properties/firstName"
    },
    {
      "type": "Control",
      "scope": "#/properties/lastName"
    },
    {
      "type": "Control",
      "scope": "#/properties/initial"
    },
  ]
}

Instructional Content

For when you need to add instructions, or help, to guide users when they are filling out a form. Instructions can be rendered in text, as hyperlinks, or with images. See the section on help text for more information.

Note: the optional labels are used as paragraph headings, when so desired. Nesting paragraphs (see below) can be used to generate subparagraphs, with appropriately sized subheadings. You can nest up to 3 levels.

Feature JSON schema UI schema
Paragraph N/A 

{
  "type": "HelpContent",
  "label": "Paragraph Heading (bold, H2)",
  "options": {
    "help": "Put the paragraph text in here"
  }
}
Nested Paragraphs N/A 

{
  "type": "HelpContent",
  "label": "Paragraph Heading (bold, H2)",
  "options": {
    "help": "Put the main paragraph text in here."
  },
  "elements": [
    {
      "type": "HelpContent",
      "label": "Secondary Heading (bold, H3)",
      "options": {
        "help": "Put the secondary paragraph text in here."
      }
    }
  ]
}
Bullet Points N/A 

{
  "type": "HelpContent",
  "elements": [
    {
      "type": "HelpContent",
      "label": "Introductory text",
      "options": {
        "help": [
          "First point...",
          "Second point...",
          "Third point...",
          "Forth point..."
        ]
      }
    }
  ]
}
Hide/Show detailed explanations N/A 

{
  "type": "HelpContent",
  "label": "Title: Click here to show details",
  "options": {
    "variant": "details"
    "help": "Paragraph preceding the bullet points, below"
  },
  "elements": [
    {
      "type": "HelpContent",
      "options": {
        "help": [
          "First point...",
          "Second point...",
          "Third point..."
        ]
      }
    }
  ]
}
Primary heading N/A 

{
  "type": "HelpContent",
  "label": "Primary Heading (bold, H2)",
}
Secondary heading N/A 

{
  "type": "HelpContent",
  "elements": [
    {
        "type": "HelpContent",
        "label": "Secondary Heading (bold, H3)"
    }
  ]
}
Image N/A 

{
  "type": "HelpContent",
  "label": "An image",
  "options": {
    "variant": "img",
    "width": "200",
    "height": "300",
    "alt": "myImage",
    "src": "https://picsum.photos/200/300"
  }
}
Hyperlink N/A 

{
  "type": "HelpContent",
  "options": {
    "variant": "hyperlink",
    "link": "https://picsum.photos/200/300",
    "help": "link text goes here"
  }
}

File Uploads

For when the user needs to upload supporting documentation. For a more complete description of file uploads, see the documentation.

Feature JSON schema UI schema
Upload a File 

{
  "certificate": {
    "type": "string",
    "format": "file-urn"
  }
}
    

{
  "type": "Control",
  "scope": "#/properties/certificate",
  "options": {
    "variant": "dragdrop"
  }
}

Repeating Items

Repeating Items are useful when you need to capture multiple instances of similar information from your applicants. For example, you may want to collect contact information for one or more family members. With the List with Details or Object Array components, users can easily add as many rows as needed to complete the form. For more information on how these components work, please see the section on Repeating Items.

Feature JSON schema UI schema
List With Detail 

{
  "type": "object",
  "properties": {
    "Users": {
      "type": "array",
      "items": {
        "type": "object",
        "title": "Users",
        "properties": {
          "firstname": {
            "type": "string"
          },
          "lastname": {
            "type": "string"
          }
        }
      }
    }
  }
}
    

{
  "type": "ListWithDetail",
  "scope": "#/properties/Users",
  "options": {
    "detail": {
      "type": "VerticalLayout",
      "elements": [
        {
          "type": "HorizontalLayout",
          "elements": [
            {
              "type": "Control",
              "scope": "#/properties/firstname",
              "label": "First Name"
            },
            {
              "type": "Control",
              "scope": "#/properties/lastname",
              "label": "Last Name"
            }
          ]
        }
      ]
    }
  }
}
Object Array 

{
  "type": "object",
  "properties": {
    "people": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "firstName": {
            "type": "string"
          },
          "lastName": {
            "type": "string"
          }
        }
      }
    }
  }
}
    

{
  "type": "Control",
  "label": "People",
  "scope": "#/properties/people"
}

Steppers

Steppers allow you to partition your form into one or more steps, so users can focus on one group of questions at a time. For more information on how these components work, please see the section on steppers.

Feature JSON schema UI schema
Categorization 

{
  "type": "object",
  "properties": {
    "firstName": {
      "type": "string"
    },
    "lastName": {
      "type": "string"
    }
  }
}
    

{
  "type": "Categorization",
  "elements": [
    {
      "type": "Category",
      "label": "First Name,
      "elements": [
        {
          "type": "Control",
          "scope": "#/properties/firstName
        }
      ]
    },
    {
      "type": "Category",
      "label": "Last Name,
      "elements": [
        {
          "type": "Control",
          "scope": "#/properties/last
        }
      ]
    }
  ]
}