Defining a Schema

A form schema is used to define the fields, layout and behaviours of a form. It can be as simple or as complex as needed.

A schema is a simple JSON array and, typically, will contain the following sections:

• fields - define the fields that will appear in the form
• sections - define the layout of the form

Defining fields

A field is defined as follows:

• unique_field_name: an arbitrary name (eg. "job_number", "site_code" etc.) unique to the field so you can reference it elsewhere in the schema
• FIELD_TYPE: the type of the field (eg. "TEXT", "CHOICE" etc.) see below for a list of available field types
• options (optional): any field options (eg. label, validation, etc.) see below for a list of field options

"unique_field_name": {
  "type": "FIELD_TYPE",
  "options": {
    "label": "Field Label"
  }
}

If a field is part of a collection (see Field Types below) then it must also contain the "belongs_to" property:

"my_collection": {
  "type": "COLLECTION"
}

"unique_field_name": {
  "belongs_to": "my_collection",
  "type": "FIELD_TYPE",
  "options": {
    "label": "Field Label"
  }
}

Field options

The following are some commonly used field options:

string
		

"label": "Job Number"
		

boolean
		

"readonly": true
		

boolean
		

"hide_label": true
		

array
		

"constraints": [
  {
    "type": "NOT_BLANK",
    "options": {}
  }
]
		

"constraints": [
  {
    "type": "NOT_BLANK",
    "options": {
      "message": "Please fill in this field"
    }
  }
]
		

The following are some commonly used CHOICE field options:

array 
{label : value}
		

"choices": {
  "Option A": "a",
  "Option B": "b"
}
		

string
		

"placeholder": "Select an option"
		

boolean
		

"multiple": true
		

boolean
		

"expanded": true
		

The following are HTML field options:

string
		

"html": "<strong>Some content</strong>"
		

The following are HEADING field options:

string
		

"text": "My Heading"
		

Field types

List of available field types:

Sections

The layout of the form is defined within the "sections" portion of the schema.

Each field (defined in the "fields" portion) MUST also be included within "sections". You can define a form section as follows:

• unique_section_name: an arbitrary name (eg. "general_details", "section_1" etc.) unique to the section
• label: the section label, displayed in the form
• description (optional): a description of the form section, displayed in the form, set to 'null' if not needed
• rows: an array of rows, containing fields, which belong to the form section

Defining rows

A row is just an array of fields, including a class to determine the width of the field. A row with one field would look like this:

"col" is the default class and should be used if you don't want to specify a width for the field. If you wish to specify the width of the fields, please reference the Bootstrap Grid System

[
  {
    "field": "existing_field_name",
    "class": "col"
  }
]

This is how a section is structured:

{
  "sections": {
    "unique_section_name": {
      "label": "Section Label",
      "description": "A brief description of this section",
      "rows": [
        [
          {
            "field": "existing_field_name",
            "class": "col"
          }
        ]
      ]
    }
  }
}

Example

{
  "fields": {
    "text": {
      "type": "TEXT",
      "options": {
        "label": "Text"
      }
    }
  },
  "sections": {
    "general_details": {
      "label": "General Details",
      "description": null,
      "rows": [
        [
          {
            "field": "text",
            "class": "col"
          }
        ]
      ]
    }
  }
}