Form schema

NOTE

More information about the forms editor here

The Schema represents the data model and validation rules for your form. It defines the structure, data types, and constraints of each field.

Here are some commonly used Schema properties:

• title: specifies the title or name of the form.
• description: provides a brief description of the form.
• type: specifies the overall type of the form, typically "object" to represent a collection of fields.
• properties: defines individual fields within the form, including their types and validation rules.
  • valid types: "integer", "boolean", "number", "string", "array", "object".
• required: lists the fields that must be filled out before submitting the form.

Example:

{
  "title": "User Information",
  "description": "A form example",
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "age": {
      "type": "number",
      "minimum": 18,
      "maximum": 99
    }
  },
  "required": ["name", "email"]
}

This code represents a JSON Schema for a user information form. It defines the structure and validation rules for the form fields. The form includes properties for "name", "email", and "age."

• The "name" property is of type "string" and does not have any additional constraints.
• The "email" property is also of type "string" and has a format constraint of "email", ensuring that the input matches an email address format.
• The "age" property is of type "number" and has minimum and maximum constraints of 18 and 99, respectively.

The "required" keyword specifies that the "name" and "email" fields are mandatory and must be filled out before submitting the form. The "title" and "description" provide additional information about the form.

Data Components

The Schema plays a crucial role in defining the data model and validation rules for your form. It outlines the structure of your form, specifies the data types for each field, and sets constraints to ensure data integrity.

By leveraging the Schema, you can effectively define the underlying structure and rules for your form's data.

NOTE

To facilitate the understanding of the examples, the definition of the Forms Schema is accompanied by the definition of a UI Forms Schema. To learn about the UI Scheme, visit the specific documentation section.

Integer

---

Renders a number input field, by default an integer number to use a float see

Type: Number

Example:

Schema

UI Schema

{
  "properties": {
    "age": {
      "type": "integer",
      <<options>>
    }
  }
}

Options:

Options	Description
title	Specifies a customized label for the field.
description	Shows a customized message for the field description.
default	Specifies a pre-set value for the field.
minimum	Specifies the minimum number allowed for the field.
maximum	Specifies the maximum number allowed for the field.

{
  "type": "Control",
  "scope": "#/properties/age"
}

Boolean

---

Represents a value that can be either true or false. It is used to define properties or data points that are expected to have a boolean (logical) value. By default appears as a checkbox, but it can be changed to a toggle switch in the UI Schema options.

Example:

Schema

UI Schema

{
  "properties": {
    "student": {
      "type": "boolean",
      <<options>>
    }
  }
}

Options:

Options	Description
title	Specifies a customized label for the field.
description	Shows a customized message for the field description.
default	Specifies a pre-set value for the field.

{
  "type": "Control",
  "scope": "#/properties/student",
  "options": {
    <<option>>
  }
}

Option:

Option	Description
toggle	true Change to a toggle switch in the user interface.
	false Not mandatory, keep the checkbox format in the user interface.

Number

---

Renders a number input field, by default a float number, to use an integer see

Type: Integer

Example:

Schema

UI Schema

{
  "properties": {
    "height": {
      "type": "number",
      <<options>>
    }
  }
}

Options:

Option	Description
title	Specifies a customized label for the field.
description	Shows a customized message for the field description.
default	Specifies a pre-set value for the field.
minimum	Specifies the minimum value for the number
maximum	Specifies the maximum value for the number

{
  "type": "Control",
  "scope": "#/properties/height"
}

String

---

The string type represents a simple text input field in the form. With the format option, it could validate inputs or change its visualization.

Example:

Schema

UI Schema

{
  "properties": {
    "name": {
      "type": "string",
      <<options>>
    }
  }
}

Options:

Options	Description
title	Specifies a customized label for the field.
description	Shows a customized message for the field description.
default	Specifies a pre-set value for the field.
minLength	Specifies the minimum length for the string
maxLength	Specifies the maximum length for the string
transform	"trimStart", "trimEnd", "trimLeft", "trimRight", "trim", "toLowerCase", "toUpperCase", "toEnumCase"
pattern	Allows the possibility of creating a RegEx validation for string content.
format	email: Represents a email format string
	tel: Represents a telephone format input field
	password: Replaces the entered string with non-readable characters.
	kuflow-file: Represents a file input field ( see File )
	kuflow-principal: Represents a user browsing field ( see User )
	date: Represents a date input field ( see Date )

{
  "type": "Control",
  "scope": "#/properties/name",
  "options": {
    <<option>>
  }
}

Option:

Option	Description
multi	true: Represents a multiline text input field

Date

---

The time picker will be used when format: "date" is specified for a string property in the Schema.

Example:

Schema

UI Schema

{
  "properties": {
    "date": {
      "type": "string",
      "format": "date",
      <<options>>
    }
  }
}

Options:

Option	Description
title	Specifies a customized label for the field.
description	Shows a customized message for the field description.
default	Specifies a pre-set value for the field.

{
  "type": "Control",
  "scope": "#/properties/date",
  "options": {
    <<options>>
  }
}

Options:

Option	Description
dateFormat	"dd-MM-yyyy": Represents the date in the UI as follows 25-05-1977
	"dd-MMM-yyyy": Represents the date in the UI as follows 25-May-1977
dateSaveFormat	Defines how the data will be saved.

File

---

This is one of our customizations, the upload file field will be used when the format: "kuflow-file" is specified for a string property in the Schema. It will allow you to upload files to the form.

Example:

Schema

UI Schema

{
  "properties": {
    "file": {
      "type": "string",
      "format": "kuflow-file",
      <<options>>
    }
  }
}

Options:

Options	Description
title	Specifies a customized label for the field.
description	Shows a customized message for the field description.
accept	Specifies the acceptable file extensions to be uploaded
maxSize	Specifies a maximum file size acceptance

{
  "type": "Control",
  "scope": "#/properties/file"
}

User

---

Other of our customizations, the user search field will be used when the format: "kuflow-principal" is specified for a string property in the Schema. It will allow you to search users in the organization.

Example:

Schema

UI Schema

{
  "properties": {
    "user": {
      "type": "string",
      "format": "kuflow-principal",
      <<options>>
    }
  }
} 

Options:

Options	Description
title	Specifies a customized label for the field.
description	Shows a customized message for the field description.
groupId	Restrict user search to specified group id, see

For better understanding see the Users Searching Example

{
  "type": "Control",
  "scope": "#/properties/user"
}

Enum Single-Select

---

It is possible to configure a single selection, where only one option can be selected from a drop down list.

Example:

Schema

UI Schema

{
  "properties": {
    "driverLicense": {
      "type": "string",
      "enum": [
        "MOTORBIKE",
        "CAR",
        "TRUCK"
      ],
      <<options>>
    }
  }
}

Alternatively, you could use custom labels for each element in the list:

{
  "properties": {
    "driverLicense": {
      "type": "string",
      "oneOf": [
        {
          "const": "motorbike",
          "title": "MOTORBIKE"
        },
        {
          "const": "car",
          "title": "CAR"
        },
        {
          "const": "truck",
          "title": "TRUCK"
        }
      ],
      <<options>>
    }
  }
}

Options:

Option	Description
title	Specifies a customized label for the field.
description	Shows a customized message for the field description.
default	Specifies a pre-set value for the field.

{
  "type": "Control",
  "scope": "#/properties/driverLicense"
}

Alternatively, you can use the "radius" option, which by default is aligned in columns, and with the "direction" option, you can change its alignment.

Example:

Schema

UI Schema

{
  "properties": {
    "driverLicense": {
      "type": "string",
      "enum": [
        "MOTORBIKE",
        "CAR",
        "TRUCK"
      ],
      <<options>>
    }
  }
}

Alternatively, you could use custom labels for each element in the list:

{
  "properties": {
    "driverLicense": {
      "type": "string",
      "oneOf": [
        {
          "const": "motorbike",
          "title": "MOTORBIKE"
        },
        {
          "const": "car",
          "title": "CAR"
        },
        {
          "const": "truck",
          "title": "TRUCK"
        }
      ],
      <<options>>
    }
  }
}

Options:

Option	Description
title	Specifies a customized label for the field.
description	Shows a customized message for the field description.
default	Specifies a pre-set value for the field.

{
  "type": "Control",
  "scope": "#/properties/driverLicense",
  "options": {
    "format": "radio",
    <<options>>
  }
}

Options:

Option	Description
format	radio: Represents a group of radio buttons
direction	row: Change the layout of the buttons to horizontal

Enum Multiple-Choice

---

KuFlow supports different multiple-choice options, where several options from the list can be selected. By default, it will be represented as checkboxes, but it could be shown as a multi select array setting the keyword "uniqueItems" to false.

Example:

Schema

UI Schema

{
  "properties": {
    "driverLicense": {
      "type": "array",
      "uniqueItems": true,
      "items":{
        "type":"string",
        "enum": [
          "MOTORBIKE",
          "CAR",
          "TRUCK"
        ]
      },
      <<options>>
    }
  }
}

Alternatively, you could use custom labels for each element in the list:

{
  "properties": {
    "driverLicense": {
      "type": "array",
      "uniqueItems": true,
      "items":{
        "type":"string",
        "oneOf": [
        {
          "const": "motorbike",
          "title": "MOTORBIKE"
        },
        {
          "const": "car",
          "title": "CAR"
        },
        {
          "const": "truck",
          "title": "TRUCK"
        }
      ]
      },
      <<options>>
    }
  }
}

Options:

Options	Description
title	Specifies a customized label for the field.
description	Shows a customized message for the field description.
default	Specifies a pre-set value for the field.
minItems	Specifies the minimum length for the array.
maxItems	Specifies the maximum length for the array.

{
  "type": "Control",
  "scope": "#/properties/driverLicense",
  "options": {
    <<option>>
  }
}

Option:

Option	Description
direction	row: Change the layout of the checkboxes to horizontal.2

² Only works with checkbox format.

Array

---

Arrays are structures that allow multiple values to be stored in a single field, similar to a list or set of items in other programming languages.

Example:

Schema

UI Schema

{
  "properties": {
    "example": {
      "type": "array",
      "items": {
        "type": [type],
      },
      <<options>>
    }
  }
}

^{Array items must be of [type] string, number, object, array or boolean}

Options:

Options	Description
title	Specifies a customized label for the field.
description	Shows a customized message for the field description.
items	Used to define the type or types of the elements within the array. It can be a single type or an array of types.
minItems	Specifies the minimum length for the array.
maxItems	Specifies the maximum length for the array.
uniqueItems	Setting the keyword to true ensures that each of the items in an array is unique.

{
  "type": "Control",
  "scope": "#/properties/example",
  "options": {
    <<option>>
  }
}

Option:

Option	Description
showSortButtons	true: Not mandatory, allows the possibility of ordering the items within the same array.
	false: If used, will hide the sort arrows.

Files

---

In case you need to upload more than one file, you can do the following using a variant of our customizations: File

Example:

Schema

UI Schema

{
  "properties": {
    "files": {
      "title": "Files",
      "type": "array",
      "items": {
        "type": "string",
        "format": "kuflow-file"
      }
    }
  }
}

To see the File schema options see File section.

To see the Array schema options see Array section.

{
  "type": "Control",
  "scope": "#/properties/files"
}

To see the Array UI schema options see Array section.

Users

---

To search and select more than one user, you can do the following using a variant of our customizations: User

Example:

Schema

UI Schema

{
  "properties": {
    "users": {
      "title": "Multiple users",
      "type": "array",
      "items": {
        "type": "string",
        "format": "kuflow-principal"
      }
    }
  }
}

To see the User schema options see User section.

To see the Array schema options see Array section.

{
  "type": "Control",
  "scope": "#/properties/users"
}

To see the Array UI schema options see Array section.

Table

---

The "table" component allows you to create dynamic and interactive tables within your forms. It is particularly useful when you need to capture multiple entries or display tabular data.

Example:

Schema

UI Schema

{
  "properties": {
    "table": {
      "type": "array",
      <<options>>,
      "items": {
        "type": "object",
        "required": [
          "key"
        ],
        "properties": {
          "key": {
            "type": "string"
          },
          "name": {
            "type": "string"
          }
        }
      }
    }
  }
}

To see the Array Schema options see Array section.

{
  "type": "Control",
  "scope": "#/properties/table",
  "options": {
    <<option>>
  }
}

To see the Array UI schema options see Array section.

Object

---

The "type: object" is used when you have related fields and need to capture more complex form data. It allows you to define a key-value structure, where each key represents a field in the form. This enables you to organize and structure the data efficiently. With the "object" type, you can capture and display data in a structured manner, making it easier to understand and work with complex form information.

Properties

---

This keyword is used to define the properties (or fields) that are expected to be present within an object. When the "type" keyword is set to "object", the "properties" keyword is used to specify the expected properties and their corresponding schemas.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "age": {
      "type": "number"
    }
  }
}

In this example, the Schema defines an object with two properties: "name" and "age". The "name" property is expected to be a string, while the "age" property is expected to be a number.

Schema

UI Schema

{
  "type": "object",
  <<options>>
}

Options:

Options	Description
properties	Defines the expected properties and their schemas within the object. (as seen in properties example)
required	Specifies an array of property names that must be present in the object.
additionalProperties	Determines whether additional properties are allowed in the object.
minProperties	Sets the minimum number of properties allowed in the object.
maxProperties	Sets the maximum number of properties allowed in the object.
patternProperties	Defines a pattern that properties must match to be considered valid.
dependencies	Specifies dependencies between properties in the object.

NOTE

The type: object in JSON Schema is focused on defining the structure, properties, and constraints of an object data type. It does not directly include UI (User Interface) schema definitions.

Now, in case we wish to add some complexity and better organization to the data structure and its visualization, we can create an object within an object. Let's see how:

Schema

UI Schema

{
  "type": "object",
  "properties": {
    "father": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "age": {
          "type": "integer",
          "minimum": 0,
          "maximum": 200
        }
      }
    },
    "mother": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "age": {
          "type": "integer",
          "minimum": 0,
          "maximum": 200
        }
      }
    }
  }
}       

{
  "type": "VerticalLayout",
  "elements": [
    {
      "type": "Label",
      "text": "Please introduce your Father data"
    },
    {
      "type": "HorizontalLayout",
      "elements": [
        {
          "type": "Control",
          "scope": "#/properties/father/properties/name"
        },
        {
          "type": "Control",
          "scope": "#/properties/father/properties/age"
        }
      ]
    },
    {
      "type": "Label",
      "text": "Please introduce your Mother data"
    },
    {
      "type": "HorizontalLayout",
      "elements": [
        {
          "type": "Control",
          "scope": "#/properties/mother/properties/name"
        },
        {
          "type": "Control",
          "scope": "#/properties/mother/properties/age"
        }
      ]
    }
  ]
}      

The Schema code defines an object type with two nested objects, "father" and "mother". Each nested object has properties for "name" (string type) and "age" (integer type with a minimum of 0 and a maximum of 200). This structure allows you to capture and store information in this way:

{
  "father": {
    "name": "John",
    "age": 33
  },
  "mother": {
    "name": "Jane",
    "age": 32
  }
}

Definitions

---

To avoid repeating the same definitions for each item, it's recommended to use references ($ref) to a previously configured definition.

Example:

As you will see, an object definition called "PersonType" is created using the "definitions" keyword. This definition defines the common structure and properties for a person. Then, the "father" and "mother" properties within the main schema are set to reference the "PersonType" definition using the "$ref" keyword.

Before

After

{
  "type": "object",
  "properties": {
    "father": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "age": {
          "type": "integer",
          "minimum": 0,
          "maximum": 200
        }
      }
    },
    "mother": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "age": {
          "type": "integer",
          "minimum": 0,
          "maximum": 200
        }
      }
    }
  }
}         

{
  "type": "object",
  "definitions": {
    "PersonType": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "age": {
          "type": "integer",
          "minimum": 0,
          "maximum": 200
        }
      }
    }
  },
  "properties": {
    "father": {
      "$ref": "#/definitions/PersonType"
    },
    "mother": {
      "$ref": "#/definitions/PersonType"
    }
  }
}