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. NOTE: There is a known issue in jsonforms that allows an empty string to satisfy the required validation rule. To work around this, you should also add a minimum length of 1 to required string fields (see Limited text with required validation) below.

Format Description JSON schema UI schema
Date A calendar date picker for selecting a date value in ISO format (YYYY-MM-DD). 

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

{
  "type": "Control",
  "scope": "#/properties/dateOfBirth",
}
Date (past dates only) A date picker restricted to only allow selection of dates in the past (before today). 

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

{
  "type": "Control",
  "scope": "#/properties/dateOfBirth",
  "options": {
    "allowPastDate": true,
    "allowFutureDate": false
  }
}
Date (future dates only) A date picker restricted to only allow selection of dates in the future (after today). 

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

{
  "type": "Control",
  "scope": "#/properties/dateOfBirth",
  "options": {
    "allowPastDate": false,
    "allowFutureDate": true
  }
}
Integer A numeric input field for whole numbers with optional min, max, and step constraints. 

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

{
  "type": "Control",
  "scope": "#/properties/numberOfChildren",
  "options": {
    "componentProps": {
      "min": 10,
      "max": 200,
      "step": 5
    }
  }
}
Number A numeric input field for decimal and floating-point values. 

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

{
  "type": "Control",
  "scope": "#/properties/averageYearlyRainfall"
}
Calculation (computed) A read-only calculated field that evaluates a numeric expression from other form values and writes the result back into form data. 

  {
    "total": {
      "type": "string",
      "format": "computed",
      "description": "#/properties/x * #/properties/y + #/properties/z"
    }
  }
      

  {
    "type": "Control",
    "scope": "#/properties/total",
    "label": "Total"
  }
Limited Text A single-line text input field with character limit. 

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

{
  "type": "Control",
  "scope": "#/properties/firstName"
}
Limited text with required validation A required single-line text input that cannot be empty and must contain at least one character. 

{
  "firstName": {
    "type": "string",
    "minLength" : 1
  },
  "required" : [
    "firstName"
    ]
}
    

{
  "type": "Control",
  "scope": "#/properties/firstName"
}
Text Box A multi-line text input field for longer text content with configurable row height. 

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

{
  "type": "Control",
  "scope": "#/properties/reasonForApplying"
  "options": {
  "multi": true,
  "componentProps": {
    "rows": 10,
    "placeholder": "multi line input"
    }
  }
}
Text Box with required validation A required multi-line text field that must contain at least one character. 

{
  "reasonForApplying": {
    "type": "string",
    "minLength" : 1
  },
  "required" : [
     "reasonForApplying"
  ]
}
    

{
  "type": "Control",
  "scope": "#/properties/reasonForApplying"
  "options": {
  "multi": true,
  "componentProps": {
    "rows": 10,
    "placeholder": "multi line input"
    }
  }
}
Boolean (yes,no) A radio button group for selecting between two options (typically 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"
  }
}
Checkbox with required validation A required checkbox that must be checked (confirmed) to satisfy the form requirement. 

{
  "iDeclare": {
    "type": "boolean",
    "allOf": [
      {
        "enum": [
          true
        ]
      }
    ]
  },
  "required" : [
    "ideclare"
  ]
}
    
    
{
  "type": "Control",
  "scope": "#/properties/iDeclare"
  "options":{
    text: "I declare the information is correct to the best of my knowledge"
  }
}

Date Input Control Options

The date control supports these options to restrict date selection:

Option Behavior Default
allowPastDate When set to true with allowFutureDate: false, restricts the date picker to only allow selection of past dates (before today). Not set
allowFutureDate When set to true with allowPastDate: false, restricts the date picker to only allow selection of future dates (after today). Not set

Calculation Control

The calculation control is rendered when the JSON schema field uses "format": "computed". The expression is defined in schema.description, evaluated against current form data, and the result is written back to the control path automatically. The rendered field is read-only.

Calculation Requirements
Property Location Behavior
format JSON schema Must be set to computed for the calculation renderer to be selected.
description JSON schema Contains the calculation expression. This is where the library reads the formula from.
scope UI schema Points to the destination field where the computed result is stored.
label UI schema Optional display label for the read-only calculated field.
Supported Calculation Patterns
Pattern Description Example Expression
Arithmetic with scopes Uses referenced form values in numeric expressions. #/properties/x * #/properties/y + #/properties/z
SUM(...) Sums a numeric property across all rows of an object array. SUM(#/properties/items/amount)
min(...) Returns the smallest numeric value from referenced scopes and/or literals. min(#/properties/a, #/properties/b, 100)
max(...) Returns the largest numeric value from referenced scopes and/or literals. max(#/properties/a, #/properties/b, 0)
Calculation Examples

Basic arithmetic

{
  "type": "object",
  "properties": {
    "x": {
      "type": "number"
    },
    "y": {
      "type": "number"
    },
    "z": {
      "type": "number"
    },
    "total": {
      "type": "string",
      "format": "computed",
      "description": "#/properties/x * #/properties/y + #/properties/z"
    }
  }
}

{
  "type": "VerticalLayout",
  "elements": [
    {
      "type": "Control",
      "scope": "#/properties/x"
    },
    {
      "type": "Control",
      "scope": "#/properties/y"
    },
    {
      "type": "Control",
      "scope": "#/properties/z"
    },
    {
      "type": "Control",
      "scope": "#/properties/total",
      "label": "Total"
    }
  ]
}

Sum a numeric column from a repeating-item array

{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "amount": {
            "type": "number"
          }
        }
      }
    },
    "totalAmount": {
      "type": "string",
      "format": "computed",
      "description": "SUM(#/properties/items/amount)"
    }
  }
}

{
  "type": "VerticalLayout",
  "elements": [
    {
      "type": "ListWithDetail",
      "scope": "#/properties/items",
      "options": {
        "detail": {
          "type": "VerticalLayout",
          "elements": [
            {
              "type": "Control",
              "scope": "#/properties/amount",
              "label": "Amount"
            }
          ]
        }
      }
    },
    {
      "type": "Control",
      "scope": "#/properties/totalAmount",
      "label": "Total amount"
    }
  ]
}

Clamp to a minimum or maximum value

{
  "type": "object",
  "properties": {
    "requested": {
      "type": "number"
    },
    "approved": {
      "type": "string",
      "format": "computed",
      "description": "min(#/properties/requested, 1000)"
    }
  }
}
Calculation Behavior and Errors
Case Behavior
All referenced values missing The field stays blank and no error is shown.
Some referenced values missing The field stays blank and shows Please provide values for: ... after the user has interacted with the form.
Invalid scope in the expression A configuration error is shown for the bad scope reference.
Invalid expression syntax A configuration error is shown with Invalid expression syntax.
Non-numeric values in SUM(...) The calculation does not produce a value and asks for valid values for the referenced array column.
Notes
  • The library selects this control for schema fields with type: "string" and format: "computed".
  • Even though the schema type is string, the rendered control is a disabled numeric input and the computed value written back to form data is numeric.
  • Scope references should use JSON pointer-style paths such as #/properties/fieldName.

Selectors

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

Feature Description JSON schema UI schema
Dropdown menu A collapsed dropdown selector for choosing one option from a predefined list. 

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

{
  "type": "Control",
  "scope": "#/properties/colour"
  "label": "What's your favorite colour?",
}
Radio Button A set of radio buttons for selecting one option from a list, with options displayed inline or vertically. 

{
  "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 A set of checkboxes for selecting multiple options from a list simultaneously. 

{
  "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 Description JSON schema UI schema
Vertical Layout (columns) Arranges input fields vertically (stacked on top of each other) in a single column. 

{
  "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) Arranges input fields horizontally (side by side) in a single row. 

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

{
  "type": "HorizontalLayout",
  "elements": [
    {
      "type": "Control",
      "scope": "#/properties/firstName"
    },
    {
      "type": "Control",
      "scope": "#/properties/lastName"
    }
  ]
}
Mixed Combines vertical and horizontal layouts to create complex field arrangements with multiple rows and columns. 

{
  "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 Groups related input fields together with a label, visually organizing related information. 

{
  "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.

As of Jan. 2025 you can use markdown for help content, significantly simplifying the process of adding help text. Please see the section on help text.

Feature Description JSON schema UI schema
Markdown Renders instructional content using Markdown syntax, supporting bold, italic, links, bullet points, and section headings. N/A 

{
  "type": "HelpContent",
  "label": "Paragraph Heading (bold, H2)",
  "options": {
    "markdown": true,
    "help": [
    "## Section Heading",
    "This is a paragraph with some **bold** text.",
    "This is another paragraph, with _italic_ text.",
    "This paragraph has [a link](https://google.com)."
    "- First bullet point",
    "- Second bullet point"
    ]
  }
}
Paragraph Displays a plain text paragraph with optional heading label for instructional content. N/A 

{
  "type": "HelpContent",
  "label": "Paragraph Heading (bold, H2)",
  "options": {
    "help": "Put the paragraph text in here"
  }
}
Nested Paragraphs Organizes multiple paragraphs hierarchically with parent and child heading levels (up to 3 levels deep). 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 Displays a list of bullet points, useful for presenting multiple related items or steps. N/A 

{
  "type": "HelpContent",
  "elements": [
    {
      "type": "HelpContent",
      "label": "Introductory text",
      "options": {
        "help": [
          "First point...",
          "Second point...",
          "Third point...",
          "Forth point..."
        ]
      }
    }
  ]
}
Hide/Show detailed explanations Creates a collapsible section (accordion) with a title that users can click to reveal detailed content. 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 Displays a large primary heading (H2) for section titles in instructional content. N/A 

{
  "type": "HelpContent",
  "label": "Primary Heading (bold, H2)",
}
Secondary heading Displays a smaller secondary heading (H3) for subsections within instructional content. N/A 

{
  "type": "HelpContent",
  "elements": [
    {
        "type": "HelpContent",
        "label": "Secondary Heading (bold, H3)"
    }
  ]
}
Image Embeds an image in the form with configurable dimensions, alt text, and source URL. N/A 

{
  "type": "HelpContent",
  "label": "An image",
  "options": {
    "variant": "img",
    "width": "200",
    "height": "300",
    "alt": "myImage",
    "src": "https://picsum.photos/200/300"
  }
}
Hyperlink Creates a clickable link to an external URL with custom link text. 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 Description JSON schema UI schema
Upload a File Allows users to upload a file via drag-and-drop or file selection interface, storing a file URN reference. 

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

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

FileUploader Control Options

The FileUploader Control supports these options to configure file upload behavior:

Option Location Behavior Default
maximum componentProps.maximum Set a limit on how many files can be uploaded for the control. Prevents users from uploading more than the specified number of files. 1
noDownloadButton format.noDownloadButton When set to true, hides the download button in the file list, preventing users from downloading uploaded files. false
FileUploader Control Options Examples

Multiple file uploads with no download button:

{
  "type": "Control",
  "scope": "#/properties/supportingDocuments",
  "options": {
    "variant": "dragdrop",
    "componentProps": {
      "maximum": 5
    },
    "format": {
      "noDownloadButton": true
    }
  }
}

Single file upload with download enabled:

{
  "type": "Control",
  "scope": "#/properties/certificate",
  "options": {
    "variant": "dragdrop",
    "componentProps": {
      "maximum": 1,
      "maxFileSize": "5MB",
      "accept": ".pdf,.doc,.docx"
    }
  }
}

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 Description JSON schema UI schema
List With Detail Displays array items in a list view with the ability to click and edit detailed information for each item. 

{
  "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 Displays array items in an inline table format where each row can be expanded for individual editing. 

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

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

Repeating Items Control Options

The repeating item controls support this array-list option:

</tr> </table> ##### Repeating Items Control Option Example ```json { "type": "ListWithDetail", "scope": "#/properties/people", "options": { "showArrayTableSortButtons": true, "detail": { "type": "VerticalLayout", "elements": [ { "type": "Control", "scope": "#/properties/firstName" }, { "type": "Control", "scope": "#/properties/lastName" } ] } } } ``` ### Steppers {#target-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](/adsp-monorepo/tutorials/form-service/steppers.html).
Option Location Behavior Default
showArrayTableSortButtons options.showArrayTableSortButtons Enables the array sort-button setting for repeating item controls. false
Feature Description JSON schema UI schema
Categorization Partitions form fields into multiple categories/steps that users navigate through sequentially, with automatic summary review page. 

{
  "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
        }
      ]
    }
  ]
}
Page steppers support these Task List and review-flow options:
Attribute Description Scope Example
hideSummary Hide the Summary row on the Task List and skip the summary review page. Categorization.options 

{
  "type": "Categorization",
  "options": {
    "hideSummary": true
  }
}
hideSubmit Hide the Submit button on the summary review page. Categorization.options 

{
  "type": "Categorization",
  "options": {
    "hideSubmit": true
  }
}
toAppOverviewLabel Change the back-link text that returns the user to the Task List. Categorization.options 

{
  "type": "Categorization",
  "options": {
    "toAppOverviewLabel": "Back to task list"
  }
}
sectionTitle Group categories under a section heading on the Task List. Category.options 

{
  "type": "Category",
  "options": {
    "sectionTitle": "The parties"
  }
}
showInTaskList When set to false, hide the category from the Task List. Hidden categories do not render their own row, and a section header is not shown if all categories in that section are hidden. Category.options 

{
  "type": "Category",
  "label": "What are their contact details?",
  "options": {
    "sectionTitle": "The parties",
    "showInTaskList": false
  }
}
### Validation {#target-validation} Validation is most easily accomplished through the semantics of JSON Schemas. Note the "minLength" attribute of the name property. This is needed to address a fix needed when required string fields.
Feature Description JSON schema
Required Ensures that specified fields must have a value provided before form submission. 

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1
    },
    "isAlbertan": {
      "type": "boolean"
    }
  },
  "required": [
    "firstName",
    "lastName"
  ]
}
Conditionally Required Makes a field required based on conditions defined in other field values using if-then logic. 

{
  "type": "object",
  "properties": {
    "hasChild": {
      "type": boolean
    },
    "childsName": {
      "type": "string",
    },
  },
  "required": [
    "hasChild"
  ],
  "if": {
    "properties": {
      "hasChild": {
        "const": true
      }
    }
  },
  "then": {
    "properties": {
      "childsName": {
      "minLength": 1
      }
    },
    "required": [
      "childsName"
    ]
  }
}