OmniSchema
Key Roos
05-12-2024
30 minute read
OmniSchema is an extension on JSON Schema to render fillable, validated forms. With metadata properties schema items can be customized and the final JSON is used to render a full form in Vue, validated by Ajv JSON schema validator.
This document describes all form items that can be rendered with OmniSchema, and it lists what properties are needed to render each specific item.
Global schema options and options that apply to (almost) all OmniSchema items.
Global OmniSchema metadata properties
These options apply the schema, not to a specific schema item. They are set on the root-level metadata object.
Property | Type | Description |
display_type | string | The layout the schema is presented in |
hide_empty_values | boolean | This hides items without data in readOnly |
initial_defaults | boolean | Set all defaults values in the data when the schema loads |
mapping_identification | string | Mapping triggered by execute_mapping |
truncate | boolean | Truncate labels in the form |
variables | object[] | A list of variables that can be used in labels and descriptions |
Display
A schema can be displayed in three different layouts, default, tabs and wizard.
Default
The default display shows the schema as a long form with all items rendered underneath one another on a single page. This layout is best for short forms with not a lot of fields to fill in.
Tabs
For the tabs display each root-level item is rendered on a separate page. Tabs are rendered at the top, that allow navigation to the pages. This layout is useful for larger forms with schema items that fall into clear categories. Rendering a large schema in tabs will also increase its performance.
It is recommended to only create root-level items of type object for tabs display.
Wizard
Same as for tabs, each root-level item is rendered on a separate page. Instead of rendering tabs, in a wizard pagination is rendered at the bottom. This layout is useful to guide users through the form in a directed order, forcing them to fill in certain fields first, before they can continue to next page. Rendering a large schema in tabs will also increase its performance.
It is recommended to only create root-level items of type object for wizard display.
Mapping
A mapping identification can be referenced in the schema and chosen schema items can trigger this mapping when their data value changes.
This mapping uses the data value of the entire schema as it’s input and when it finishes, the output is set as the new data value for the schema.
Mapping Example
This has numerous possible uses, one of them being calculating values. Let’s say you have field A and B, which are both number fields and in field C you want to show A and B multiplied. This can be achieved with a mapping that is triggered any time field A or B has their value updated.
In this example field A and B need have the metadata property execute_mapping set to true and field C needs to have mapped_value set to true.
JSON Schema properties
Property | Type | Description |
description | string | Show info text |
readOnly | boolean | Item can’t be edited |
default | any | Default value |
OmniSchema metadata properties
These are the metadata properties that can be applied to (almost) any OmniSchema item. There are more valid metadata properties specific to certain OmniSchema types, those are listed with the type they are meant for under options. The options are set in the metadata of the item, because they are not valid JSON Schema properties.
Property metadata. | Type | Description |
placeholder | string | Show a placeholder text in an input field |
help_message_subtitle | boolean | Show the desc. as a subtitle, not in popover |
description_show_title | boolean | Show item title in description popover |
copyable | boolean | Adds a copy button to the input |
index | string | Index for selection screen |
hidden | boolean | Hide the item |
disabled | any | No input is allowed |
privacy_sensitive | boolean | The value can be privacy sensitive |
execute_mapping | boolean | Execute schema mapping on value change |
mapped_value | boolean | Value comes from the schema mapping |
conditional_rendering | array | List of conditional rendering actions |
grid | object | Layout of the item within the grid |
omniconnect | string | Value is id of Connector to be executed |
These are the metadata properties that can be applied to almost any OmniSchema item. There are more valid metadata properties specific to certain OmniSchema types, those are listed with the type they are meant for under options.
Indexing
In an OmniSchema you can configure what fields need to be indexed for elastic search. This is done by adding index: true to the metadata of the item you want indexed.
Items of type object and array cannot be indexed. For objects you have to index every property separately and for arrays you place the index in the metadata of the items object.
Layout (grid)
The OmniSchema form is rendered in a grid, where, by default, each item uses the full row of 12 columns. For each item you can configure how many columns it should span, if there is enough space, items will render next to each other. This way you can have 3 items of 4 columns rendered next to each other, or one of 8 columns and one of 4 for instance.
OmniConnect
Any item can have an OmniConnect identification set. The referenced OmniConnector is triggered whenever the schema item has its value updated. The entire schema data object is used as the input for the connector and the result can be mapped back to the schema data.
OmniConnectors allow for advanced background operations, making schema’s extremely flexible in what they can do. A good example is automatic address fill. In the schema there is a postal code input field that has an OmniConnector set. When a user enters a value, the OmniConnector searches the address information for the input and the street name and city are mapped to separate fields in the schema.
Validation
These are all possible validations in a schema. It’s listed on each type what validation can be applied to it.
Property | Type | Description |
required | array | The property must exist in the data |
pattern | string | RegEx that the value must match to |
minimum | number | Minimum number value |
maximum | number | Maximum number value |
multipleOf | number | Number value must be a multiple of the given number |
minLength | number | Minimum string length |
maxLength | number | Maximum string length |
minItems | number | Minimum items in an array |
maxItems | number | Maximum items in an array |
uniqueItems | boolean | List can't have duplicate items |
format | string | Value must match a format |
enum | array | Value must match one of the provided |
additionalProperties | boolean | Object can have additional properties |
Required
In a JSON schema required means that a property must exist within an object. Even when this property doesn’t have a value, if it exists, it is valid.
This is the reason why required is not set as a boolean on a schema item, but as an array on items of type object. The array holds the keys of every property that is required within the object.
Nested required
Because required properties must exist within the object, they are not required when the parent object doesn’t exist. To ensure a nested item is always required, the parent object can be made required as well.
Conditional Rendering
With Conditional Rendering the behavior of schema items can change when data values change. Five actions can alter the way the schema item can be interacted with.
Basic and even complex compare statements can be configured to hide, show, disable or require schema items.
A simple example is to show field B when field A has the value true.
Actions
These are the actions that can be applied to field when conditions are met.
Hide
Hide the item when the conditions are met. When the item is hidden, the data value is cleared automatically.
Hide with Data Preservation
Hide the item when the conditions are met, but the data value is not cleared when the item is hidden.
Show
Show the item when the conditions are met. When the item is hidden, the data value is cleared automatically.
Disable
Disable the item when the conditions are met. The value is not cleared when the item is disabled, but the user will no longer be able to change its value.
Require
Make the item required when the conditions are met. The form will validate as invalid if a conditionally required item does not have a value.
Conditions
When the conditions are met, the action is applied to the field. Conditions can be a simple compare statement, but the compare statements can be nested in AND, OR and NOT statements to create complex conditions when needed.
A compare statement always compares a data value of the schema to some other value. This other value can be any type of static value, a string, a boolean, or number etc. but it’s also possible to compare it with another schema data value.
AND
All compare conditions nested in the AND condition must result in true.
OR
At least one of the compare conditions nested in the OR condition must result in true.
NOT
The NOT condition can hold compare statements, AND conditions and OR conditions. The outcome of all conditions must not be true for the action to be applied.
Compare
Comparing values can be compared in the following ways
- eq - Equal
- ne - Not equal
- gt - Greater than
- gte - Greater than or equal
- lt - Less than
- lte - Less than or equal
- includes – An array must include the value
Conditional Select Options
Instead of rendering schema items, it’s also possible to render the options of a select. For this type of Conditional Rendering, it’s only possible to hide, show, and disable the options.
Groups are schema items of type object they can be used to group input fields. This can be useful to apply Conditional Rendering to an entire group of input fields at once, but it is also used to render pages in Tabs and Wizard display.
Tables are lists of groups, where each property in the group is a column in the table.
Property | Type | Description |
properties | object | All schema item objects within the object |
required | array | List of all required properties in the object |
Metadata options
Property | Type | Description |
render_order | array | Array to put the properties in a desired order |
is_table_footer | boolean | An object item can be displayed as the footer of a table. In the table the group should be referenced with a path in the table_footer property. |
Pages and Tabs
To render pages or tabs in Tabs or Wizard display, the root-level items of the OmniSchema should all be groups. Each group is then rendered as separate page.
All OmniSchema item types that allow custom text input.
Text
Type: string
Validation: required, pattern, minLength, maxLength
Textarea
Type: string
Validation: required, pattern, minLength, maxLength
Subtype: textarea
Options:
Property | Type | Description |
textarea_rows | number | Amount of initially shown rows |
Type: string
Validation: required, pattern, minLength, maxLength
Format: email
UUID
Type: string
Validation: required
Format: uuid
URL
Type: string
Validation: required, pattern, minLength, maxLength
Format: uri
Options:
Property | Type | Description |
display | “button” | Show as a clickable button in readOnly |
BSN
Type: string
Validation: required
Format: bsn
Text Editor
Type: string
Validation: required, minLength, maxLength
Subtype: text-editor
options:
Property | Type | Description |
options | array | List of available options for the editor |
All OmniSchema item types that allow number input.
Number
Type: number
Validation: required, pattern, minimum, maximum
Integer
Type: integer
Validation: required, pattern, minimum, maximum
Currency
Type: string
Validation: required, minimum, maximum
subtype: currency
Options:
Property | Type | Description |
currency_type | number | The currency sign to be displayed ($) |
currency_separator | string | Provide a locale value (nl, en) to show either a comma or a dot as the separator |
All OmniSchema item types that allow for date selection.
Time
Type: string
Format: time
Validation: required, format
Options:
Property | Type | Description |
date_format | string | Display format of the time using date-fns |
Date
Type: string
Format: date
Validation: required, format
Options:
Property | Type | Description |
date_format | string | Display format of the date using date-fns |
limitDate | object | Disable before or after a chosen date. |
Date and Time
Date-time values are saved as UTC and displayed as the corresponding date for the time zone of the viewer.
Type: string
Format: date-time
Validation: required, format
Options:
Property | Type | Description |
date_format | string | Display format of the date using date-fns |
limitDate | object | Disable before or after a chosen date. More about limitDate |
Date Range
Type: array
Subtype: date-time-period
Validation: required
Options:
Property | Type | Description |
date_format | string | Display format of the date using date-fns |
limitDate | object | Disable before or after a chosen date. |
Items
Format: date-time
Validation: format
Limit Dates
With the limitDate metadata prop, the selection of dates before or after a chosen date can be disabled.
The chosen date can be one of the three following options.
Today
Disable all dates before or after the date on which the user is selecting a date.
Custom
Disable all dates before or after a provided date.
Schema Value Date
Disable all dates before or after a date provided elsewhere in the schema. This option can be used to disable dates dynamically. A date can be mapped into a hidden schema item for instance.
Limit Date Metadata Object
Property | Type | Value |
disableFutureDates | string | object | • “today” • { customDate: “YYYY-MM-DDTHH:mm:ss.000Z” } • “[PATH TO SCHEMA VALUE]” |
disablePastDates | string | object | • “today” • { customDate: “YYYY-MM-DDTHH:mm:ss.000Z” } • “[PATH TO SCHEMA VALUE]” |
All OmniSchema item types that allow the user to quickly select a value.
Select
Providing an enum for a text input, will render a selection dropdown.
Type: string
Enum: string[]
Validation: enum
Options:
Property | Type | Description |
radio | boolean | Show as radio group |
button | boolean | Show as button group |
show_radio | boolean | Show radio in buttons of button group |
conditional_options | array | Conditional Rendering for select options |
Multiple Select
For a multiple select, create an item of type array, with items of type string.
Type: array
Subtype: multiple-select
Validation: minItems, maxItems
Options:
Property | Type | Description |
checkbox | boolean | Show as checkbox group |
tags_input | boolean | Allow the user to add custom values |
multiple_select_options | array | When tags_input is true, the enum has to be moved to this metadata prop, otherwise custom values are validated as invalid. |
conditional_options | array | Conditional Rendering for select options |
Items (for Multiple Select)
Type: string
Enum: string[]
Validation: enum
Checkbox
A checkbox can be required, but only if you add an enum with the value true.
Type: boolean
Validation: required (enum: [true])
Switch
A switch can be required, but only if you add an enum with the value true.
Type: boolean
Subtype: switch
Validation: required (enum: [true])
Options:
Property | Type | Description |
falseLabel | string | Label to display when value is false |
trueLabel | string | Label to display when value is true |
Rating
Type: integer
Validation: required, minimum, maximum
Subtype: rating
Slider
Type: string
Validation: required, maximum
Subtype: slider
Options:
Property | Type | Description |
step | number | The value of each position on the slider |
showStops | boolean | Display the steps on the slider |
Instance Select
An Instance Select allows the selection of an Omnimap Instance. The selection will copy chosen values from the selected instance over to the schema data.
Type: object
Validation: required
Subtype: instance-select
Options:
Property | Type | Description |
custom_components | boolean | Custom components do not exist within Omnimap but are built in separate project. They are slotted in from the project |
custom_type | string | Should have value “omniselect2” |
omniselect_type | string | Can be search or get. A search requires a query that return the select options. A get requires a path to an Omnimap endpoint. Results of the get must be filtered into an array. |
omniselect_query | object | Provide a query for the Omnimap /search endpoint to retrieve a list of instances to select from. |
omniselect_url | string | Provide an endpoint of the Omnimap API to retrieve results for the selection. These endpoints usually return an object of data, but OmniInstanceSelect requires an array, use omniselect_filter to turn the returned data into an array. |
omniselect_filter | string |
|
omniselect_display | array | Provide an array of paths that direct to values in the results of the query/get. These values are displayed in the selection dropdown, and they are saved when a selection is made. By default, the value for omniselect_display is [“$.name”], which will show the name of the selectable instance in the dropdown. |
omniselect_storage | array | Same as omniselect_display, but these values aren’t displayed in the selection list. By default, there is no value for storage. |
omniselect_search_includes | array | Specify what data should be included in the response of an Instance Select of type query. PROPERTIES, LOCATIONS, CONTENT, MONITORING, CONTEXT. By default only CONTENT and PROPERTIES are returned. |
omniselect_search_characters | number |
|
omniselect_variables | array | Variables can be placed in the query or url of the select. These variables are replaced by chosen data values from the schema. |
omniselect_populate | boolean | Values from the selection can be used to set as the values of other items anywhere in the schema. |
omniselect_populate_fields | array |
|
context_definition_identification | string |
|
omniselect_allow_create | boolean | Shows a button in the selection dropdown to directly start the creation of an instance of the definition type returned from the query. The created instance is automatically selected. |
omniselect_mode | string | By default, the instance select is in select mode. Setting this to create will show the instance select in a mode with the option to select a value from a list. In create mode there is a button to start the creation process of a new instance. When the instance is created, it’s automatically selected. |
omniselect_image | string | Enter a path of an indexed media content value. If the image available it will show in the dropdown at the start of the selectable value. |
omniselect_image_aspect_ratio |
| Aspect ratio of the image provided in omniselect_image. Provide the dimension joined on a /. Example: 16/9, 1/1. |
view_instance | boolean | A button is shown to view the full selected instance. |
Source Select
Type: object
Validation: required
Subtype: source-select
Options:
Location Select
Type: object
Validation: required
Subtype: location
Options:
Property | Type | Description |
custom_components | boolean | Custom components do not exist within Omnimap but are built in a separate project. They are slotted in from the project |
custom_type | string | Should have value “location” |
mapdefinition | String | Identification of a map definition |
map_settings | object |
|
Map Settings
Property | Type | Description |
show_draw_buttons | boolean |
|
draw_options | array | Polygon, Line, DWG |
auto_buffer | boolean |
|
buffer_size | number |
|
filters | object |
|
File upload
Type: string
Validation: required
Format: uuid
Subtype: media
Property | Type | Description |
custom_components | boolean | Custom components do not exist within Omnimap but are built in a separate project. They are slotted in from the project |
custom_type | string | Should have value “media” |
media_definition | string | Identification of a media definition |
All items of OmniSchema can be rendered in a list.
Lists are of type array and require an items property that specifies of what type each item is.
List
Type: array
Validation: required, minItems, maxItems, uniqueItems
Options:
Property | Type | Description |
block_add_array | boolean | Disallow adding new items to the list |
block_delete_array | boolean | Disallow deleting items from the list |
search_boundary | number | Lists become searchable when the length of the list is greater than the search_boundary. The default is 15 |
Items
Type: any
Object List
Lists with items of type object (group)
Type: array
Validation: required, minItems, maxItems, uniqueItems
Options:
Property | Type | Description |
Item_title | string | Key of the property in the object that should be the value of the collapse header of the list item |
block_add_array | boolean | Disallow adding new items to the list |
block_delete_array | boolean | Disallow deleting items from the list |
search_boundary | number | Lists become searchable when the length of the list is greater than the search_boundary. The default is 15 |
Items
Type: object
Table
Object lists can be rendered as a table if the subtype is set to Table. Each property in the properties object within items will become a column in the table.
Type: array
Validation: required, minItems, maxItems, uniqueItems
Subtype: table
Options:
Property | Type | Description |
block_add_array | boolean | Disallow adding new rows to the table |
block_delete_array | boolean | Disallow deleting rows from the table |
page_size | number | A table is automatically paginated. The default page_size is 15 rows. |
search_boundary | number | Tables become searchable when the length of the list is greater than the search_boundary. If the search_boundary is not provided, it is equal to the page_size |
table_footer | string | Path to the schema object that should be rendered as the table footer. |
Items
Type: object
All OmniSchema item types that are meant to display something without allowing user input.
Link
Show a clickable link in the schema. It can link to an external URL, or to an Omnimap instance.
Type: string
Subtype: link
Options:
Property | Type | Description |
linkText | string | Label of the button |
url | string | The URL that the button opens. This a static way of creating a button, but the URL can be dynamic as well. If a value is mapped to the data value of the link, that value is used as the URL. |
linkDisplay | string | By default, the link is shown as a button, but with the value link it is shown a regular link. |
internal | boolean | The link can open an Omnimap Instance if the internal property is set to true. The identification of the instance should be provided in the url property, or for a dynamic solution it should be mapped to the data value of the link. |
Info
Instead of an input, show informational text.
Type: string
Subtype: info
Options:
Property | Type | Description |
Info_text | string | The HTML string |
Image
Show an image in the schema.
Type: string
Subtype: image
Options:
Property | Type | Description |
img_src | string | URL to the image’s location. Same as with the link, the image source can be dynamic by mapping it to the data value of the image item. |
Compare Text
Display differences between two strings. The values should be mapped to the old and new properties in the CompareText object.
Type: object
Subtype: compare-text
Properties
Key | Type | Description |
old | string | The original value |
new | string | The new value to compare with the original |
Threshold
Compare the data value with a set threshold.
Type: number
Subtype: threshold
Options:
Property | Type | Description |
threshold | number | The value to compare to |
Comparator | string | eq, ne, gt, ge, lt, le |
Progress
Show the progress of the current date (today) between a date range in a progress bar. A third date can be added to the array to compare with instead of the current date.
Type: array
Subtype: progress
Items
Type: string
Format: date-time
Instance Reference
Show the content of a selected instance.
Type: string
Subtype:
Options:
QR Code
Show a string value as a QR Code in readOnly.
Type: string
Subtype: qr
Options:
Property | Type | Description |
qr_size | number | The size of the QR code in pixels. |