What is a Form Schema and a Widget?

The Form Schema is a JSON Schema document stored in your app which describes the fields of the Form (= the structure of the model). Such fields in the form are called Widgets. For example the type of the field, validation rules, the title and how to display such a widget in the form.

The syntax of this document is based on the “defacto-standard” JSON schema described here:
JSON Schema.

Here is an example of a simple Form Schema which describes the “person” Form Model:

This would result in a form similar to this example below, where - by default - each widget is rendered into its own row:

Open

As you can see, each field in the JSON form has at least an id (e.g. lastName) and a type (e.g. string). For example:

The field lastName will be rendered to a simple text field which can contain a text. This is the most simple field possible in the Form Schema.

Common Field Attributes and Settings

Label

By default the name of a field will be used as the label of the widget in the form.

The id firstName of a field in the JSON Schema like this:

Would then be rendered to a field with firstName as label like this example:

Open

In order to specify a concrete label, you can use the JSON schema attribute title:

Which would be rendered to something like this (note: firstName was replaced by First Name):

Description (Tooltip)

By default, no hint, tooltip or description is displayed for a widget in the form. In order to show this in the form, you need to add the optional description attribute to the Form Schema as this example shows:

This will then be rendered to a useful hint in the form. Whether it is rendered as a tooltip, a help button or similar, depends on the underlying widget element. By default it is rendered as a tooltip which pops-up on mouse-over like this:

For more info about the keyword description, see the JSON Schema spec: JSON Schema - Generic keywords

Hidden

In order to hide a given widget from being displayed in the form, exclude it in the Form Config & Layout (View).

There is no specific attribute for this in the Form Schema.

Readonly

In order to set a given widget to readonly, use the Form Config & Layout (View). Here you can set the readonly flag per field widget.

There is no specific attribute for this in the Form Schema.

Required

In order to make a field required, you have to add the validation like below in form configuration.

See: https://logabit.atlassian.net/wiki/spaces/DEV/pages/846233616

Widgets Reference

Each field in the Form Schema will be rendered to a form item, called a “widget” using the components of the Quasar framework.

How such a field is rendered to a form widget is mainly defined by its type as defined in the Form Schema. This specifies the default rendering.

For some widgets, the default rendering can be customized. Such additional customizations are typically done in the Form Config.

Text widget

This is how a text widget could look like:

See Quasar: Input | Quasar Framework

In order to define a text field, you have to set the attribute type to string according to json-schema.org in the Form Schema. Here is an example how to define a single text field in a Form Schema:

After the user has clicked on the submit button on the form, the value of this text field will be rendered to this output model:

Constraints

You can define constraints for the text field in order to be able to make sure only text matching these criteria will be accepted as value to this field.

minLength

Defines the minimum required length of the text. If the length of the text is less than this minimum, the text is considered to be not valid.

Example:

In this example, the first name must be at least 2 characters long. So a single character like U would be considered to be not valid. But two characters or more are valid. For example: Max.

maxLength

Defines the maximum length of the text. If the text contains more characters, it is considered to be not valid.

Example:

In this example, the first name must contain more than 10 characters. So the text Max would be valid. But this text would be recognized as invalid: Maximillian.

pattern

This attribute defines a regular expression which must match to the text of the field. If the text doesn’t match to the regex given by pattern, it is recognized as invalid.

Example:

Valid values:

Invalid values:

Textarea widget

A textarea field is based on a text field (it supports the same attributes). It is a bigger text field which can show multi-line text. Such a text area is shown in case maxLength is set to a value > 50.

Example:

By default, this will be rendered to a text area like this:

See Quasar: Input | Quasar Framework

Constraints

Same as for Text field.

Date and time widget

The date and time field is based on a text field according to the https://json-schema.org/understanding-json-schema/reference/string.html specification.

The difference is that the format attribute is set to the required structure and can be one of these:

• date-time

• time

• date

Format: date

Example:

By default, the format date will be rendered to a date field with a date picker:

See Quasar: QDate | Quasar Framework

Localization

In order to localize the format of a date string you have to define a pattern using the mask attribute. This way you can specify how the input and output model should read / write the date and time.

For example:

Would cause the date field to show the selected date as german date in day.month.year format:

The output model would look like this:

Format: time

Example:

The format time will be rendered to a time field with a time picker:

See Quasar: QTime | Quasar Framework

Localization

In order to localize the format of a time string you have to define a pattern using the mask attribute. This way you can specify how the input and output model should read / write the time.

For example:

Would cause the time field to show the selected time in this format:

The output model would look like this:

Format: date-time

Example:

The format date-time will be rendered to a date and time field with a date-time picker:

See Quasar: QDate | Quasar Framework

Localization

In order to localize the format of a date-time string you have to define a pattern using the mask attribute. This way you can specify how the input and output model should read / write the date and time.

For example:

Would cause the date field to show the selected date and time in this format:

The output model would look like this:

Checkbox widget

In order to show a checkbox for a true/false boolean field, you can use the type boolean as defined in the json-schema specs: JSON Schema - boolean

Example:

Valid values for the approved field would then be true or false. But not "true", "false", 0, 1, "yes", "no" for example.

By default, this renders to a checkbox like this:

See Quasar: Checkbox | Quasar Framework

The model for this example could look like this:

Number widget

Example schema:

See Quasar: Input | Quasar Framework

The input and output model for this example could look like this:

Constraints

This field supports constraints to define valid ranges for the given number. See json-schema spec for further details: JSON Schema - Numeric types

multipleOf

The multipleOf constraint defines a rule where the given number must be a multiple of the given constraint.

Example:

In this example, a value of 10 and 100 would be valid whereas 38 or 1 would be considered as invalid.

range

You can also specify a number range in which the given value for the field would considered to be valid. These attributes can be used for this:

Example:

In this example a value >= 18 or <= 99 would be considered to be valid. The values -1, 15, 102 for example would be invalid.

Also exclusiveMinimum and exclusiveMaximum are possible. See the json-spec for more details here:

JSON Schema - Numeric types

Dropdown Widget (single select)

The single select widget gives a list of options the user can select one item from:

Example schema:

See Quasar: https://quasar.dev/vue-components/select

The output model would look like this:

Load items dynamically

The selection items can also be loaded dynamically at runtime. To do so: TODO

Dropdown Widget (multi select)

The multi-select widget provides a list of options from which the user can select one or more items:

See Quasar: https://quasar.dev/vue-components/select

Example:

The data model would look similar to this:

Load items dynamically

The selection items can also be loaded dynamically at runtime. To do so: TODO

Button Widget

A form button is represented as a boolean field in the model JSON. In case this button was clicked, the field value is true. Otherwise false.

Example Form Schema:

The render attribute must be defined in the Form Config inside the layout section:

In case the user has clicked the approveed button, then the resulting model could look like this:

File Upload and Preview Widget

Also see: https://logabit.atlassian.net/wiki/spaces/PA/pages/2545942697.

By default, a file upload widget will be rendered like this in the form:

See Quasar: https://quasar.dev/vue-components/file-picker/

Example Form Schema with a content reference object in it:

Upload Widget

After you have defined the content reference in the Form Schema, you also need to specify in the Form Config how to render this file field. If you set "render": "filepicker" (which is the default) a simple file widget will be shown which opens a file choose in case it gets clicked:

See Quasar: https://quasar.dev/vue-components/file-picker/

Preview Widget

If you set "render": "pdfviewer" PDF previewer will be embedded into the form.

After a PDF has been selected, it will be rendered as preview in the form like this example:

Content Reference

Also see https://logabit.atlassian.net/wiki/spaces/PA/pages/2545320099 .

Since there is no corresponding simple type in the JSON Schema specification to define a file, PIPEFORCE uses a custom object structure called a content reference. A content reference inside a form data JSON could look like this example:

The content reference can be seen as the metadata of a file widget of a form. It contains all required information about a file of the form like its name, length and type for example.

And here is an example of such a content reference in the JSON Schema:

As you can see, the field myFile is of type object since it is a complex field.

The properties of this field are mandatory. They will be filled by the forms framework in case the user has selected a file for upload:

• name: The original name of the file (for example my.pdf). Also paths are supported like myfolder/my.pdf

• contentLength: The content size of the file in bytes.

• contentType: The media type of the file. For example application/pdf.

• contentEncoding: Defines, how the file content is encoded in the content field. Can be one of base64 or outbound-url.

• content: Can be a base64 encoded string which is the content in case contentEncoding:base64 or a custom url pointing to the outbound resource in case contentEncoding:outbound-url which is typically a PIPEFORCE URI pointing to a property. For example $uri:property:path/to/property.

Example content reference with PDF as base64 content (= embedded)

Note that contentEncoding is set to base64 and therefore the attribute content contains the PDF file data as base64 encoded string (so the full PDF data is embedded into the JSON).

Example content reference with PDF as uri content (= outbound)

Note that contentEncoding is set to outbound-url and therefore the attribute content contains a url pointing to the PDF file data to be loaded by the forms framework on form load. In this example this is the path to a property in the property store which contains the file as attachment. The name of the attachment is, by default, the same as the name set by the name attribute of the content reference. In this example this is invoice-123.pdf.

Internationalization (i18n)

The title and description of schema fields (widgets) can be internationalized (= translated to different languages). See here for more details, how this works: Internationalization (i18n).