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 rendered as corresponding form components on the Root management dashboard.

You specify the type of component to be rendered using the type key in the JSON object. There are four 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.

For each component type you also have the option to specify the following information:

• 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.

• Display conditions - Allows you to conditionally render a component based on the value of other components, or previously entered data.

• Validators - Validators are optionally included in relevant schema components. They help to prevent unnecessary API calls with invalid data, and improve the user experience as error messages can be displayed in real time.

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>"
}

Properties

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>"
}

Properties

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"
}

Properties

Props

For props examples, see the props section below.

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"
}

Properties

Props

For props examples, see the props section below.

Input components

Text

This component is used to capture string input.

{
  "type": "text",
  "key": "<unique_key>",
  "label": "Contact Name *"
}

Properties

Props

For props examples, see the props section below.

Validators

For validator examples, see the validators section below.

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>",
  "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"
    }
  ]
}

Properties

Props

For props examples, see the props section below.

Validators

For validator examples, see the validators section below.

Country

This component renders as a dropdown list of countries.

{
  "type": "country",
  "key": "<unique_key>",
  "label": "Country of birth *"
}

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"
    }
}

Properties

Props

For props examples, see the props section below.

Validators

For validator examples, see the validators section below.

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? *",
  "options": [
    {
      "label": "Yes",
      "value": "yes"
    },
    {
      "label": "No",
      "value": "no"
    }
  ]
}

📘

Horizontal or vertical options

The "type": "radio" will render buttons vertically underneath each other. Options can be rendered horizontally next to each other by using "type": "radio-button".

Properties

Props

For props examples, see the props section below.

Validators

For validator examples, see the validators section below.

Multiple-checkbox

The multi-checkbox component is used to capture multiple boolean values. The labels and values for the different options are specified under the "options" parameter.

{
  "type": "multiple-checkbox",
  "key": "additional_benefits",
  "label": "Do you want to add additional benefits for:",
  "options": [
    {
      "label": "Theft",
      "value": "theft"
    },
    {
      "label": "Damage",
      "value": "damage"
    },
    {
      "label": "Accidental loss",
      "value": "accidental_loss"
    }
},

Properties

Props

For props examples, see the props section below.

Validators

For validator examples, see the validators section below.

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?"
},

Properties

Props

For props examples, see the props section below.

Validators

For validator examples, see the validators section below.

Cellphone

The cellphone component is used to capture the cellphone details.

{
  "key": "customer_cellphone",
  "type": "cellphone",
  "label": "Cellphone"
}

This component consists of a country picker and cellphone number input. The component allows the user to select the country the cellphone number is registered to, as well as to complete the cellphone number. The component will validate that the cellphone number is valid for the specified country.

The output format of the input can be seen below

{
  "number": "0823010571",
  "international_number": "+27823010571",
  "country_code": "ZA"
}

Properties

Props

For props examples, see the props section below.

Validators

For validator examples, see the validators section below.

Number

The number component is used to input numeric values.

{
  "key": "discount_percentage",
  "type": "number",
  "label": "Discount percentage"
}

Properties

Props

For props examples, see the props section below.

Validators

For validator examples, see the validators section below.

Number slider

The number slider component works in the same way as the number component but instead of the user typing in the number, they can make use of a slider to set the number desired. You can also optionally pass an "increment" value, which determines by how much each move of the slider increments the value.

{
  "key": "discount_percentage",
  "type": "number-slider",
  "label": "Discount percentage",
  "props": {
    "increment": "5"
  }
}

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 *",
  "props": {
    "prefix": "$"
  }
}

Properties

Props

For props examples, see the props section below.

Validators

For validator examples, see the validators section below.

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. You can also optionally pass an "increment" prop (value in cents), which determines by how much each move of the slider increments the amount.

{
  "key": "loan_instalment_amount",
  "type": "currency-slider",
  "label": "Loan Instalment Amount *",
  "props": {
    "prefix": "$",
    "increment": "100000"
  }
}

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 *"
}

Properties

Props

For props examples, see the props section below.

Validators

For validator examples, see the validators section below.

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",
  "maxNumber": 5,
  "components": [
    {
      "type": "section-header",
      "label": "Child",
      "props": {
        "headingTag": "h5",
        "indexNumber": true
      }
    },
    {
      "key": "age",
      "outputPath": "children",
      "type": "number",
      "label": "Age *",
    }
  ],
  "outputPathList": "children"
}

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
    }
  ]
}

Properties

Props

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"
    },
    {
      "type": "object",
      "key": "uuid",
      "label": "UUID"
    }
  ],
  "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.

Properties

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": "==="
    }
  ]
}

Properties

Display conditions can be defined for all component types.

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.

For example, this is how to implement the colWidth prop for a paragraph component.

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

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": "greaterThanEqualsToNumber"
      }
    },
    {
      "validation": {
        "max": 15,
        "type": "lessThanEqualsToNumber"
      }
    }
  ]
}