Skip to content

Commit 8a68b25

Browse files
author
Marko Petzold
committed
docs: improve definition-schema.json for AI agent readability
1 parent b80424e commit 8a68b25

1 file changed

Lines changed: 68 additions & 39 deletions

File tree

‎src/definition-schema.json‎

Lines changed: 68 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -1,62 +1,82 @@
11
{
22
"title": "inputData",
3+
"description": "A versatile chart widget for visualizing data as line charts, bar charts, or scatter plots. Use this widget for time-series data, trend analysis, comparisons, and general data visualization. Supports multiple data series with different chart types in the same view, automatic pivot-based series generation, zoom controls, and flexible styling options. The ECharts-based rendering provides smooth animations and interactive tooltips. Ideal for monitoring dashboards, historical data analysis, and any scenario requiring visual data representation over continuous or categorical dimensions.",
34
"type": "object",
45
"properties": {
5-
"title": { "title": "Title", "type": "string", "order": 1 },
6-
"subTitle": { "title": "Subtitle", "type": "string", "order": 2 },
6+
"title": {
7+
"title": "Title",
8+
"description": "The main heading displayed above the chart. Use to describe what data is being visualized (e.g., 'Temperature Over Time', 'Sales by Region').",
9+
"type": "string",
10+
"order": 1
11+
},
12+
"subTitle": {
13+
"title": "Subtitle",
14+
"description": "Secondary text displayed below the title. Use for additional context like data source, time period, or measurement units.",
15+
"type": "string",
16+
"order": 2
17+
},
718
"axis": {
819
"title": "Configuration",
20+
"description": "Chart display settings including axes, legend, and layout options.",
921
"type": "object",
1022
"order": 3,
1123
"properties": {
24+
"xAxisLabel": {
25+
"title": "X-Axis Label",
26+
"description": "Label text displayed below the horizontal axis. Describes the x-dimension (e.g., 'Time', 'Date', 'Category').",
27+
"type": "string",
28+
"dataDrivenDisabled": false,
29+
"order": 0
30+
},
31+
"yAxisLabel": {
32+
"title": "Y-Axis Label",
33+
"description": "Label text displayed beside the vertical axis. Describes the measured values (e.g., 'Temperature (°C)', 'Count', 'Revenue ($)').",
34+
"type": "string",
35+
"dataDrivenDisabled": false,
36+
"order": 1
37+
},
1238
"showLegend": {
1339
"title": "Show Legend",
14-
"description": "Display the chart legend.",
40+
"description": "When enabled, displays a legend identifying each data series by color and label. Essential for multi-series charts.",
1541
"type": "boolean",
1642
"default": true,
1743
"dataDrivenDisabled": true,
18-
"order": 1
44+
"order": 1.1
1945
},
2046
"showTitle": {
2147
"title": "Show Title",
22-
"description": "Display the chart title.",
48+
"description": "When enabled, displays the chart title and subtitle. Disable for compact layouts or when the widget container provides its own title.",
2349
"type": "boolean",
2450
"default": true,
2551
"dataDrivenDisabled": true,
2652
"order": 2
2753
},
2854
"showBox": {
2955
"title": "Show Box Frame",
30-
"description": "Display a border frame around the chart area.",
56+
"description": "When enabled, draws a border frame around the chart plotting area. Useful for visual separation in dense dashboards.",
3157
"type": "boolean",
3258
"default": false,
3359
"dataDrivenDisabled": true,
3460
"order": 3
3561
},
3662
"timeseries": {
3763
"title": "Timeseries Chart",
38-
"description": "This will apply a proper time series x-Axis. Check if your x-values are timestamps.",
64+
"description": "When enabled, treats x-axis values as timestamps and applies proper time-based scaling and formatting. Enable when your x-values are dates/times (ISO strings or timestamps). Disable for categorical x-axes.",
3965
"type": "boolean",
4066
"dataDrivenDisabled": true,
4167
"order": 4
4268
},
4369
"columnLayout": {
4470
"title": "Vertical Layout",
45-
"description": "When multiple charts are drawn, then they will be layed out horizontically or vertically.",
71+
"description": "When multiple charts are drawn (via chartName grouping), this controls their arrangement. Enabled = stacked vertically, Disabled = arranged horizontally side by side.",
4672
"type": "boolean",
4773
"dataDrivenDisabled": true,
4874
"order": 5
4975
},
5076

51-
"xAxisLabel": {
52-
"title": "X-Axis Label",
53-
"type": "string",
54-
"dataDrivenDisabled": false,
55-
"order": 6
56-
},
5777
"showXAxis": {
5878
"title": "Show X-Axis",
59-
"description": "Display the x-axis with labels. When hidden, bottom padding is removed.",
79+
"description": "When enabled, displays the x-axis line, ticks, and labels. Disable to remove bottom axis and its padding for minimal designs.",
6080
"type": "boolean",
6181
"default": true,
6282
"dataDrivenDisabled": true,
@@ -65,28 +85,22 @@
6585
"xAxisZoom": {
6686
"title": "X-Axis Zoom Tool",
6787
"type": "boolean",
68-
"description": "If checked, a zoom tool will be shown on the x-axis to zoom into the chart.",
88+
"description": "When enabled, shows a slider control below the chart for zooming into specific x-axis ranges. Useful for long time series where users need to focus on specific periods.",
6989
"dataDrivenDisabled": true,
7090
"order": 8
7191
},
7292

73-
"yAxisLabel": {
74-
"title": "Y-Axis Label",
75-
"type": "string",
76-
"dataDrivenDisabled": false,
77-
"order": 9
78-
},
7993
"showYAxis": {
8094
"title": "Show Y-Axis",
81-
"description": "Display the y-axis with labels. When hidden, left padding is removed.",
95+
"description": "When enabled, displays the y-axis line, ticks, and labels. Disable to remove left axis and its padding for minimal designs.",
8296
"type": "boolean",
8397
"default": true,
8498
"dataDrivenDisabled": true,
8599
"order": 10
86100
},
87101
"yAxisScaling": {
88102
"title": "Y-Axis Scaling",
89-
"description": "If checked, the Y-Axis will be scaled to the data range. If not checked, the Y-Axis will always start at 0.",
103+
"description": "When enabled, the y-axis range automatically adjusts to fit the data (min to max). When disabled, the y-axis always starts at 0, which is better for comparing absolute values.",
90104
"type": "boolean",
91105
"dataDrivenDisabled": true,
92106
"order": 11
@@ -95,6 +109,7 @@
95109
},
96110
"dataseries": {
97111
"title": "Dataseries",
112+
"description": "Array of data series to plot. Each series can have its own chart type (line/bar/scatter), colors, and styling. Multiple series can share an axis or be grouped into separate charts.",
98113
"type": "array",
99114
"dataDrivenDisabled": true,
100115
"order": 4,
@@ -103,13 +118,14 @@
103118
"properties": {
104119
"label": {
105120
"title": "Label",
106-
"description": "The name for this data series",
121+
"description": "Display name for this data series shown in legends and tooltips. Should clearly identify what data this series represents.",
107122
"type": "string",
108123
"required": true,
109124
"order": 1
110125
},
111126
"type": {
112127
"title": "Drawing Style",
128+
"description": "The visual representation type: 'line' for continuous line charts (best for trends), 'bar' for vertical bar charts (best for comparisons), 'scatter' for individual data points (best for correlation analysis).",
113129
"type": "string",
114130
"enum": ["bar", "line", "scatter"],
115131
"required": true,
@@ -118,36 +134,42 @@
118134
},
119135
"backgroundColor": {
120136
"title": "Fill Color",
121-
"description": "The inner color of the bars if you chose Drawing Type 'bar' or the inner colors of the points if you chose Drawing Type 'line'.",
137+
"description": "For bar charts: the bar fill color. For line charts: the data point marker fill color. For scatter: the point fill color. Leave empty to use theme default.",
122138
"type": "color",
123139
"color": true,
124140
"order": 3
125141
},
126-
"borderColor": { "title": "Line Color", "type": "color", "color": true, "order": 4 },
142+
"borderColor": {
143+
"title": "Line Color",
144+
"description": "For line charts: the line stroke color. For bar charts: the bar border color. This is the primary color identifying the series.",
145+
"type": "color",
146+
"color": true,
147+
"order": 4
148+
},
127149
"styling": {
128150
"title": "Styling",
129-
"description": "",
151+
"description": "Additional visual styling options for the series.",
130152
"type": "object",
131153
"order": 6,
132154
"properties": {
133155
"fill": {
134156
"title": "Line Area Fill",
135-
"description": "Check this box to turn a line chart into an area chart.",
157+
"description": "When enabled for line charts, fills the area between the line and the x-axis, creating an area chart. Useful for visualizing volume or cumulative values.",
136158
"type": "boolean",
137159
"condition": { "relativePath": "../../type", "showIfValueIn": ["line"] },
138160
"dataDrivenDisabled": true,
139161
"order": 1
140162
},
141163
"borderWidth": {
142164
"title": "Line Width",
143-
"description": "Width of the lines in the chart.",
165+
"description": "Thickness of lines in pixels. Larger values make lines more prominent. Typical values: 1-2 for dense charts, 2-4 for emphasis.",
144166
"type": "number",
145167
"dataDrivenDisabled": true,
146168
"order": 2
147169
},
148170
"borderDash": {
149171
"title": "Line Dash Style",
150-
"description": "",
172+
"description": "Line pattern for line charts: 'solid' for continuous lines, 'dashed' for long dashes, 'dotted' for dots. Use different patterns to distinguish overlapping series.",
151173
"type": "string",
152174
"condition": { "relativePath": "../../type", "showIfValueIn": ["line"] },
153175
"enum": ["solid", "dashed", "dotted"],
@@ -156,6 +178,7 @@
156178
},
157179
"pointStyle": {
158180
"title": "Symbol Style",
181+
"description": "Shape of data point markers: 'circle', 'rect' (square), 'roundRect', 'triangle', 'diamond', 'pin', 'arrow', or 'none' to hide markers. Different shapes help distinguish series.",
159182
"condition": {
160183
"relativePath": "../../type",
161184
"showIfValueIn": ["line", "scatter"]
@@ -177,20 +200,20 @@
177200
},
178201
"advanced": {
179202
"title": "Advanced Settings",
180-
"description": "",
203+
"description": "Advanced configuration for multi-chart layouts and draw ordering.",
181204
"type": "object",
182205
"order": 7,
183206
"properties": {
184207
"drawOrder": {
185208
"title": "Draw Order",
186-
"description": "Determines the draw order of the series. Dataseries with lower numbers are drawn on top of ones with higher numbers within one chart.",
209+
"description": "Z-index controlling which series appears on top when overlapping. Lower numbers are drawn on top. Use to ensure important series aren't hidden behind others.",
187210
"type": "number",
188211
"dataDrivenDisabled": true,
189212
"order": 2
190213
},
191214
"chartName": {
192215
"title": "Chart Name",
193-
"description": "If two dataseries have the same 'Chart Name', they will be drawn in the same chart. Otherwise they will get their own chart. If the name contains #split# as substring then a separat chart will be drawn for each split dataseries.",
216+
"description": "Groups series into separate charts. Series with the same chartName share one chart; different names create separate charts. Use '#split#' in the name to auto-create one chart per pivot value.",
194217
"type": "string",
195218
"dataDrivenDisabled": true,
196219
"order": 3
@@ -199,23 +222,29 @@
199222
},
200223
"data": {
201224
"title": "Data",
202-
"description": "The data used to draw this data series.",
225+
"description": "Array of data points to plot. Each point has x (position on horizontal axis), y (value), and optionally r (point size) and pivot (for auto-generating series).",
203226
"type": "array",
204227
"order": 5,
205228
"items": {
206229
"type": "object",
207230
"properties": {
208231
"x": {
209232
"title": "X-Value",
210-
"description": "If timeseries is checked in the settings, then this should be an ISO String date like 2023-11-04T22:47:52.351152+00:00. But this works with many other formats as well.",
233+
"description": "The horizontal axis value. For timeseries charts, use ISO 8601 timestamp strings (e.g., '2023-11-04T22:47:52.351152+00:00') or Unix timestamps. For categorical charts, use category labels.",
211234
"type": "string",
212235
"order": 1,
213236
"required": true
214237
},
215-
"y": { "title": "Y-Value", "type": "string", "order": 2, "required": true },
238+
"y": {
239+
"title": "Y-Value",
240+
"description": "The vertical axis value representing the measurement or count at this x position.",
241+
"type": "string",
242+
"order": 2,
243+
"required": true
244+
},
216245
"r": {
217246
"title": "Point Size",
218-
"description": "Controls the symbol size for line and scatter charts.",
247+
"description": "Radius/size of the data point marker for line and scatter charts. Use varying sizes to encode a third data dimension (bubble chart effect).",
219248
"condition": {
220249
"relativePath": "../../../type",
221250
"showIfValueIn": ["line", "scatter"]
@@ -225,7 +254,7 @@
225254
},
226255
"pivot": {
227256
"title": "Split Data by",
228-
"description": "You can specify a column in the input data to autogenerate dataseries for each distinct entry in this column. E.g. if you have a table with columns [city, timestamp, temperature] and specify 'city' as split column, then you will get a line for each city.",
257+
"description": "Column value used to split this data into multiple series automatically. Each unique pivot value creates a separate line/bar series (e.g., pivot by 'city' to get one line per city).",
229258
"order": 4,
230259
"type": "string"
231260
}

0 commit comments

Comments
 (0)