JSON Schema Human Task

JSON Schema Human Task is a flexible, schema-driven Human Task Type built on the react-jsonschema-form library. It provides a powerful way to create validated forms with dynamic behavior, conditional fields, and custom components.

JSON Schema Human Task can be utilized for:

Creating complex validated forms with dependencies between fields
Building dynamic forms that adapt based on user input
Integrating with EasyRPA Data Stores for dynamic dropdown options
Displaying read-only information alongside editable fields
Handling nested objects and arrays with collapsible sections

Document Type JSON Structure

The Document Type configuration consists:

schema - defines the data structure, types, and validation rules (based on JSON Schema).
uiSchema - controls the visual presentation, widgets, and layout.
document_validator (optional) - custom JavaScript function for additional validation of output parameters.

Below you can find a comprehensive example of the Settings JSON:

JSON Schema Document Type JSON example

{
	"schema": {
		"type": "object",
		"title": "Exception Processing",
		"required": [
			"newTransactionStatus"
		],
		"properties": {
			"formTitle": {
				"title": "UDP Exception Processing"
			},
			"documentId": {
				"title": "Document: ",
				"link": "/data-stores"
			},
			"marks": {
				"type": "array",
				"title": "Document marks",
				"items": {
					"type": "string"
				},
				"readOnly": true,
				"hideIfEmpty": true
			},
			"newTransactionStatus": {
				"type": "string",
				"title": "Restart Processing From",
				"enum": [
					"ABORTED",
					"COMPLETED",
					"PENDING"
				],
				"default": "ABORTED"
			}
		}
	},
	"uiSchema": {
		"ui:layoutGrid": {
			"ui:row": {
				"className": "row",
				"children": [
					{
						"ui:col": {
							"xs": 12,
							"children": [
								"formTitle"
							]
						}
					},
					{
						"ui:col": {
							"xs": 6,
							"children": [
								"documentId"
							]
						}
					},
					{
						"ui:col": {
							"xs": 12,
							"children": [
								"marks"
							]
						}
					},
					{
						"ui:col": {
							"xs": 12,
							"children": [
								"newTransactionStatus"
							]
						}
					}
				]
			}
		},
		"formTitle": {
			"ui:field": "TitleField"
		},
		"documentId": {
			"ui:field": "LinkField"
		},
		"marks": {
			"ui:field": "BadgesField"
		},
		"newTransactionStatus": {
			"ui:widget": "select",
			"ui:placeholder": "Select...",
			"ui:enumNames": [
				"Stop Processing (Abort)",
				"Processing Complete",
				"Pending Review"
			]
		}
	}
}

Field Types

Each field in the properties object must have a type and can include several standard validation keywords.

Common Properties (Available for all types)

type (string) (required) - specifies the data type.
title (string) (optional) - the label displayed for the field.
description (string) (optional) - helper text displayed below the label.
default (any) (optional) - the default value.
enum (list) (optional) - a list of allowed values (renders as a dropdown or radio buttons).
readOnly (boolean) (optional) - prevents user editing.

Specific Field Types

String

minLength / maxLength (number) - constrains text length.
pattern (string) - a regular expression the value must match.
format (string) - predefined formats: email, uri, date, date-time, color.

Number / Integer

minimum / maximum (number) - range constraints.
exclusiveMinimum / exclusiveMaximum (boolean) - if true, it excludes the boundary value.
multipleOf (number) - ensures the value is a multiple of a specific number.

Boolean

Simple true/false field, rendered as a checkbox by default.

{
	"type": "boolean",
	"title": "I agree to terms",
	"default": false
}

Object

Objects allow grouping related fields together. They can be nested and support various validation rules.

Schema Properties:

properties (object) (required) - defines the fields within the object
required (array) - list of required property names
additionalProperties (boolean or object) - controls whether extra properties are allowed
- false: no additional properties allowed
- true: any additional properties allowed
- object: additional properties must match this schema
patternProperties (object) - properties whose names match regex patterns
minProperties / maxProperties (number) - constrains the number of properties
dependencies (object) - defines field dependencies (see Dependencies section)

Example

{
	"type": "object",
	"title": "Address",
	"required": [
		"street",
		"city"
	],
	"properties": {
		"street": {
			"type": "string",
			"title": "Street"
		},
		"city": {
			"type": "string",
			"title": "City"
		},
		"zipCode": {
			"type": "string",
			"title": "ZIP Code"
		}
	}
}

Object with Additional Properties:

{
	"type": "object",
	"properties": {
		"name": {
			"type": "string",
			"title": "Name"
		}
	},
	"additionalProperties": {
		"type": "string"
	}
}

This allows users to add custom key-value pairs beyond the defined properties.

Object with Pattern Properties:

{
	"type": "object",
	"properties": {
		"name": {
			"type": "string",
			"title": "Name"
		}
	},
	"patternProperties": {
		"^config_": {
			"type": "string"
		}
	}
}

Properties matching the pattern ^config_ (e.g., config_timeout, config_retries) must be strings.

Nested Objects:

Objects can contain other objects for complex data structures:

{
	"type": "object",
	"properties": {
		"user": {
			"type": "object",
			"properties": {
				"name": {
					"type": "string"
				},
				"email": {
					"type": "string",
					"format": "email"
				}
			}
		}
	}
}

UI Options for Objects:

Control object display using uiSchema:

{
	"address": {
	"ui:collapsible": true,			 // Make object collapsible (default: true)
	"ui:defaultExpanded": false,		// Start collapsed (default: false)
	"ui:layoutGrid": { ... }			// Apply grid layout to object properties
	}
}

Example from sample.json:

{
	"schema": {
		"humanTaskCompletionDetails": {
			"type": "object",
			"title": "Human Task Completion Details",
			"properties": {
				"completedBy": {
					"type": "string",
					"title": "Completed By"
				},
				"startedAt": {
					"type": "string",
					"title": "Started At"
				},
				"completedAt": {
					"type": "string",
					"title": "Completed At"
				}
			},
			"readOnly": true,
			"hideIfEmpty": true
		}
	},
	"uiSchema": {
		"humanTaskCompletionDetails": {
			"ui:collapsible": false,
			"ui:layoutGrid": {
				"ui:row": {
					"className": "row",
					"children": [
						{
							"ui:col": {
								"xs": 4,
								"children": [
									"completedBy"
								]
							}
						},
						{
							"ui:col": {
								"xs": 4,
								"children": [
									"startedAt"
								]
							}
						},
						{
							"ui:col": {
								"xs": 4,
								"children": [
									"completedAt"
								]
							}
						}
					]
				}
			}
		}
	}
}

Array

Arrays can contain simple values (strings, numbers) or complex objects. They support various configurations for validation and UI behavior.

Schema Properties:

items (object or array) (required) - defines the schema for array items
- If object: all items follow the same schema (variable-length array)
- If array: each position has its own schema (fixed-length tuple)
minItems / maxItems (number) - constrains the number of items
uniqueItems (boolean) - if true, all items must be unique
additionalItems (object) - schema for items beyond those defined in fixed array

Array Types:

Simple Array - array of primitive values:

{
	"type": "array",
	"title": "Tags",
	"items": {
		"type": "string"
	},
	"minItems": 1,
	"maxItems": 5
}

Array of Objects - array of complex items:

{
	"type": "array",
	"title": "Tasks",
	"items": {
		"type": "object",
		"required": [
			"title"
		],
		"properties": {
			"title": {
				"type": "string",
				"title": "Task Title"
			},
			"completed": {
				"type": "boolean",
				"title": "Completed",
				"default": false
			},
			"priority": {
				"type": "string",
				"title": "Priority",
				"enum": [
					"low",
					"medium",
					"high"
				]
			}
		}
	}
}

Multiple Choice (Checkboxes) - array with enum and uniqueItems:

{
	"type": "array",
	"title": "Select Options",
	"items": {
		"type": "string",
		"enum": [
			"option1",
			"option2",
			"option3"
		]
	},
	"uniqueItems": true
}

Use "ui:widget": "checkboxes" in uiSchema to render as checkboxes.

Fixed Array (Tuple) - array with different types at each position:

{
	"type": "array",
	"title": "Person Info",
	"items": [
		{
			"type": "string",
			"title": "First Name"
		},
		{
			"type": "string",
			"title": "Last Name"
		},
		{
			"type": "number",
			"title": "Age"
		}
	]
}

UI Options for Arrays:

Configure array behavior in uiSchema using ui:options:

{
	"tasks": {
	"ui:options": {
		"orderable": true, // Enable reordering items (default: true)
		"addable": true, // Show add button (default: true)
		"removable": true, // Show remove button (default: true)
		"copyable": false // Show copy button (default: false)
	}
	}
}

Example from sample.json:

{
	"schema": {
		"errors": {
			"type": "array",
			"title": "Errors",
			"items": {
				"type": "object",
				"properties": {
					"errorType": {
						"type": "string",
						"title": "Error Type",
						"readOnly": true
					},
					"errorMessage": {
						"type": "string",
						"title": "Error Message"
					}
				}
			}
		}
	},
	"uiSchema": {
		"errors": {
			"ui:options": {
				"orderable": false,
				"removable": false,
				"addable": false
			}
		}
	}
}

Schema Composition (oneOf, anyOf, allOf)

Schema composition keywords allow you to combine multiple schemas to create complex validation rules and conditional field structures.

oneOf - Exactly One Schema Must Match

The oneOf keyword ensures that exactly one of the provided subschemas is valid. This is useful for mutually exclusive options.

Basic oneOf Example:

{
	"type": "object",
	"oneOf": [
		{
			"properties": {
				"paymentType": {
					"type": "string",
					"const": "credit_card"
				},
				"cardNumber": {
					"type": "string",
					"title": "Card Number"
				}
			},
			"required": [
				"paymentType",
				"cardNumber"
			]
		},
		{
			"properties": {
				"paymentType": {
					"type": "string",
					"const": "paypal"
				},
				"email": {
					"type": "string",
					"format": "email",
					"title": "PayPal Email"
				}
			},
			"required": [
				"paymentType",
				"email"
			]
		}
	]
}

oneOf with Discriminator:

Use the discriminator property to help the form identify which schema to use based on a specific field:

{
	"type": "object",
	"discriminator": {
		"propertyName": "shape"
	},
	"oneOf": [
		{
			"properties": {
				"shape": {
					"type": "string",
					"const": "circle"
				},
				"radius": {
					"type": "number",
					"title": "Radius"
				}
			},
			"required": [
				"shape",
				"radius"
			]
		},
		{
			"properties": {
				"shape": {
					"type": "string",
					"const": "rectangle"
				},
				"width": {
					"type": "number",
					"title": "Width"
				},
				"height": {
					"type": "number",
					"title": "Height"
				}
			},
			"required": [
				"shape",
				"width",
				"height"
			]
		}
	]
}

anyOf - At Least One Schema Must Match

The anyOf keyword validates if at least one of the subschemas is valid. Multiple schemas can match simultaneously.

Basic anyOf Example:

{
	"type": "object",
	"anyOf": [
		{
			"properties": {
				"firstName": {
					"type": "string",
					"title": "First Name"
				}
			},
			"required": [
				"firstName"
			]
		},
		{
			"properties": {
				"firstName": {
					"type": "string",
					"title": "First Name"
				},
				"lastName": {
					"type": "string",
					"title": "Last Name"
				}
			}
		}
	]
}

anyOf with Custom Titles:

Override titles for anyOf options using uiSchema:

Basic Object:

{
	"schema": {
		"type": "object",
		"anyOf": [
			{
				"type": "string",
				"title": "String Option"
			},
			{
				"type": "number",
				"title": "Number Option"
			},
			{
				"type": "boolean",
				"title": "Boolean Option"
			}
		]
	},
	"uiSchema": {
		"anyOf": [
			{
				"ui:title": "Enter Text"
			},
			{
				"ui:title": "Enter Number"
			},
			{
				"ui:title": "Yes or No"
			}
		]
	}
}

allOf - All Schemas Must Match

The allOf keyword combines multiple schemas. The data must be valid against all of them simultaneously. This is useful for schema composition and inheritance.

Basic allOf Example:

{
	"allOf": [
		{
			"type": "object",
			"properties": {
				"name": {
					"type": "string",
					"title": "Name"
				}
			},
			"required": [
				"name"
			]
		},
		{
			"properties": {
				"email": {
					"type": "string",
					"format": "email",
					"title": "Email"
				}
			},
			"required": [
				"email"
			]
		}
	]
}

allOf with Conditional Defaults:

Combine allOf with if-then-else for conditional field behavior:

Basic Object:

{
	"type": "object",
	"properties": {
		"accountType": {
			"type": "string",
			"enum": [
				"personal",
				"business"
			],
			"title": "Account Type"
		}
	},
	"allOf": [
		{
			"if": {
				"properties": {
					"accountType": {
						"const": "personal"
					}
				}
			},
			"then": {
				"properties": {
					"firstName": {
						"type": "string",
						"title": "First Name"
					},
					"lastName": {
						"type": "string",
						"title": "Last Name"
					}
				},
				"required": [
					"firstName",
					"lastName"
				]
			}
		},
		{
			"if": {
				"properties": {
					"accountType": {
						"const": "business"
					}
				}
			},
			"then": {
				"properties": {
					"companyName": {
						"type": "string",
						"title": "Company Name"
					},
					"taxId": {
						"type": "string",
						"title": "Tax ID"
					}
				},
				"required": [
					"companyName",
					"taxId"
				]
			}
		}
	]
}

Comparison Table

Keyword	Validation Rule	Use Case
oneOf	Exactly one schema must match	Mutually exclusive options (e.g., payment methods)
anyOf	At least one schema must match	Multiple valid configurations
allOf	All schemas must match	Schema composition, inheritance, conditional logic

The sample.json uses dependencies with oneOf for conditional field visibility:

{
	"schema": {
		"newTransactionStatus": {
			"type": "string",
			"enum": [
				"ABORTED",
				"CLASSIFICATION_COMPLETED",
				"COMPLETED"
			]
		}
	},
	"dependencies": {
		"newTransactionStatus": {
			"oneOf": [
				{
					"properties": {
						"newTransactionStatus": {
							"enum": [
								"CLASSIFICATION_COMPLETED"
							]
						},
						"ef_category": {
							"type": "string",
							"title": "Document Category"
						}
					},
					"required": [
						"ef_category"
					]
				},
				{
					"properties": {
						"newTransactionStatus": {
							"enum": [
								"ABORTED"
							]
						},
						"ef_error_code": {
							"type": "string",
							"title": "Error Code"
						}
					},
					"required": [
						"ef_error_code"
					]
				},
				{
					"properties": {
						"newTransactionStatus": {
							"enum": [
								"COMPLETED"
							]
						}
					}
				}
			]
		}
	}
}

Layout Grid Configuration

Layout Grid allows you to organize fields into a responsive, multi-column layout using the Bootstrap grid system. It can be applied to any object (including the root form).

To enable grid layout, use the custom field "ui:field": "LayoutGridField" in your uiSchema.

How to use?

Grid layout is configured in the uiSchema using the LayoutGridField custom component.

1. schema requirements

There are no special requirements for the schema. You simply define the fields as part of an object.

"schema": {
	"type": "object",
	"properties": {
	"first": { "type": "string", "title": "First" },
	"second": { "type": "string", "title": "Second" }
	}
}

2. uiSchema configuration

Configure the grid using the ui:layoutGrid property.

"uiSchema": {
	"ui:field": "LayoutGridField",
	"ui:layoutGrid": {
	"ui:row": {
		"className": "row",
		"children": [
		{
			"ui:col": {
			"xs": 12,
			"md": 6,
			"children": ["first"]
			}
		},
		{
			"ui:col": {
			"xs": 12,
			"md": 6,
			"children": ["second"]
			}
		}
		]
	}
	}
}

Grid Options

ui:field (string) - must be set to "LayoutGridField" to enable grid layout
ui:layoutGrid (object) - contains the grid configuration
- ui:row (object) - the container for columns
  - className (string) - Standard Bootstrap class (e.g. "row", "row align-items-center")
  - children (array) - List of column configurations
- ui:col (object) - defines column width and content
  - xs, sm, md, lg, xl (number) - Grid size (1-12) according to Bootstrap breakpoints
    - xs - extra small screens (< 576px)
    - sm - small screens (≥ 576px)
    - md - medium screens (≥ 768px)
    - lg - large screens (≥ 992px)
    - xl - extra large screens (≥ 1200px)
  - children (array) - List of field names from the schema to render inside this column

Nested Grid Layouts

You can apply grid layouts to nested objects as well:

{
	"uiSchema": {
		"address": {
			"ui:layoutGrid": {
				"ui:row": {
					"className": "row",
					"children": [
						{
							"ui:col": {
								"xs": 12,
								"md": 6,
								"children": [
									"street"
								]
							}
						},
						{
							"ui:col": {
								"xs": 12,
								"md": 6,
								"children": [
									"city"
								]
							}
						}
					]
				}
			}
		}
	}
}

Available Widgets

Widgets define the input control used to render a field. Apply using "ui:widget": "widgetName" in uiSchema.

Standard Widgets (react-jsonschema-form)

For `boolean` fields

radio - radio button group with true/false options
select - dropdown with true/false options
default: checkbox

For `string` fields

textarea - multi-line text input
password - masked password input
color - color picker
email / uri / date / date-time / time - based on format
default: regular text input

For `number` and `integer` fields

updown - number input with up/down buttons
range - slider
radio - radio buttons for enum values
default: number input

Other

hidden - hidden field
file - file upload (use with format: "data-url")

Custom Widgets

SelectWidget

Custom select dropdown with improved handling of initialization values.

Widget Name: SelectWidget
Difference from standard rjsf select: When the input value is not present in the available options (enum), the standard rjsf select displays the raw value. SelectWidget handles this case gracefully by displaying an empty selection instead.

Custom Fields Reference

Custom fields are applied using "ui:field": "FieldName" and can completely change the rendering of a property.

1. TitleField

Displays a large section heading.

Used with: Any property where you want a header label.
Schema: Uses title property.

Example:

"sectionHeader": { "title": "Main Information" }
"sectionHeader": { "ui:field": "TitleField" }

2. LinkField

Displays one or more clickable links.

Used with: String fields that contain URLs, or special Link Objects from Input JSON.
Schema: Supports a custom link property to define a base URL, which is then extended by input data.
Rendering: Renders as a blue hyperlink.

3. BadgesField

Converts an array of strings into a list of styled badges (pills).

Used with: Array of strings (e.g., document tags, OCR marks).
Styling: Each item is rendered with a gray background and rounded corners.

4. TextareaField

Provides a large text input area with optional collapsible support.

Collapsible Feature: Controlled by "collapsible": true in the schema.
Collapsing Behavior: If collapsible, the textarea starts in a compact state and expands only when clicked or when it has focus. Useful for long descriptions or error logs.

5. DynamicSelectField

A powerful field that connects to EasyRPA Data Stores to provide dynamic options.

Specific Schema Keywords:
- dataStore: Name of the Data Store to search.
- textName: Field name from the Data Store record to use as the value.
- filter: Object defining search criteria (e.g. {"status": [{"predicate": "EQUALS", "value": "ACTIVE"}]}).
Behavior: Fetches options from the server and shows a loading spinner while data is being retrieved.

Custom Schema Keywords (Custom)

These keywords extend standard JSON Schema to provide extra functionality in this application:

hideIfEmpty (boolean) - hides the field from the form if it is not populated by the Input JSON.
collapsible (boolean) - used with TextareaField to make it collapsible.
dataStore (string) - used with DynamicSelectField to link to an EasyRPA Data Store.
link (string) - used with LinkField to define a base link path.

Custom Validation (document_validator)

The document_validator is a custom JavaScript function defined in settings for additional validation of output parameters beyond standard JSON Schema validation.

Location: settings.document_validator
Type: string (JavaScript function)
Input: Receives the form data object (document)
Output: Returns an array of error messages (empty array = valid)

Example

{
	"settings": {
		"document_validator": "document => {
const result = [];
if (document.status === 'active' && !document.category) {
result.push('Category is required when status is active');
}
return result;
}"
	}
}

The function runs after standard form validation. If it returns errors, they are displayed alongside field-level validation errors.

Input JSON Structure

The Input JSON populates the form with initial data and can dynamically modify field properties.

Input JSON Processing Rules

Link Merging: Objects with link or title from Input JSON are merged into the schema, allowing you to dynamically set link labels and URLs.
Placeholder Replacement: Schema defaults like placeholder_xxx are replaced by input values (e.g., "user": "Alex" replaces placeholder_user).
Overrides: Allows modifying schema properties (title, readOnly, etc.) at runtime for specific fields.
Hide If Empty: Fields with "hideIfEmpty": true are removed if missing in Input JSON.

Output JSON Structure

The Output JSON represents the resulting form data after user submission. The output structure strictly follows the property names defined in the schema.

Important Architectural Note:

The JSON Schema Human Task does not process or utilize the incoming outputJson object.

JSON Schema Human Task

Document Type JSON Structure

Field Types

Common Properties (Available for all types)

Specific Field Types

String

Number / Integer

Boolean

Object

Array

Schema Composition (oneOf, anyOf, allOf)

oneOf - Exactly One Schema Must Match

anyOf - At Least One Schema Must Match

allOf - All Schemas Must Match

Comparison Table

Layout Grid Configuration

How to use?

1. schema requirements

2. uiSchema configuration

Grid Options

Nested Grid Layouts

Available Widgets

Standard Widgets (react-jsonschema-form)

For boolean fields

For string fields

For number and integer fields

Other

Custom Widgets

SelectWidget

Custom Fields Reference

1. TitleField

2. LinkField

3. BadgesField

4. TextareaField

5. DynamicSelectField

Custom Schema Keywords (Custom)

Custom Validation (document_validator)

Input JSON Structure

Input JSON Processing Rules

Output JSON Structure

For `boolean` fields

For `string` fields

For `number` and `integer` fields