Skip to content

Commit bfed6a4

Browse files
MystypixMystypix
authored
Merge pull request #372 from keboola/mystypix-ut-3614-json-schema-updates
Updated json schema documentation
2 parents bf907b0 + b11460f commit bfed6a4

File tree

2 files changed

+308
-15
lines changed

2 files changed

+308
-15
lines changed

‎extend/component/ui-options/configuration-schema.md‎

Lines changed: 89 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -22,13 +22,58 @@ Using the configuration schema also allows us to validate the user input on fron
2222

2323
JSON schemas are well documented on the [json-schema.org](https://json-schema.org/) website.
2424

25-
We use [JSON Editor](https://github.com/json-editor/json-editor) for displaying a schema.
26-
The supported formatting options for
27-
the editor are available in the [official editor documentation](https://github.com/json-editor/json-editor#format).
28-
29-
For developing and testing,
30-
use, for example, JSON Editor available [on-line](http://jeremydorn.com/json-editor/), or the
31-
[JSON-Editor Interactive Playground](https://pmk65.github.io/jedemov2/dist/demo.html).
25+
We use [RJSF (React JSON Schema Form)](https://rjsf-team.github.io/react-jsonschema-form/) for rendering schemas
26+
into forms. The schema supports standard JSON Schema properties as well as custom extensions documented
27+
in [UI Element Examples](/extend/component/ui-options/configuration-schema/examples/) and
28+
[Sync Action Examples](/extend/component/ui-options/configuration-schema/sync-action-examples/).
29+
30+
### Supported Formats
31+
32+
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.
33+
34+
| Format | Type | Description |
35+
|---|---|---|
36+
| `password` | string | Masked password input with show/hide toggle |
37+
| `textarea` | string | Multi-line text area |
38+
| `editor` | string/object | CodeMirror code editor (JSON, SQL, Python, etc.) |
39+
| `date` | string | Date picker input |
40+
| `checkbox` | boolean | Checkbox toggle |
41+
| `radio` | string | Radio button group (requires `enum`) |
42+
| `trim` | string | Standard text input with automatic whitespace trimming |
43+
| `grid` / `grid-strict` | object | Responsive grid layout for grouped fields |
44+
| `tabs` / `tabs-top` / `categories` | object | Tabbed layout for grouped fields |
45+
| `table` | array | Editable table for arrays of objects |
46+
| `info` | *any JSON Schema type* | Static informational alert (uses `title` as message; Keboola UI extension) |
47+
| `ssh-editor` | object | SSH key/form editor |
48+
| `sync-action` | *Keboola UI button widget* | Action button triggering a sync action (not a JSON Schema `type`) |
49+
| `test-connection` | *Keboola UI button widget* | Connection test button (not a JSON Schema `type`) |
50+
51+
### Supported Options
52+
53+
The following `options` keys can be used in property definitions:
54+
55+
| Option | Description |
56+
|---|---|
57+
| `options.async` | Dynamic option loading via sync actions. See [Sync Action Examples](/extend/component/ui-options/configuration-schema/sync-action-examples/). |
58+
| `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). |
59+
| `options.tags` | Enable tag-style input for multi-select arrays |
60+
| `options.creatable` | Allow user-created values in select dropdowns |
61+
| `options.tooltip` | Help text displayed as a tooltip icon next to the field label. Supports Markdown syntax. |
62+
| `options.documentation` | Documentation link rendered as a book icon next to the field label. Value: `{ "link": "https://...", "tooltip": "optional hover text" }` |
63+
| `options.enum_titles` | Display labels for `enum` values |
64+
| `options.hidden` | Hide the field from the UI |
65+
| `options.collapsed` | Start object sections in collapsed state |
66+
| `options.disable_collapse` | Prevent collapsing of object sections |
67+
| `options.enabled` | Set to `false` to disable a field |
68+
| `options.grid_columns` | Number of grid columns (1–12) in `grid`/`grid-strict` layouts |
69+
| `options.grid_break` | Force a new row in grid layouts |
70+
| `options.editor` | CodeMirror editor options: `mode`, `lineNumbers`, `lint`, `input_height` |
71+
| `options.input_height` | Height for textarea fields (e.g., `"100px"`) |
72+
| `options.inputAttributes` | HTML input attributes (e.g., `placeholder`) |
73+
| `options.only_keys` | SSH editor variant showing only key fields |
74+
| `options.disable_array_add` | Disable adding items to arrays |
75+
| `options.disable_array_delete` | Disable removing items from arrays |
76+
| `options.disable_array_reorder` | Disable reordering items in arrays |
3277

3378
### Example
3479
Let's assume your component accepts the following configuration:
@@ -98,8 +143,30 @@ The form above can be created using this JSON Schema:
98143
{% endhighlight %}
99144

100145
### Links Example
101-
If you want to provide links to external resources, keep in mind that the configuration schema does not support markdown,
102-
but it has a `links` feature. The above example can be modified so that the links are clickable:
146+
147+
***Note:** The `links` feature is deprecated. Use `options.documentation` instead (see [Supported Options](#supported-options)).*
148+
149+
If you want to provide links to external resources, use `options.documentation` to add a clickable documentation icon next to the field label:
150+
151+
{% highlight json %}
152+
{
153+
"dateFrom": {
154+
"title": "Date from",
155+
"type": "string",
156+
"description": "Any date accepted by the strtotime function",
157+
"options": {
158+
"documentation": {
159+
"link": "https://www.php.net/manual/en/function.strtotime.php",
160+
"tooltip": "strtotime Documentation"
161+
}
162+
}
163+
}
164+
}
165+
{% endhighlight %}
166+
167+
#### Legacy links feature (deprecated)
168+
169+
The old `links` property is **no longer supported**. If you have existing schemas using it, migrate to `options.documentation`:
103170

104171
{% highlight json %}
105172
{
@@ -130,7 +197,7 @@ but it has a `links` feature. The above example can be modified so that the link
130197
"dateFrom": {
131198
"title": "Date from",
132199
"type": "string",
133-
"description": "Any date accepted by the strtotime function",
200+
"description": "Any date accepted by the strtotime function",
134201
"minLength": 1,
135202
"default": "",
136203
"propertyOrder": 3,
@@ -163,3 +230,15 @@ Which renders like this:
163230

164231
{: .image-popup}
165232
![Configuration Schema with links](/extend/component/ui-options/configuration-schema-2.png)
233+
234+
### Legacy Features
235+
236+
The following features are still supported for backwards compatibility but have preferred alternatives:
237+
238+
- **`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).
239+
240+
### Deprecated Features
241+
242+
The following features from the legacy JSON Editor library are **no longer supported**:
243+
244+
- **`links`** — Clickable links on field descriptions. Use `options.documentation` with `link` and optional `tooltip` instead.

‎extend/component/ui-options/ui-examples/configuration-schema-examples.md‎

Lines changed: 219 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -404,13 +404,13 @@ The above code will create the following user interface:
404404
![optional block](/extend/component/ui-options/ui-examples/optional_block_array.gif)
405405

406406

407-
### Changing Set of Options Dynamically Based on Selection
407+
### Conditionally Showing Fields Based on Selection
408408

409-
In some cases, a different set of options is available for different types of the same object, e.g., Report type.
410-
JSON Schema allows to define different schemas based on selection.
411-
This may be useful in the configuration rows scenario, where each row could represent a different type of Report, Endpoint, etc.
409+
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.
410+
JSON Schema UI options allow you to control field visibility based on the values of other fields.
411+
This may be useful in configuration rows, where each row can expose extra options depending on how a user configures it.
412412

413-
This can be achieved via [dependencies](https://github.com/json-editor/json-editor#dependencies).*
413+
This can be achieved via `options.dependencies`. When the dependency conditions are met, the field is shown; otherwise it is hidden.
414414

415415

416416
```json
@@ -463,3 +463,217 @@ You can also react on multiple array values or on multiple elements at the same
463463
}
464464
}
465465
```
466+
467+
You can also reference nested fields using dot notation with a `root.` prefix:
468+
469+
```json
470+
"options": {
471+
"dependencies": {
472+
"root.credentials.#api_token": ""
473+
}
474+
}
475+
```
476+
477+
This shows the field only when the `#api_token` field inside the `credentials` object is empty.
478+
479+
480+
### Tooltips and Documentation Links
481+
482+
Use `options.tooltip` to add a help icon next to the field label. The tooltip content supports **Markdown** syntax:
483+
484+
```json
485+
{
486+
"api_key": {
487+
"type": "string",
488+
"title": "API Key",
489+
"options": {
490+
"tooltip": "Your API key from the [dashboard](https://example.com/dashboard).\n\n**Note:** Keep this value secret."
491+
}
492+
}
493+
}
494+
```
495+
496+
Use `options.documentation` to add a clickable documentation link icon:
497+
498+
```json
499+
{
500+
"query": {
501+
"type": "string",
502+
"title": "SQL Query",
503+
"options": {
504+
"documentation": {
505+
"link": "https://docs.example.com/sql-reference",
506+
"tooltip": "Open SQL reference"
507+
}
508+
}
509+
}
510+
}
511+
```
512+
513+
### Radio Buttons
514+
515+
Use `format: "radio"` with an `enum` to render radio buttons instead of a dropdown:
516+
517+
```json
518+
{
519+
"output_format": {
520+
"type": "string",
521+
"title": "Output Format",
522+
"enum": ["csv", "json", "parquet"],
523+
"format": "radio",
524+
"default": "csv",
525+
"propertyOrder": 1
526+
}
527+
}
528+
```
529+
530+
531+
### Date Picker
532+
533+
Use `format: "date"` for a date input with a calendar picker. Values are stored as `YYYY-MM-DD` strings:
534+
535+
```json
536+
{
537+
"start_date": {
538+
"type": "string",
539+
"title": "Start Date",
540+
"format": "date",
541+
"propertyOrder": 1
542+
}
543+
}
544+
```
545+
546+
547+
### Grid Layout
548+
549+
Use `format: "grid"` or `format: "grid-strict"` on an object to arrange its properties in a responsive 12-column grid.
550+
Each property can specify `options.grid_columns` (1–12) to control its width. Use `options.grid_break` to force a new row:
551+
552+
```json
553+
{
554+
"connection": {
555+
"type": "object",
556+
"title": "Connection",
557+
"format": "grid-strict",
558+
"properties": {
559+
"host": {
560+
"type": "string",
561+
"title": "Hostname",
562+
"propertyOrder": 1,
563+
"options": { "grid_columns": 8 }
564+
},
565+
"port": {
566+
"type": "integer",
567+
"title": "Port",
568+
"propertyOrder": 2,
569+
"options": { "grid_columns": 4 }
570+
},
571+
"database": {
572+
"type": "string",
573+
"title": "Database",
574+
"propertyOrder": 3,
575+
"options": { "grid_break": true }
576+
}
577+
}
578+
}
579+
}
580+
```
581+
582+
583+
### Collapsible Sections
584+
585+
Use `options.collapsed` on an object to make it collapsible. Set `options.disable_collapse` to prevent the user from collapsing it:
586+
587+
```json
588+
{
589+
"advanced": {
590+
"type": "object",
591+
"title": "Advanced Settings",
592+
"options": {
593+
"collapsed": true
594+
},
595+
"properties": {
596+
"timeout": { "type": "integer", "title": "Timeout" }
597+
}
598+
}
599+
}
600+
```
601+
602+
603+
### Disabled Fields
604+
605+
Use `options.enabled: false` to render a field as read-only:
606+
607+
```json
608+
{
609+
"locked_field": {
610+
"type": "string",
611+
"title": "Locked Value",
612+
"default": "Cannot be changed",
613+
"options": {
614+
"enabled": false
615+
}
616+
}
617+
}
618+
```
619+
620+
621+
### Info Blocks
622+
623+
Use `format: "info"` to display a static informational message. The `title` property is used as the message text:
624+
625+
```json
626+
{
627+
"notice": {
628+
"title": "This component requires an API token to function.",
629+
"format": "info",
630+
"propertyOrder": 1
631+
}
632+
}
633+
```
634+
635+
#### Alert Type
636+
637+
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"`.
638+
639+
```json
640+
{
641+
"missing_token_warning": {
642+
"title": "WARNING: API token is required!",
643+
"format": "info",
644+
"options": {
645+
"alert_type": "warning"
646+
}
647+
}
648+
}
649+
```
650+
651+
```json
652+
{
653+
"config_error": {
654+
"title": "Configuration is invalid.",
655+
"description": "Please check the required fields below.",
656+
"format": "info",
657+
"options": {
658+
"alert_type": "error"
659+
}
660+
}
661+
}
662+
```
663+
664+
Info blocks can be combined with `options.dependencies` to show warnings conditionally:
665+
666+
```json
667+
{
668+
"missing_token_warning": {
669+
"title": "WARNING: API token is required!",
670+
"format": "info",
671+
"options": {
672+
"alert_type": "warning",
673+
"dependencies": {
674+
"root.credentials.#api_token": ""
675+
}
676+
}
677+
}
678+
}
679+
```

0 commit comments

Comments
 (0)