From 83cd32d5cd72e89eab5a3ac2ab3d4ad8eae3c143 Mon Sep 17 00:00:00 2001 From: Mystypix Date: Wed, 18 Mar 2026 13:41:34 +0100 Subject: [PATCH 1/2] Updated json schema documentation --- .../ui-options/configuration-schema.md | 69 ++++++- .../configuration-schema-examples.md | 183 +++++++++++++++++- 2 files changed, 242 insertions(+), 10 deletions(-) diff --git a/extend/component/ui-options/configuration-schema.md b/extend/component/ui-options/configuration-schema.md index 5cfb600e..1b056850 100644 --- a/extend/component/ui-options/configuration-schema.md +++ b/extend/component/ui-options/configuration-schema.md @@ -22,13 +22,58 @@ Using the configuration schema also allows us to validate the user input on fron JSON schemas are well documented on the [json-schema.org](https://json-schema.org/) website. -We use [JSON Editor](https://github.com/json-editor/json-editor) for displaying a schema. -The supported formatting options for -the editor are available in the [official editor documentation](https://github.com/json-editor/json-editor#format). - -For developing and testing, -use, for example, JSON Editor available [on-line](http://jeremydorn.com/json-editor/), or the -[JSON-Editor Interactive Playground](https://pmk65.github.io/jedemov2/dist/demo.html). +We use [RJSF (React JSON Schema Form)](https://rjsf-team.github.io/react-jsonschema-form/) for rendering schemas +into forms. The schema supports standard JSON Schema properties as well as custom extensions documented +in [UI Element Examples](/extend/component/ui-options/configuration-schema/examples/) and +[Sync Action Examples](/extend/component/ui-options/configuration-schema/sync-action-examples/). + +### Supported Formats + +The following `format` values are supported in property definitions: + +| Format | Type | Description | +|---|---|---| +| `password` | string | Masked password input with show/hide toggle | +| `textarea` | string | Multi-line text area | +| `editor` | string/object | CodeMirror code editor (JSON, SQL, Python, etc.) | +| `date` | string | Date picker input | +| `checkbox` | boolean | Checkbox toggle | +| `radio` | string | Radio button group (requires `enum`) | +| `select` | array | Multi-select dropdown (with `uniqueItems: true`) | +| `trim` | string | Standard text input with automatic whitespace trimming | +| `grid` / `grid-strict` | object | Responsive grid layout for grouped fields | +| `tabs` / `tabs-top` / `categories` | object | Tabbed layout for grouped fields | +| `table` | array | Editable table for arrays of objects | +| `info` | any | Static informational alert (uses `title` as message) | +| `ssh-editor` | object | SSH key/form editor | +| `sync-action` | button | Action button triggering a sync action | +| `test-connection` | button | Connection test button | + +### Supported Options + +The following `options` keys can be used in property definitions: + +| Option | Description | +|---|---| +| `options.async` | Dynamic option loading via sync actions. See [Sync Action Examples](/extend/component/ui-options/configuration-schema/sync-action-examples/). | +| `options.dependencies` | Conditional field visibility based on other field values. See [Dynamic Options](/extend/component/ui-options/configuration-schema/examples/#changing-set-of-options-dynamically-based-on-selection). | +| `options.tags` | Enable tag-style input for multi-select arrays | +| `options.creatable` | Allow user-created values in select dropdowns | +| `options.tooltip` | Help text displayed as a tooltip | +| `options.enum_titles` | Display labels for `enum` values | +| `options.hidden` | Hide the field from the UI | +| `options.collapsed` | Start object sections in collapsed state | +| `options.disable_collapse` | Prevent collapsing of object sections | +| `options.enabled` | Set to `false` to disable a field | +| `options.grid_columns` | Number of grid columns (1–12) in `grid`/`grid-strict` layouts | +| `options.grid_break` | Force a new row in grid layouts | +| `options.editor` | CodeMirror editor options: `mode`, `lineNumbers`, `lint`, `input_height` | +| `options.input_height` | Height for textarea fields (e.g., `"100px"`) | +| `options.inputAttributes` | HTML input attributes (e.g., `placeholder`) | +| `options.only_keys` | SSH editor variant showing only key fields | +| `options.disable_array_add` | Disable adding items to arrays | +| `options.disable_array_delete` | Disable removing items from arrays | +| `options.disable_array_reorder` | Disable reordering items in arrays | ### Example Let's assume your component accepts the following configuration: @@ -98,7 +143,7 @@ The form above can be created using this JSON Schema: {% endhighlight %} ### Links Example -If you want to provide links to external resources, keep in mind that the configuration schema does not support markdown, +If you want to provide links to external resources, keep in mind that the configuration schema does not support markdown, but it has a `links` feature. The above example can be modified so that the links are clickable: {% highlight json %} @@ -130,7 +175,7 @@ but it has a `links` feature. The above example can be modified so that the link "dateFrom": { "title": "Date from", "type": "string", - "description": "Any date accepted by the strtotime function", + "description": "Any date accepted by the strtotime function", "minLength": 1, "default": "", "propertyOrder": 3, @@ -163,3 +208,9 @@ Which renders like this: {: .image-popup} ![Configuration Schema with links](/extend/component/ui-options/configuration-schema-2.png) + +### Deprecated Features + +The following features from the legacy JSON Editor library are **no longer supported**: + +- **`enumSource` / `watch`** — Dynamic enum population based on other field values. Use `options.async` with `autoload` instead for cascading dropdowns. See [Sync Action Examples](/extend/component/ui-options/configuration-schema/sync-action-examples/#autoload). diff --git a/extend/component/ui-options/ui-examples/configuration-schema-examples.md b/extend/component/ui-options/ui-examples/configuration-schema-examples.md index 0d93bc0a..17c00059 100644 --- a/extend/component/ui-options/ui-examples/configuration-schema-examples.md +++ b/extend/component/ui-options/ui-examples/configuration-schema-examples.md @@ -410,7 +410,7 @@ In some cases, a different set of options is available for different types of th JSON Schema allows to define different schemas based on selection. This may be useful in the configuration rows scenario, where each row could represent a different type of Report, Endpoint, etc. -This can be achieved via [dependencies](https://github.com/json-editor/json-editor#dependencies).* +This can be achieved via `options.dependencies`. When the dependency conditions are met, the field is shown; otherwise it is hidden. ```json @@ -463,3 +463,184 @@ You can also react on multiple array values or on multiple elements at the same } } ``` + +You can also reference nested fields using dot notation with a `root.` prefix: + +```json +"options": { + "dependencies": { + "root.credentials.#api_token": "" + } +} +``` + +This shows the field only when the `#api_token` field inside the `credentials` object is empty. + + +### Radio Buttons + +Use `format: "radio"` with an `enum` to render radio buttons instead of a dropdown: + +```json +{ + "output_format": { + "type": "string", + "title": "Output Format", + "enum": ["csv", "json", "parquet"], + "format": "radio", + "default": "csv", + "propertyOrder": 1 + } +} +``` + + +### Date Picker + +Use `format: "date"` for a date input with a calendar picker. Values are stored as `YYYY-MM-DD` strings: + +```json +{ + "start_date": { + "type": "string", + "title": "Start Date", + "format": "date", + "propertyOrder": 1 + } +} +``` + + +### Grid Layout + +Use `format: "grid"` or `format: "grid-strict"` on an object to arrange its properties in a responsive 12-column grid. +Each property can specify `options.grid_columns` (1–12) to control its width. Use `options.grid_break` to force a new row: + +```json +{ + "connection": { + "type": "object", + "title": "Connection", + "format": "grid-strict", + "properties": { + "host": { + "type": "string", + "title": "Hostname", + "propertyOrder": 1, + "options": { "grid_columns": 8 } + }, + "port": { + "type": "integer", + "title": "Port", + "propertyOrder": 2, + "options": { "grid_columns": 4 } + }, + "database": { + "type": "string", + "title": "Database", + "propertyOrder": 3, + "options": { "grid_break": true } + } + } + } +} +``` + + +### Collapsible Sections + +Use `options.collapsed` on an object to make it collapsible. Set `options.disable_collapse` to prevent the user from collapsing it: + +```json +{ + "advanced": { + "type": "object", + "title": "Advanced Settings", + "options": { + "collapsed": true + }, + "properties": { + "timeout": { "type": "integer", "title": "Timeout" } + } + } +} +``` + + +### Disabled Fields + +Use `options.enabled: false` to render a field as read-only: + +```json +{ + "locked_field": { + "type": "string", + "title": "Locked Value", + "default": "Cannot be changed", + "options": { + "enabled": false + } + } +} +``` + + +### Info Blocks + +Use `format: "info"` to display a static informational message. The `title` property is used as the message text: + +```json +{ + "notice": { + "title": "This component requires an API token to function.", + "format": "info", + "propertyOrder": 1 + } +} +``` + +#### Alert Type + +By default, info blocks render as an informational (blue) alert. Use `options.alert_type` to change the visual style. Supported values: `"info"` (default), `"warning"`, `"error"`, `"success"`. + +```json +{ + "missing_token_warning": { + "title": "WARNING: API token is required!", + "format": "info", + "options": { + "alert_type": "warning" + } + } +} +``` + +```json +{ + "config_error": { + "title": "Configuration is invalid.", + "description": "Please check the required fields below.", + "format": "info", + "options": { + "alert_type": "error" + } + } +} +``` + +Info blocks can be combined with `options.dependencies` to show warnings conditionally: + +```json +{ + "missing_token_warning": { + "title": "WARNING: API token is required!", + "format": "info", + "options": { + "alert_type": "warning", + "dependencies": { + "root.credentials.#api_token": "" + } + } + } +} +``` From b11460f98358b0061d1291c9876246ac6b9f1672 Mon Sep 17 00:00:00 2001 From: Mystypix Date: Thu, 26 Mar 2026 14:03:41 +0100 Subject: [PATCH 2/2] fix: update docs to match actual RJSF implementation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Remove `format: "select"` from formats table (not a distinct format) - Add `options.documentation` to supported options (link icon with tooltip) - Note that `options.tooltip` supports Markdown - Fix `enumSource`/`watch` — NOT deprecated, still supported (moved to Legacy) - Mark `links` as deprecated (not supported in RJSF), suggest `options.documentation` - Add examples for tooltips and documentation links - Add `options.documentation` migration example in Links section Co-Authored-By: Claude Opus 4.6 (1M context) --- .../ui-options/configuration-schema.md | 48 +++++++++++++++---- .../configuration-schema-examples.md | 41 ++++++++++++++-- 2 files changed, 75 insertions(+), 14 deletions(-) diff --git a/extend/component/ui-options/configuration-schema.md b/extend/component/ui-options/configuration-schema.md index 1b056850..f3e9460c 100644 --- a/extend/component/ui-options/configuration-schema.md +++ b/extend/component/ui-options/configuration-schema.md @@ -29,7 +29,7 @@ in [UI Element Examples](/extend/component/ui-options/configuration-schema/examp ### Supported Formats -The following `format` values are supported in property definitions: +The following `format` values are supported in property definitions. The **Type** column shows the underlying JSON Schema `type`; italicized entries are descriptive notes, not literal `type` values. | Format | Type | Description | |---|---|---| @@ -39,15 +39,14 @@ The following `format` values are supported in property definitions: | `date` | string | Date picker input | | `checkbox` | boolean | Checkbox toggle | | `radio` | string | Radio button group (requires `enum`) | -| `select` | array | Multi-select dropdown (with `uniqueItems: true`) | | `trim` | string | Standard text input with automatic whitespace trimming | | `grid` / `grid-strict` | object | Responsive grid layout for grouped fields | | `tabs` / `tabs-top` / `categories` | object | Tabbed layout for grouped fields | | `table` | array | Editable table for arrays of objects | -| `info` | any | Static informational alert (uses `title` as message) | +| `info` | *any JSON Schema type* | Static informational alert (uses `title` as message; Keboola UI extension) | | `ssh-editor` | object | SSH key/form editor | -| `sync-action` | button | Action button triggering a sync action | -| `test-connection` | button | Connection test button | +| `sync-action` | *Keboola UI button widget* | Action button triggering a sync action (not a JSON Schema `type`) | +| `test-connection` | *Keboola UI button widget* | Connection test button (not a JSON Schema `type`) | ### Supported Options @@ -56,10 +55,11 @@ The following `options` keys can be used in property definitions: | Option | Description | |---|---| | `options.async` | Dynamic option loading via sync actions. See [Sync Action Examples](/extend/component/ui-options/configuration-schema/sync-action-examples/). | -| `options.dependencies` | Conditional field visibility based on other field values. See [Dynamic Options](/extend/component/ui-options/configuration-schema/examples/#changing-set-of-options-dynamically-based-on-selection). | +| `options.dependencies` | Conditional field visibility based on other field values. See [Dynamic Options](/extend/component/ui-options/configuration-schema/examples/#conditionally-showing-fields-based-on-selection). | | `options.tags` | Enable tag-style input for multi-select arrays | | `options.creatable` | Allow user-created values in select dropdowns | -| `options.tooltip` | Help text displayed as a tooltip | +| `options.tooltip` | Help text displayed as a tooltip icon next to the field label. Supports Markdown syntax. | +| `options.documentation` | Documentation link rendered as a book icon next to the field label. Value: `{ "link": "https://...", "tooltip": "optional hover text" }` | | `options.enum_titles` | Display labels for `enum` values | | `options.hidden` | Hide the field from the UI | | `options.collapsed` | Start object sections in collapsed state | @@ -143,8 +143,30 @@ The form above can be created using this JSON Schema: {% endhighlight %} ### Links Example -If you want to provide links to external resources, keep in mind that the configuration schema does not support markdown, -but it has a `links` feature. The above example can be modified so that the links are clickable: + +***Note:** The `links` feature is deprecated. Use `options.documentation` instead (see [Supported Options](#supported-options)).* + +If you want to provide links to external resources, use `options.documentation` to add a clickable documentation icon next to the field label: + +{% highlight json %} +{ + "dateFrom": { + "title": "Date from", + "type": "string", + "description": "Any date accepted by the strtotime function", + "options": { + "documentation": { + "link": "https://www.php.net/manual/en/function.strtotime.php", + "tooltip": "strtotime Documentation" + } + } + } +} +{% endhighlight %} + +#### Legacy links feature (deprecated) + +The old `links` property is **no longer supported**. If you have existing schemas using it, migrate to `options.documentation`: {% highlight json %} { @@ -209,8 +231,14 @@ Which renders like this: {: .image-popup} ![Configuration Schema with links](/extend/component/ui-options/configuration-schema-2.png) +### Legacy Features + +The following features are still supported for backwards compatibility but have preferred alternatives: + +- **`enumSource` / `watch`** — Dynamic enum population based on other field values. For new schemas, prefer `options.async` with sync actions instead. See [Sync Action Examples](/extend/component/ui-options/configuration-schema/sync-action-examples/#autoload). + ### Deprecated Features The following features from the legacy JSON Editor library are **no longer supported**: -- **`enumSource` / `watch`** — Dynamic enum population based on other field values. Use `options.async` with `autoload` instead for cascading dropdowns. See [Sync Action Examples](/extend/component/ui-options/configuration-schema/sync-action-examples/#autoload). +- **`links`** — Clickable links on field descriptions. Use `options.documentation` with `link` and optional `tooltip` instead. diff --git a/extend/component/ui-options/ui-examples/configuration-schema-examples.md b/extend/component/ui-options/ui-examples/configuration-schema-examples.md index 17c00059..01f58ce7 100644 --- a/extend/component/ui-options/ui-examples/configuration-schema-examples.md +++ b/extend/component/ui-options/ui-examples/configuration-schema-examples.md @@ -404,11 +404,11 @@ The above code will create the following user interface: ![optional block](/extend/component/ui-options/ui-examples/optional_block_array.gif) -### Changing Set of Options Dynamically Based on Selection +### Conditionally Showing Fields Based on Selection -In some cases, a different set of options is available for different types of the same object, e.g., Report type. -JSON Schema allows to define different schemas based on selection. -This may be useful in the configuration rows scenario, where each row could represent a different type of Report, Endpoint, etc. +In some cases, additional options should only be shown when a related setting is enabled, e.g., when a particular report feature is turned on. +JSON Schema UI options allow you to control field visibility based on the values of other fields. +This may be useful in configuration rows, where each row can expose extra options depending on how a user configures it. This can be achieved via `options.dependencies`. When the dependency conditions are met, the field is shown; otherwise it is hidden. @@ -477,6 +477,39 @@ You can also reference nested fields using dot notation with a `root.` prefix: This shows the field only when the `#api_token` field inside the `credentials` object is empty. +### Tooltips and Documentation Links + +Use `options.tooltip` to add a help icon next to the field label. The tooltip content supports **Markdown** syntax: + +```json +{ + "api_key": { + "type": "string", + "title": "API Key", + "options": { + "tooltip": "Your API key from the [dashboard](https://example.com/dashboard).\n\n**Note:** Keep this value secret." + } + } +} +``` + +Use `options.documentation` to add a clickable documentation link icon: + +```json +{ + "query": { + "type": "string", + "title": "SQL Query", + "options": { + "documentation": { + "link": "https://docs.example.com/sql-reference", + "tooltip": "Open SQL reference" + } + } + } +} +``` + ### Radio Buttons Use `format: "radio"` with an `enum` to render radio buttons instead of a dropdown: