Schema component reference

Configure the form elements on the Root management dashboard for quote, application and alteration workflows

Schema components and component types

The input components included in schemas are defined as an array of JSON objects. Each JSON object in the schema represents a form element (e.g input or dropdown) and must have its own unique key. The JSON objects are converted by the platform into the corresponding form components on the dashboard.

You specify the type of component to be rendered using the type key in the JSON object. There are three categories of components:

  • Static components - In order to improve the user experience and provide context, there are schema components for headings, spacing, paragraphs of text, and horizontal dividers.

  • Input components - These components accept information entered or selected by the user.

  • List component - This component is used to create a list of child input components. The list can be of variable length, and allows the user to add or remove components as needed.

  • Object component - The object component is not displayed on the form, and is used to implicitly include previously stored data in the request payload sent from the schema.

See display conditions to dynamically control when to show or hide components in the form.

Static components

Blank space

This component is used to create blank vertical space on the screen. Repeated components can be used to create a larger blank space.

{
  "type": "blank-space",
  "key": "<unique_key>",
  "props": { ... }, // optional
  "displayConditions": [ ... ] // optional
}

Horizontal line

This component is used to create a horizontal line or separator across the screen. This component is typically used to separate different sections or categories of inputs.

{
  "type": "horizontal-line",
  "key": "<unique_key>",
  "props": { ... }, // optional
  "displayConditions": [ ... ] // optional
}

Section header

A header component to introduce and delineate a new section or category of inputs.

{
  "type": "section-header",
  "key": "<unique_key>",
  "label": "Section 5: Customer Information",
  "props": [ ... ] // optional
  "displayConditions": [ ... ] // optional
}

Paragraph

This component is used to display a paragraph of static text.

{
  "type": "paragraph",
  "key": "<unique_key>",
  "label": "The default commencement  date is the first day of next month",
  "props": {
    "colWidth": 6
  }
}

Top-level parameters

Below is a reference for all the top-level parameters relevant to static components.

ParameterComponent typesDefinition
"type"Allstring. Specifies the component type to render. One of ["blank-space", "horizontal-line", "paragraph", "section-header"].
"key"Allstring. The component's unique key.
"label""paragraph", "section-header"string. The paragraph or header text.
"props"
  optional
"paragraph", "section-header"object. Props affect how the component is displayed.

See the props table below for a full list of available props for static components
"displayConditions"
  optional
Allarray. Make the display of this component dependent on the input value of another component, or on module data saved previously.

See the display conditions section for more details.

Props

Props are used to specify how the component is displayed on the user interface. They are represented by a single object, with a key-value pair for each prop. All props are optional.

Prop exampleComponent typesDefinition
"colWidth""paragraph"integer. The proportion of the page width the component will occupy. One of [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]. The default value is 12.
"headingTag""section-header"string. The size of the heading. One of ["h1", "h2", "h3", "h4", "h5"]. The default value is "h3".
"fontWeight""section-header"string. The font weight of the heading. One of ["bold", "normal"]. The default value is "normal".

Input components

Text

This component is used to capture string input.

{
  "type": "text",
  "key": "<unique_key>",
  "outputPath": "applicant.contact_name",
  "label": "Contact Name *",
  "validators": [
    {
      "validation": {
        "type": "required"
      }
    }
  ],
  "displayConditions": [
    {
      "path": "registered_owner",
      "value": "no",
      "condition": "==="
    }
  ]
}

Select

This component renders as a dropdown that allows the user to select from a list of values. The labels and values for the different options are specified under the "options" parameter.

{
  "key": "<unique_key>",
  "outputPath": "dashboard_trackers",
  "type": "select",
  "label": "Tracker Device *",
  "options": [
    {
      "label": "Active",
      "value": "Active"
    },
    {
      "label": "Executive Plus",
      "value": "Executive Plus"
    },
    {
      "label": "High Alert",
      "value": "High Alert"
    },
    {
      "label": "Nimbi",
      "value": "Nimbi"
    }
  ],
  "validators": [
    {
      "validation": {
        "type": "required"
      }
    }
  ],
  "displayConditions": [
    {
      "path": "company",
      "value": "Bidtrack",
      "condition": "==="
    }
  ]
}

Country

This component renders as a dropdown list of countries.

{
  "type": "country",
  "key": "<unique_key>",
  "label": "Country of birth *",
  "outputPath": "additional_member.country_of_birth",
  "validators": [
    {
      "validation": {
        "type": "required"
      }
    }
  ]
}

The selected country is included in the request payload as an ISO 3166 alpha-2 two-digit country code. Based on the above example, the United States of America will be included in the request payload like this:

{
    "additional_member":
    { 
      "country_of_birth": "US"
    }
}

Radio

This component renders a group of radio buttons. The labels and values for each button are specified under the options field.

{
  "type": "radio",
  "key": "<unique_key>",
  "label": "Are you the registered owner? *",
  "outputPath": "applicant_registered_owner",
  "options": [
    {
      "label": "Yes",
      "value": "yes"
    },
    {
      "label": "No",
      "value": "no"
    }
  ],
  "validators": [
    {
      "validation": {
        "type": "required"
      }
    }
  ]
}

Checkbox

The checkbox component is used to capture boolean values (true or false).

{
  "type": "checkbox",
  "key": "add_additional_benefits",
  "label": "Do you want to add additional benefits?"
}

Number

The number component is used to input numeric values.

{
  "key": "discount_percentage",
  "type": "number",
  "label": "Discount percentage",
  "outputPath": "discount.percentage",
  "validators": [
    {
      "validation": {
        "type": "required"
      }
    },
    {
      "validation": {
        "min": 0,
        "type": "greaterThanNumber"
      }
    },
    {
      "validation": {
        "max": 15,
        "type": "lessThanNumber"
      }
    }
  ],
  "displayConditions": [
    {
      "path": "discount.type",
      "value": "percentage",
      "condition": "==="
    }
  ]
}

Currency

The currency component is used to capture currency values. The currency prefix can be specified under the "props" field.

While currency values are displayed in full units (without cents) on the user interface, they are stored in memory (and included in the request payload) in cents. For example, the maximum value of 10000000 specified in the example represents $100,000.00.

{
  "key": "loan_instalment_amount",
  "type": "currency",
  "label": "Loan Instalment Amount *",
  "outputPath": "loan_details.loan_instalment_amount",
  "props": {
    "prefix": "USD"
  },
  "validators": [
    {
      "validation": {
        "type": "required"
      }
    },
    {
      "validation": {
        "min": 0,
        "type": "greaterThanCurrency",
      }
    },
    {
      "validation": {
        "max": 10000000,
        "type": "lessThanCurrency",
      }
    }
  ]
}

Currency slider

The currency slider component works in the same way as the currency component, but instead of the user typing in the amount they can make use of a slider to set the amount desired. Note: This component is only supported for the embed workflow.

{
  "key": "loan_instalment_amount",
  "type": "currency-slider",
  "label": "Loan Instalment Amount *",
  "outputPath": "loan_details.loan_instalment_amount",
  "props": {
    "prefix": "$"
  },
  "validators": [
    {
      "validation": {
        "type": "required"
      }
    },
    {
      "validation": {
        "min": 0,
        "type": "greaterThanCurrency"
      }
    },
    {
      "validation": {
        "max": 10000000,
        "type": "lessThanCurrency"
      }
    }
  ]
}

Date picker

The date picker component displays a calendar in the user interface, from which the user can select a date. Dates can also be entered directly as strings in ISO format.

{
  "key": "loan_start_date",
  "type": "date-picker",
  "label": "Loan Start Date *",
  "outputPath": "loan_details.loan_start_date",
  "validators": [
    {
      "validation": {
        "type": "required"
      }
    }
  ]
}

Top-level parameters

Below is a reference for all the top-level parameters relevant to input components.

ParameterComponent typesDefinition
"type"Allstring. Specifies the component type to render. One of ["select", "country", "date-picker", "checkbox", "radio", "currency", "currency-slider", "text", "number"].
"key"Allstring. The component's unique key.

This will be the default name of the key in the API request payload to which the input value is assigned. You can override this by specifying the "outputPath".
"outputPath"
  optional
Allstring. The name of the key in the API request payload to which the input value is assigned. Allows for nesting, for example "main_member.age".
"label"Allstring. The label that will be displayed above the input element.
"props"
  optional
Allobject. Props affect how the component is displayed.

See the props table below for a full list of available props for input components.
"validators"
  optional
Allarray. An array of validation rules for the component. See the validators section for a full list of available validators.
"displayConditions"
  optional
Allarray. Make the display of this component dependent on the input value of another component.
"defaultValue"
  optional
"checkbox"boolean. Whether or not the checkbox is selected when the page loads. Defaults to false.
"options""select", "radio"array. An array of JSON objects, each representing one of the options that can be selected by the user.

Each option object must have a "label" and a "value" parameter. The "label" is displayed to the user. The "value " is sent in the API request.

Props

Props are used to specify how the component is displayed on the user interface. They are represented by a single object, with a key-value pair for each prop. All props are optional.

PropComponent typesDefinition
"hiddenComponent"Allboolean. Whether the component should be hidden. Defaults to false.
"prefix""currency", "text", "number"string. Prefix to display in front of the form input. For the currency component, you can use the ISO 4217 currency code which will automatically convert the code to the corresponding symbol e.g. "USD" = "$".
"placeholder""text"string. Placeholder text to display as a hint to the user.
"decimal""number"boolean. Whether the number component accepts decimal values.

Validators

It is good practice to include validation in the quote and application schemas. This prevents unnecessary API calls with invalid data, and improves the user experience as error messages can be displayed in real time.

Validators are optionally included as an array of validation objects under the "validators" parameter of the relevant schema component, as illustrated in the example below.

{
  "key": "discount_percentage",
  "type": "number",
  "label": "Discount percentage",
  "validators": [
    {
      "validation": {
        "type": "required"
      }
    },
    {
      "validation": {
        "min": 0,
        "type": "greaterThanNumber"
      }
    },
    {
      "validation": {
        "max": 15,
        "type": "lessThanNumber"
      }
    }
  ]
}

Below is a reference for all supported validators. All validators are optional.

TypeComponent typesDescription
"required"AllChecks that the input value is not left blank.
"za_id""text", "select", "radio"Checks that the input value is a valid RSA ID number.
"email""text", "select", "radio"Checks that the input value conforms to a valid email address format.
"imei""text", "select", "radio"Checks that the input value is a valid IMEI number.
"greaterThanLength""text", "select", "radio"Checks that the length of the input value is greater than the specified number of characters.

The minimum number of characters is specified using the mandatory "min" parameter.
"lessThanLength""text", "select", "radio"Checks that the length of the input value is smaller than the specified number of characters.

The maximum number of characters is specified using the mandatory "max" parameter.
"greaterThanNumber""number", "select", "radio"Checks that a numeric input value is greater than the specified minimum.

The minimum is specified using the mandatory "min" parameter.
"lessThanNumber""number", "select", "radio"Checks that a numeric input value is less than the specified maximum.

The maximum is specified using the mandatory "max" parameter.
"greaterThanCurrency""currency"Checks that a currency value is greater than the specified minimum amount.

The minimum is specified using the mandatory "min" parameter (an integer in cents).
"lessThanCurrency""currency"Checks that a currency value is less than the specified maximum amount.

The maximum is specified using the mandatory "max" parameter (an integer in cents).

List component

Often a variable number of items or persons need to be included on a policy. For example, multiple motor vehicles on a fleet motor insurance policy, or multiple children on a family funeral policy.

Since it is not known beforehand how many items or people will be be included, schemas provide a tool whereby the user can capture the same data for a variable number of items, as illustrated in the following example.

{
  "type": "list",
  "label": "List",
  "props": {
    "addButtonLabel": "Add child"
  },
  "maxNumber": 8,
  "components": [
    {
      "type": "section-header",
      "label": "Child",
      "props": {
        "headingTag": "h5",
        "indexNumber": true
      }
    },
    {
      "key": "age",
      "type": "number",
      "label": "Age *",
      "outputPath": "children",
      "validators": [
        {
          "validation": {
            "type": "required"
          }
        },
        {
          "validation": {
            "min": 0,
            "type": "greaterThanNumber"
          }
        },
        {
          "validation": {
            "max": 21,
            "type": "lessThanNumber"
          }
        }
      ]
    }
  ],
  "outputPathList": "children",
  "displayConditions": [
    {
      "path": "children_included",
      "value": true,
      "condition": "==="
    }
  ]
}

The components to be repeated are included as an array under the "components" parameter of the list component. Note that the "outputPath" parameter of each child component must equal the "outputPathList" parameter of the parent list component.

The input values entered by the user will be included in an array in the request payload. This array is assigned to the key in the request payload specified in the "outputPathList". A separate object is included in the array for each child component added under the list. Within these objects, the key matches the "key" parameter specified for the child component in the list.

For example, based on the above list component, the user will generate the following request payload if she adds three children of ages 17, 14 and 6 respectively:

{
  "children": [
    {
      "age": 17
    },
    {
      "age": 14
    },
    {
      "age": 6
    }
  ]
}

Top-level parameters

Below is a reference for all the top-level parameters that can be included under the list component.

Top-level parameterDescription
"type"string. The type of component to display. In this case, "list".
"outputPathList"string. The name of the key in the request payload structure to which the array of input values will be assigned.
"label"string. The component's label. The list component's label is not displayed when the component is rendered.
"props"
  optional
object. Props affect how the component is displayed.

See the props table below for a full list of available props for the list component.
"maxNumber"
  optional
integer. The maximum number of child components the user can add.
"minNumber"
  optional
integer. The minimum number of child components the user has to add.
"displayConditions"
  optional
array. Make the display of the entire list component dependent on the input value of another component.

Props

Props are used to specify how the component is displayed on the user interface. They are represented by a single object, with a key-value pair for each prop. All props are optional.

PropDescription
"addButtonLabel"string. The text to display on the button used to add an additional child component.
"removeButtonLabel"string. The text to display on the button used to remove a child component.

Object component

The object component is used to implicitly include previously stored data in the request payload sent from the schema. This component is not displayed to the user. Instead, the data is taken directly from the input_data of the previously created quote (in the case of an application schema), or the module data of the existing policy (in the case of an alteration schema).

As an example, let's consider a funeral policy where each child on the policy is assigned a UUID in the product module code. A snippet from the policy's module data could look like this:

{
    "module":  {
    "children": [
      {
        "name": "Jane Doe",
        "uuid": "c22e3d2b-f7c0-4856-bc25-ba5815ea4e52"
      },
      {
        "name": "John  Doe",
        "uuid": "112c298c-8d33-4f0f-a86d-d5a62ecf5955"
      }
    ]
  }
}

The alteration schema for this policy contains components to edit the children's names. However, according to the product requirements, the UUID for each child should not be displayed on the alteration form. Only the name field is displayed. Then the alteration schema could contain the following list component:

{
  "type": "list",
  "label": "Children list",
  "components": [
    {
      "type": "text",
      "key": "name",
      "label": "Name",
      "outputPath": "children"
    },
    {
      "type": "object",
      "key": "uuid",
      "label": "UUID",
      "outputPath": "children"
    }
  ],
  "outputPathList": "children"
}

The result is that only the form input for the relevant child's name is displayed. However, the UUID from the policy module data is still included in the request payload sent from the schema. This allows the newly entered name to be matched to the correct child on the policy.

Parameters

ParameterDefinition
"type"string. The type of component to display. In this case "object".
"key"string. The component's unique key.

By default, this will be the name of the key in the API request payload to which the component's value is assigned. It also represents the key in the existing input_data or module data from which the data will be taken.

You can override this by specifying the "outputPath".
"outputPath"
  optional
string. Can be used to override the "key" parameter. Allows for nesting, for example "main_member.age".
"label"string. The component's label. The label is not displayed for the object component.

Display conditions

In some cases, one input component should only be displayed if another input component has a specific value. For example, the schema could include a checkbox for whether an additional member should be included on the policy. If the checkbox is ticked, additional input components should be displayed to capture information on the additional member.

In some cases, whether or not a component should be displayed can also depend on module data saved previously. For example, if an additional vehicle was added at the quote stage, then the application schema should display additional components to capture information on that vehicle. In this case the display condition of the application components can refer to the quote package module saved previously.

Conditional rendering is achieved by specifying the optional "displayConditions" field of the schema component, as in the following example. In this case, the 'discount_percentage' component will only be displayed if the 'apply_discount" checkbox is checked.

[
  {
    "key": "additional_member_included",
    "type": "checkbox",
    "label": "Do you want to add an additional member?"
  },
  {
    "key": "additional_member_age",
    "type": "number",
    "label": "Additional member age",
    "displayConditions": [
      {
        "path": "additional_member_included",
        "value": true,
        "condition": "==="
      }
    ]
  }
]

📘

Display conditions can depend on previously entered information

In some contexts it is useful to make a component's display dependent on data captured previously. For example, an application schema should only display components to capture details on an additional life, if an additional life was added at the quote stage.

In the above example, the display condition's "path" is set to "additional_member_included". If this component is in an application schema, the platform will first look for the additional_member_included parameter in the input_data object on the previously created quote package. If this key is not found in input_data, the platform will then look for a component in the application schema itself with a key of "additional_member_included".

In the case of alteration hook schemas, the platform will look for the parameter in the module object saved on the policy, before looking for a matching component in the schema itself.

The display status of one component can depend on several other components. This is achieved by combining multiple display conditions using logical operators, as in the following example.

{
  "key": "deceased_id_number",
  "type": "text",
  "label": "South African ID number *",
  "displayConditions": [
    {
      "path": "member_deceased",
      "value": "other_insured",
      "condition": "===",
      "and": [
        {
          "path": "deceased_id_type",
          "value": "id",
          "condition": "==="
        }
      ],
    }
  ]
}

Top-level parameters

Display conditions can be defined for all component types.

ParameterDescription
"path"string. The path reference of another component, on which the display of this component depends.

In an application schema, this parameter can also reference a key the module object of the previously created quote package.
"value"any. This value will be compared against the value referenced by the "path" parameter.
"condition"string. One of ["===", "!=="]. The logical operator that will be applied in comparing the two values.
"and"
  optional
array. An array containing one other display condition. Both the parent condition and the child condition must evaluate to true for the component to be displayed.

Not allowed if the parent display condition is already part of an "and" or "or" array. Not allowed if the "or" parameter is included.
"or"
  optional
array. An array containing one other display condition. Either the parent condition or the child condition must evaluate to true for the component to be displayed.

Not allowed if the parent display condition is already part of an "and" or "or"array. Not allowed if the "and" parameter is included.

What’s Next