Form schema
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.
- 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.
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![](/img/fine-grained-concepts/forms-creation-integer.png)
Example:
{
"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
![](/img/fine-grained-concepts/forms-creation-boolean.png)
Example:
{
"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![](/img/fine-grained-concepts/forms-creation-number.png)
Example:
{
"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
![](/img/fine-grained-concepts/forms-creation-string-formats.png)
Example:
{
"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
![](/img/fine-grained-concepts/forms-creation-date.png)
Example:
{
"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
![](/img/fine-grained-concepts/forms-creation-file-upload1.png)
Example:
{
"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.
![](/img/fine-grained-concepts/forms-creation-single-user.png)
Example:
{
"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
![](/img/fine-grained-concepts/forms-creation-enum.png)
Example:
{
"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"
}
![](/img/fine-grained-concepts/forms-creation-enum-radio.png)
Example:
{
"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.
![](/img/fine-grained-concepts/forms-creation-multi-checkbox.png)
Example:
{
"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 |
2 Only works with checkbox format.
Array
![](/img/fine-grained-concepts/forms-creation-array.png)
Example:
{
"properties": {
"example": {
"type": "array",
"items": {
"type": [type],
},
<<options>>
}
}
}
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
![](/img/fine-grained-concepts/forms-creation-file-upload2.png)
Example:
{
"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
![](/img/fine-grained-concepts/forms-creation-user-multi.png)
Example:
{
"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
![](/img/fine-grained-concepts/forms-creation-table.png)
Example:
{
"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.
{
"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. |
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:
![](/img/fine-grained-concepts/forms-creation-object.png)
{
"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.
![](/img/fine-grained-concepts/forms-creation-definition-ref.png)
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.
{
"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"
}
}
}