@astrato-io/visualizations 0.0.0-stage → 0.6.4

package/VISUALIZATION_DEFINITIONS.md

@@ -0,0 +1,2378 @@
+# Visualization Definition Reference
+
+This reference documents version 1 of the public `VisualizationDefinition` creation contract exposed from `@astrato-io/visualizations/definitions`.
+
+The reference and the public per-type descriptors share the same metadata catalog.
+
+## How To Use This Reference
+
+- Use a definition only to create a visualization from a fresh default or preset vSpec.
+- Use exact, opaque engine `fieldKey` values. Never parse, reconstruct, or replace them with view/name pairs.
+- Definition-local `ref` values let sorting, Top N, and similar settings refer to data items before internal identities exist.
+- Raw fields used as measures require `aggregation`. Semantic dimensions, predefined measures, and calculations retain their engine semantics.
+- Unsupported sections and properties are rejected instead of ignored.
+- The compiler returns one complete vSpec or structured issues; it never returns partial state.
+- Settings a definition cannot express are applied with `applyOperations` on the compiled vSpec before mounting. See "Finishing A Chart Before Mounting".
+
+## Integrating With AI
+
+When building an AI integration, first choose the visualization type, such as `bar` or `table`. The compact `supportedFeatures` list can help with this discovery step without loading every full schema.
+
+After selecting the type, give the model only:
+
+1. `descriptor.jsonSchema`, which defines the allowed JSON structure.
+2. `descriptor.documentation`, which explains what the properties mean and lists chart-specific rules.
+3. `descriptor.examples`, which shows valid definitions.
+4. The compatible available fields, including their exact engine keys.
+
+Do not send schemas for every visualization or ask the model to generate a raw vSpec. That would give the model unrelated information and require it to understand internal vSpec properties and generated data-item IDs.
+
+After the model returns a definition, pass it to `compileVisualizationDefinition()`. On success, use the returned vSpec. On failure, give the structured issues back to the model so it can correct the definition and try again.
+
+Use `getVisualizationDefinitionDescriptor(type, 1)` to get the descriptor for one selected type. Use `listVisualizationDefinitionDescriptors()` to discover the available visualization types and compare their `supportedFeatures`.
+
+A definition does not cover every setting yet. If the chart needs a setting the definition cannot express, finish it with operations before mounting, as described in the next section.
+
+## Finishing A Chart Before Mounting
+
+A definition covers a subset of the operation catalogue. For settings outside it, apply operations to the compiled vSpec with `applyOperations` from `@astrato-io/visualizations/operations`, in one batch and before creating the instance. This runs in memory: it needs no runtime and makes no engine requests.
+
+Use `compilation.resolvedRefs` to get the data-item identity that operation payloads expect for a definition `ref`:
+
+```ts
+import { applyOperations } from '@astrato-io/visualizations/operations';
+
+const compilation = await compileVisualizationDefinition({ definition, availableFields, baseVSpec });
+if (!compilation.success) throw new Error(JSON.stringify(compilation.issues));
+
+const { dataItemInternalKey, dataItemUniqueSignature } = compilation.resolvedRefs.sales;
+const finished = await applyOperations({
+  instance: { id: 'sales-by-manufacturer', type: 'bar', vSpec: compilation.vSpec },
+  operationRequests: [
+    { id: 'radius', name: 'setBarChartBarRadius', payload: 4 },
+    {
+      id: 'color',
+      name: 'setMeasureGraphColor',
+      payload: { dataItemInternalKey, dataItemUniqueSignature, graphColor: '#0f766e' },
+    },
+  ],
+});
+
+// a batch is not transactional: a request that fails while running is reported here;
+// an unsupported operation name or a missing vSpec throws before any result is returned
+const failures = Object.values(finished.results as Record<string, { success: boolean }>).filter(
+  (result) => !result.success,
+);
+if (failures.length) throw new Error(JSON.stringify(failures));
+
+runtime.createInstance({ id: 'sales-by-manufacturer', type: 'bar', vSpec: finished.vSpec, dataBinding });
+```
+
+Get operation names and payload schemas from `getVisualizationMetadata(type).operations`.
+
+Avoid finishing a chart by applying operations one at a time after it is mounted. Each change to a mounted instance's vSpec can trigger a new data request, so a dashboard built that way makes one engine request per operation per chart.
+
+## Common Feature Names
+
+| Feature              | Meaning                                                                        |
+| -------------------- | ------------------------------------------------------------------------------ |
+| `axes`               | Semantic dimension/primary-measure/secondary-measure axis presentation.        |
+| `axis-bands`         | Shaded ranges between two primary measure axis values.                         |
+| `axis-range`         | Measure-axis range (min, max, starts at zero) and inversion.                   |
+| `axis-scale`         | Linear or logarithmic measure axis.                                            |
+| `content`            | User-visible content such as text, image, or URL.                              |
+| `data-labels`        | Chart or measure label visibility and supported label settings.                |
+| `dimensions`         | Dimension or field-backed data items.                                          |
+| `filter-settings`    | Settings of an interactive filter-like object.                                 |
+| `filters`            | Static visualization filters applied at creation.                              |
+| `input-settings`     | Variable-backed input behavior and presentation.                               |
+| `legend`             | Legend visibility, position, and title.                                        |
+| `measures`           | Aggregated raw fields, predefined measures, or calculations.                   |
+| `object-settings`    | Object-specific non-data presentation settings.                                |
+| `orientation`        | Horizontal or vertical chart orientation.                                      |
+| `query-limit`        | Maximum number of rows requested by the visualization.                         |
+| `selection-settings` | Selection behavior and available filter controls for a shared selection group. |
+| `sorting`            | Ordered sorting rules referencing definition-local refs.                       |
+| `table-structure`    | Normal, expandable, or pivot table data arrangement.                           |
+| `top-n`              | Top N limiting referencing a definition-local measure ref.                     |
+| `totals`             | Table totals behavior and presentation.                                        |
+| `value-formatting`   | Dimension, measure, or table-column value formatting.                          |
+
+## Capability Index
+
+| Type                     | Name                   | Data requirements                                                                                                                                                                                                                 | Supported features                                                                                                                                                                                                                 |
+| ------------------------ | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `bar`                    | Bar chart              | At least one dimension. At least one measure.                                                                                                                                                                                     | `axes`, `axis-bands`, `axis-range`, `axis-scale`, `conditional-coloring`, `data-labels`, `dimensions`, `filters`, `legend`, `measure-axis`, `measures`, `orientation`, `query-limit`, `sorting`, `top-n`, `value-formatting`       |
+| `combo`                  | Combo chart            | Exactly one dimension. Between one and ten measures.                                                                                                                                                                              | `dimensions`, `filters`, `measures`, `value-formatting`, `axes`, `axis-bands`, `axis-range`, `axis-scale`, `data-labels`, `legend`, `measure-axis`, `orientation`, `query-limit`, `series-type`, `sorting`                         |
+| `distribution-gauge`     | Distribution gauge     | Zero or one dimension. Between one and twenty measures.                                                                                                                                                                           | `dimensions`, `filters`, `measures`, `value-formatting`, `conditional-coloring`, `display-mode`, `legend`                                                                                                                          |
+| `dot`                    | Dot chart              | Exactly two dimensions. Exactly one measure.                                                                                                                                                                                      | `dimensions`, `filters`, `measures`, `value-formatting`, `conditional-coloring`, `axes`, `axis-range`, `legend`, `orientation`                                                                                                     |
+| `gauge`                  | Gauge chart            | Zero or one dimension. Between one and twenty measures; with one dimension, at most two measures.                                                                                                                                 | `dimensions`, `filters`, `measures`, `value-formatting`, `conditional-coloring`, `display-mode`, `legend`                                                                                                                          |
+| `heatMap`                | Heat map               | Exactly two dimensions. One or two measures.                                                                                                                                                                                      | `dimensions`, `filters`, `measures`, `value-formatting`, `conditional-coloring`, `axes`, `legend`, `query-limit`, `sorting`                                                                                                        |
+| `histogram`              | Histogram              | Exactly one numeric dimension. No caller-supplied measures.                                                                                                                                                                       | `axes`, `axis-bands`, `axis-range`, `dimensions`, `filters`, `legend`, `orientation`, `value-formatting`                                                                                                                           |
+| `line`                   | Line chart             | At least one dimension. At least one measure.                                                                                                                                                                                     | `axes`, `axis-bands`, `axis-range`, `axis-scale`, `conditional-coloring`, `data-labels`, `data-points`, `dimensions`, `filters`, `legend`, `measure-axis`, `measures`, `orientation`, `query-limit`, `sorting`, `value-formatting` |
+| `radar`                  | Radar chart            | Zero to two dimensions. Two to five measures without dimensions, or one with dimensions.                                                                                                                                          | `dimensions`, `filters`, `measures`, `value-formatting`, `conditional-coloring`, `legend`                                                                                                                                          |
+| `pie`                    | Pie chart              | Exactly one dimension. One or two measures.                                                                                                                                                                                       | `dimensions`, `filters`, `measures`, `value-formatting`, `conditional-coloring`, `legend`, `query-limit`, `sorting`                                                                                                                |
+| `tree`                   | Tree chart             | Zero to ten dimensions. Zero to one hundred measures, or at most one with dimensions.                                                                                                                                             | `dimensions`, `filters`, `measures`, `value-formatting`, `layout`, `query-limit`, `sorting`                                                                                                                                        |
+| `treemap`                | Treemap                | Between one and ten dimensions. Exactly one measure.                                                                                                                                                                              | `dimensions`, `filters`, `measures`, `value-formatting`, `conditional-coloring`, `legend`                                                                                                                                          |
+| `sankey`                 | Sankey chart           | Between two and fifteen dimensions. Exactly one measure.                                                                                                                                                                          | `dimensions`, `filters`, `measures`, `value-formatting`, `conditional-coloring`                                                                                                                                                    |
+| `scatter`                | Scatter chart          | One or two dimensions. Two or three measures.                                                                                                                                                                                     | `dimensions`, `filters`, `measures`, `value-formatting`, `conditional-coloring`, `axes`, `axis-range`, `legend`, `query-limit`, `sorting`                                                                                          |
+| `table`                  | Table                  | Normal tables require at least one ordered dimension or measure column. Expandable tables require at least one dimension and one measure. Pivot tables require at least one row dimension, one column dimension, and one measure. | `dimensions`, `filters`, `layout`, `measures`, `query-limit`, `sorting`, `table-structure`, `totals`, `value-formatting`                                                                                                           |
+| `waterfall`              | Waterfall chart        | Between one and one hundred measures.                                                                                                                                                                                             | `axes`, `axis-bands`, `axis-range`, `data-labels`, `filters`, `measures`, `orientation`, `value-formatting`                                                                                                                        |
+| `word-cloud`             | Word cloud             | Exactly one dimension. Exactly one measure.                                                                                                                                                                                       | `dimensions`, `filters`, `measures`, `value-formatting`, `conditional-coloring`                                                                                                                                                    |
+| `date-picker`            | Date picker            | Exactly one field.                                                                                                                                                                                                                | `dimensions`, `filter-settings`                                                                                                                                                                                                    |
+| `filter`                 | Filter                 | Exactly one field.                                                                                                                                                                                                                | `dimensions`, `filter-settings`                                                                                                                                                                                                    |
+| `iframe`                 | Iframe                 | No query data.                                                                                                                                                                                                                    | `content`                                                                                                                                                                                                                          |
+| `image`                  | Image                  | No query data.                                                                                                                                                                                                                    | `content`, `object-settings`                                                                                                                                                                                                       |
+| `number`                 | Number                 | Exactly one measure.                                                                                                                                                                                                              | `filters`, `measures`, `value-formatting`                                                                                                                                                                                          |
+| `shape`                  | Shape                  | No query data.                                                                                                                                                                                                                    | `object-settings`                                                                                                                                                                                                                  |
+| `simpleTextObject`       | Text object            | No query data.                                                                                                                                                                                                                    | `content`, `object-settings`                                                                                                                                                                                                       |
+| `atomic-input`           | Atomic input           | No query data; variable-backed input.                                                                                                                                                                                             | `input-settings`                                                                                                                                                                                                                   |
+| `astrato-app-filter-bar` | Astrato App Filter Bar | No query data; uses field metadata and selections supplied by the host.                                                                                                                                                           | `selection-settings`                                                                                                                                                                                                               |
+| `slider`                 | Slider                 | Exactly one field.                                                                                                                                                                                                                | `dimensions`, `filter-settings`                                                                                                                                                                                                    |
+
+## `bar`: Bar chart
+
+Categorical comparison chart with sorting, limiting, per-measure axes, labels, and orientation controls.
+
+**Data requirements**
+
+- At least one dimension.
+- At least one measure.
+
+**Supported features**
+
+`axes`, `axis-bands`, `axis-range`, `axis-scale`, `conditional-coloring`, `data-labels`, `dimensions`, `filters`, `legend`, `measure-axis`, `measures`, `orientation`, `query-limit`, `sorting`, `top-n`, `value-formatting`
+
+**Constraints and semantics**
+
+- Sorting and Top N refer to definition-local refs, not generated data-item IDs.
+- Every dimension and measure must resolve to an available field with a compatible role.
+- Set axis per measure to plot it against the primary or the secondary measure axis.
+- presentation.axes.primaryMeasure.bands shades the plot between two primary measure axis values; start and end are measure values, and the bands replace any on the base vSpec.
+- Set range on a measure axis to fix its min, max, or both, for example to give several charts one shared scale; leave both unset and set startsAtZero to keep an auto-fitted axis anchored at zero. Set inverted on a measure axis to reverse its values, for example to put rank 1 at the top.
+- Set scale to log on a measure axis to draw it logarithmically, with gridlines at powers of ten. Zero and negative values are drawn at the floor of a log axis.
+
+**Canonical example**
+
+```json
+{
+  "data": {
+    "dimensions": [
+      {
+        "fieldKey": "[Cars].[Manufacturer]",
+        "format": {
+          "formatType": "none"
+        },
+        "ref": "manufacturer",
+        "showNullValues": false
+      }
+    ],
+    "measures": [
+      {
+        "aggregation": "SUM",
+        "fieldKey": "[Cars].[Sales In Thousands]",
+        "format": {
+          "formatType": "number2Decimal",
+          "negativeType": "parenthesis"
+        },
+        "ref": "sales",
+        "dataLabels": {
+          "placements": ["outside", "inside"],
+          "visible": true
+        }
+      }
+    ]
+  },
+  "filterGroup": {
+    "filters": [
+      {
+        "fieldKey": "[Cars].[Manufacturer]",
+        "operator": "inList",
+        "values": ["Acura", "Audi", "BMW"]
+      }
+    ],
+    "operator": "and"
+  },
+  "limiting": {
+    "queryLimit": 100,
+    "topN": {
+      "by": "sales",
+      "count": 10,
+      "direction": "desc",
+      "showOthers": false
+    }
+  },
+  "presentation": {
+    "axes": {
+      "dimension": {
+        "labelsVisible": true,
+        "title": "Manufacturer",
+        "titleVisible": true
+      },
+      "primaryMeasure": {
+        "labelsVisible": true,
+        "title": "Sales",
+        "titleVisible": true,
+        "bands": [
+          {
+            "color": "#E6E6E6",
+            "end": 150000,
+            "label": "Target range",
+            "start": 100000
+          }
+        ]
+      },
+      "secondaryMeasure": {
+        "labelsVisible": true,
+        "title": "Horsepower",
+        "titleVisible": true
+      }
+    },
+    "legend": {
+      "position": "right",
+      "title": "Cars comparison",
+      "visible": true
+    },
+    "orientation": "vertical"
+  },
+  "sorting": [
+    {
+      "by": "sales",
+      "direction": "desc"
+    }
+  ],
+  "type": "bar",
+  "version": 1
+}
+```
+
+**Additional scenarios**
+
+### Colors bound to dimension values and a measure threshold
+
+```json
+{
+  "data": {
+    "dimensions": [
+      {
+        "fieldKey": "[Cars].[Manufacturer]",
+        "format": {
+          "formatType": "none"
+        },
+        "ref": "manufacturer"
+      }
+    ],
+    "measures": [
+      {
+        "aggregation": "SUM",
+        "fieldKey": "[Cars].[Sales In Thousands]",
+        "format": {
+          "formatType": "number2Decimal",
+          "negativeType": "parenthesis"
+        },
+        "ref": "sales"
+      }
+    ]
+  },
+  "presentation": {
+    "coloring": {
+      "overwrites": [
+        {
+          "color": "#0F766E",
+          "value": "Audi"
+        },
+        {
+          "color": "#D97706",
+          "operator": "inList",
+          "values": ["BMW", "Buick"]
+        }
+      ],
+      "rules": [
+        {
+          "color": "#DC2626",
+          "measure": "sales",
+          "operator": "less",
+          "value": 20
+        }
+      ]
+    }
+  },
+  "type": "bar",
+  "version": 1
+}
+```
+
+## `combo`: Combo chart
+
+Combined categorical chart supporting multiple measures, per-measure axes, sorting, limiting, labels, legend, and orientation.
+
+**Data requirements**
+
+- Exactly one dimension.
+- Between one and ten measures.
+
+**Supported features**
+
+`dimensions`, `filters`, `measures`, `value-formatting`, `axes`, `axis-bands`, `axis-range`, `axis-scale`, `data-labels`, `legend`, `measure-axis`, `orientation`, `query-limit`, `series-type`, `sorting`
+
+**Constraints and semantics**
+
+- The single dimension is assigned the combo category role.
+- Set seriesType per measure to create bar, line, or point series; omission keeps the existing line default.
+- Data labels apply only to bar series.
+- Sorting refers to definition-local refs, not generated data-item IDs.
+- Set axis per measure to plot it against the primary or the secondary measure axis. Bar series share one axis: state it on any bar measure, and every bar measure that states one must state the same axis.
+- presentation.axes.primaryMeasure.bands shades the plot between two primary measure axis values; start and end are measure values, and the bands replace any on the base vSpec.
+- Set range on a measure axis to fix its min, max, or both, for example to give several charts one shared scale; leave both unset and set startsAtZero to keep an auto-fitted axis anchored at zero. Set inverted on a measure axis to reverse its values, for example to put rank 1 at the top.
+- Set scale to log on a measure axis to draw it logarithmically, with gridlines at powers of ten. Zero and negative values are drawn at the floor of a log axis.
+
+**Canonical example**
+
+```json
+{
+  "data": {
+    "dimensions": [
+      {
+        "fieldKey": "[Cars].[Manufacturer]",
+        "format": {
+          "formatType": "none"
+        },
+        "ref": "manufacturer"
+      }
+    ],
+    "measures": [
+      {
+        "aggregation": "SUM",
+        "fieldKey": "[Cars].[Sales In Thousands]",
+        "format": {
+          "formatType": "number2Decimal",
+          "negativeType": "parenthesis"
+        },
+        "ref": "sales",
+        "dataLabels": {
+          "visible": true
+        },
+        "seriesType": "bar"
+      },
+      {
+        "aggregation": "AVG",
+        "fieldKey": "[Cars].[Horsepower]",
+        "format": {
+          "formatType": "number2Decimal",
+          "negativeType": "parenthesis"
+        },
+        "ref": "horsepower",
+        "axis": "secondary",
+        "seriesType": "line"
+      }
+    ]
+  },
+  "filterGroup": {
+    "filters": [
+      {
+        "fieldKey": "[Cars].[Manufacturer]",
+        "operator": "inList",
+        "values": ["Acura", "Audi", "BMW"]
+      }
+    ],
+    "operator": "and"
+  },
+  "limiting": {
+    "queryLimit": 100
+  },
+  "presentation": {
+    "axes": {
+      "dimension": {
+        "labelsVisible": true,
+        "title": "Manufacturer",
+        "titleVisible": true
+      },
+      "primaryMeasure": {
+        "labelsVisible": true,
+        "title": "Sales",
+        "titleVisible": true
+      }
+    },
+    "dataLabels": {
+      "visible": true
+    },
+    "legend": {
+      "position": "right",
+      "title": "Cars comparison",
+      "visible": true
+    },
+    "orientation": "vertical"
+  },
+  "sorting": [
+    {
+      "by": "sales",
+      "direction": "desc"
+    }
+  ],
+  "type": "combo",
+  "version": 1
+}
+```
+
+## `distribution-gauge`: Distribution gauge
+
+Gauge distribution across one or more values, optionally grouped by a dimension.
+
+**Data requirements**
+
+- Zero or one dimension.
+- Between one and twenty measures.
+
+**Supported features**
+
+`dimensions`, `filters`, `measures`, `value-formatting`, `conditional-coloring`, `display-mode`, `legend`
+
+**Constraints and semantics**
+
+- All measures are assigned the gauge-value role.
+- Distribution definitions enable the established gauge comparison mode.
+
+**Canonical example**
+
+```json
+{
+  "data": {
+    "dimensions": [
+      {
+        "fieldKey": "[Cars].[Manufacturer]",
+        "format": {
+          "formatType": "none"
+        },
+        "ref": "manufacturer"
+      }
+    ],
+    "measures": [
+      {
+        "aggregation": "SUM",
+        "fieldKey": "[Cars].[Sales In Thousands]",
+        "format": {
+          "formatType": "number2Decimal",
+          "negativeType": "parenthesis"
+        },
+        "ref": "sales"
+      },
+      {
+        "aggregation": "AVG",
+        "fieldKey": "[Cars].[Sales In Thousands]",
+        "format": {
+          "formatType": "number2Decimal",
+          "negativeType": "parenthesis"
+        },
+        "ref": "averageSales"
+      }
+    ]
+  },
+  "filterGroup": {
+    "filters": [
+      {
+        "fieldKey": "[Cars].[Manufacturer]",
+        "operator": "inList",
+        "values": ["Acura", "Audi", "BMW"]
+      }
+    ],
+    "operator": "and"
+  },
+  "presentation": {
+    "displayMode": "bar",
+    "legend": {
+      "position": "right",
+      "title": "Cars comparison",
+      "visible": true
+    }
+  },
+  "type": "distribution-gauge",
+  "version": 1
+}
+```
+
+## `dot`: Dot chart
+
+Dot comparison using two categorical dimensions and one measure.
+
+**Data requirements**
+
+- Exactly two dimensions.
+- Exactly one measure.
+
+**Supported features**
+
+`dimensions`, `filters`, `measures`, `value-formatting`, `conditional-coloring`, `axes`, `axis-range`, `legend`, `orientation`
+
+**Constraints and semantics**
+
+- Dimension order is significant and maps to the two dot-chart dimension roles.
+- Set range on the primary measure axis to fix its min, max, or both, for example to give several charts one shared scale; leave both unset and set startsAtZero to keep an auto-fitted axis anchored at zero. Set inverted on the primary measure axis to reverse its values.
+
+**Canonical example**
+
+```json
+{
+  "data": {
+    "dimensions": [
+      {
+        "fieldKey": "[Cars].[Manufacturer]",
+        "format": {
+          "formatType": "none"
+        },
+        "ref": "manufacturer"
+      },
+      {
+        "fieldKey": "[Cars].[Model]",
+        "format": {
+          "formatType": "none"
+        },
+        "ref": "model"
+      }
+    ],
+    "measures": [
+      {
+        "aggregation": "SUM",
+        "fieldKey": "[Cars].[Sales In Thousands]",
+        "format": {
+          "formatType": "number2Decimal",
+          "negativeType": "parenthesis"
+        },
+        "ref": "sales"
+      }
+    ]
+  },
+  "filterGroup": {
+    "filters": [
+      {
+        "fieldKey": "[Cars].[Manufacturer]",
+        "operator": "inList",
+        "values": ["Acura", "Audi", "BMW"]
+      }
+    ],
+    "operator": "and"
+  },
+  "presentation": {
+    "axes": {
+      "dimension": {
+        "labelsVisible": true,
+        "title": "Manufacturer",
+        "titleVisible": true
+      },
+      "primaryMeasure": {
+        "labelsVisible": true,
+        "title": "Sales",
+        "titleVisible": true
+      }
+    },
+    "legend": {
+      "position": "right",
+      "title": "Cars comparison",
+      "visible": true
+    },
+    "orientation": "horizontal"
+  },
+  "type": "dot",
+  "version": 1
+}
+```
+
+## `gauge`: Gauge chart
+
+Gauge values with an optional grouping dimension and optional data target.
+
+**Data requirements**
+
+- Zero or one dimension.
+- Between one and twenty measures; with one dimension, at most two measures.
+
+**Supported features**
+
+`dimensions`, `filters`, `measures`, `value-formatting`, `conditional-coloring`, `display-mode`, `legend`
+
+**Constraints and semantics**
+
+- With a dimension, the first measure is the gauge value and the optional second measure is the target.
+- Without a dimension, supplied measures are gauge values.
+- When a target measure is supplied, the compiler enables the established data-target mode.
+
+**Canonical example**
+
+```json
+{
+  "data": {
+    "dimensions": [
+      {
+        "fieldKey": "[Cars].[Manufacturer]",
+        "format": {
+          "formatType": "none"
+        },
+        "ref": "manufacturer"
+      }
+    ],
+    "measures": [
+      {
+        "aggregation": "SUM",
+        "fieldKey": "[Cars].[Sales In Thousands]",
+        "format": {
+          "formatType": "number2Decimal",
+          "negativeType": "parenthesis"
+        },
+        "ref": "sales"
+      },
+      {
+        "aggregation": "AVG",
+        "fieldKey": "[Cars].[Sales In Thousands]",
+        "format": {
+          "formatType": "number2Decimal",
+          "negativeType": "parenthesis"
+        },
+        "ref": "targetSales"
+      }
+    ]
+  },
+  "filterGroup": {
+    "filters": [
+      {
+        "fieldKey": "[Cars].[Manufacturer]",
+        "operator": "inList",
+        "values": ["Acura", "Audi", "BMW"]
+      }
+    ],
+    "operator": "and"
+  },
+  "presentation": {
+    "displayMode": "radial",
+    "legend": {
+      "position": "right",
+      "title": "Cars comparison",
+      "visible": true
+    }
+  },
+  "type": "gauge",
+  "version": 1
+}
+```
+
+## `heatMap`: Heat map
+
+Two-dimensional matrix colored and optionally sized by measures.
+
+**Data requirements**
+
+- Exactly two dimensions.
+- One or two measures.
+
+**Supported features**
+
+`dimensions`, `filters`, `measures`, `value-formatting`, `conditional-coloring`, `axes`, `legend`, `query-limit`, `sorting`
+
+**Constraints and semantics**
+
+- Dimension order maps to horizontal then vertical roles.
+- Measure order maps to color then optional size roles.
+
+**Canonical example**
+
+```json
+{
+  "data": {
+    "dimensions": [
+      {
+        "fieldKey": "[Cars].[Manufacturer]",
+        "format": {
+          "formatType": "none"
+        },
+        "ref": "manufacturer"
+      },
+      {
+        "fieldKey": "[Cars].[Model]",
+        "format": {
+          "formatType": "none"
+        },
+        "ref": "model"
+      }
+    ],
+    "measures": [
+      {
+        "aggregation": "SUM",
+        "fieldKey": "[Cars].[Sales In Thousands]",
+        "format": {
+          "formatType": "number2Decimal",
+          "negativeType": "parenthesis"
+        },
+        "ref": "sales"
+      },
+      {
+        "aggregation": "AVG",
+        "fieldKey": "[Cars].[Horsepower]",
+        "format": {
+          "formatType": "number2Decimal",
+          "negativeType": "parenthesis"
+        },
+        "ref": "horsepower"
+      }
+    ]
+  },
+  "filterGroup": {
+    "filters": [
+      {
+        "fieldKey": "[Cars].[Manufacturer]",
+        "operator": "inList",
+        "values": ["Acura", "Audi", "BMW"]
+      }
+    ],
+    "operator": "and"
+  },
+  "limiting": {
+    "queryLimit": 100
+  },
+  "presentation": {
+    "axes": {
+      "dimension": {
+        "labelsVisible": true,
+        "title": "Manufacturer",
+        "titleVisible": true
+      },
+      "primaryMeasure": {
+        "labelsVisible": true,
+        "title": "Sales",
+        "titleVisible": true
+      },
+      "secondaryDimension": {
+        "labelsVisible": true,
+        "title": "Model",
+        "titleVisible": true
+      }
+    },
+    "legend": {
+      "position": "right",
+      "title": "Cars comparison",
+      "visible": true
+    }
+  },
+  "sorting": [
+    {
+      "by": "sales",
+      "direction": "desc"
+    }
+  ],
+  "type": "heatMap",
+  "version": 1
+}
+```
+
+## `histogram`: Histogram
+
+Distribution of a numeric field into generated bins and counts.
+
+**Data requirements**
+
+- Exactly one numeric dimension.
+- No caller-supplied measures.
+
+**Supported features**
+
+`axes`, `axis-bands`, `axis-range`, `dimensions`, `filters`, `legend`, `orientation`, `value-formatting`
+
+**Constraints and semantics**
+
+- The compiler creates the canonical generated count measure; callers do not provide measures.
+- presentation.axes.primaryMeasure.bands shades the plot between two primary measure axis values; start and end are measure values, and the bands replace any on the base vSpec.
+- Set range on the primary measure axis to fix its min, max, or both, for example to give several charts one shared scale; leave both unset and set startsAtZero to keep an auto-fitted axis anchored at zero. Set inverted on the primary measure axis to reverse its values.
+
+**Canonical example**
+
+```json
+{
+  "data": {
+    "dimensions": [
+      {
+        "fieldKey": "[Cars].[Horsepower]",
+        "format": {
+          "formatType": "none"
+        },
+        "ref": "horsepower"
+      }
+    ]
+  },
+  "filterGroup": {
+    "filters": [
+      {
+        "fieldKey": "[Cars].[Manufacturer]",
+        "operator": "inList",
+        "values": ["Acura", "Audi", "BMW"]
+      }
+    ],
+    "operator": "and"
+  },
+  "presentation": {
+    "axes": {
+      "dimension": {
+        "labelsVisible": true,
+        "title": "Horsepower",
+        "titleVisible": true
+      },
+      "primaryMeasure": {
+        "labelsVisible": true,
+        "title": "Count",
+        "titleVisible": true
+      }
+    },
+    "legend": {
+      "position": "right",
+      "title": "Cars comparison",
+      "visible": true
+    },
+    "orientation": "vertical"
+  },
+  "type": "histogram",
+  "version": 1
+}
+```
+
+## `line`: Line chart
+
+Trend chart with sorting, query limiting, dual measure axes, labels, legend, and orientation.
+
+**Data requirements**
+
+- At least one dimension.
+- At least one measure.
+
+**Supported features**
+
+`axes`, `axis-bands`, `axis-range`, `axis-scale`, `conditional-coloring`, `data-labels`, `data-points`, `dimensions`, `filters`, `legend`, `measure-axis`, `measures`, `orientation`, `query-limit`, `sorting`, `value-formatting`
+
+**Constraints and semantics**
+
+- Each measure may select the primary or secondary axis using its axis property.
+- Visible data labels require dataPointShape on every measure.
+- presentation.axes.primaryMeasure.bands shades the plot between two primary measure axis values; start and end are measure values, and the bands replace any on the base vSpec.
+- Set range on a measure axis to fix its min, max, or both, for example to give several charts one shared scale; leave both unset and set startsAtZero to keep an auto-fitted axis anchored at zero. Set inverted on a measure axis to reverse its values, for example to put rank 1 at the top.
+- Set scale to log on a measure axis to draw it logarithmically, with gridlines at powers of ten. Zero and negative values are drawn at the floor of a log axis.
+- Value colors in presentation.coloring require at least two dimensions; measure color rules are not supported.
+
+**Canonical example**
+
+```json
+{
+  "data": {
+    "dimensions": [
+      {
+        "fieldKey": "[Cars].[Manufacturer]",
+        "format": {
+          "formatType": "none"
+        },
+        "ref": "manufacturer"
+      }
+    ],
+    "measures": [
+      {
+        "aggregation": "SUM",
+        "fieldKey": "[Cars].[Sales In Thousands]",
+        "format": {
+          "formatType": "number2Decimal",
+          "negativeType": "parenthesis"
+        },
+        "ref": "sales",
+        "axis": "primary",
+        "dataPointShape": "circle"
+      },
+      {
+        "aggregation": "AVG",
+        "fieldKey": "[Cars].[Horsepower]",
+        "format": {
+          "formatType": "number2Decimal",
+          "negativeType": "parenthesis"
+        },
+        "ref": "horsepower",
+        "axis": "secondary",
+        "dataPointShape": "square"
+      }
+    ]
+  },
+  "filterGroup": {
+    "filters": [
+      {
+        "fieldKey": "[Cars].[Manufacturer]",
+        "operator": "inList",
+        "values": ["Acura", "Audi", "BMW"]
+      }
+    ],
+    "operator": "and"
+  },
+  "limiting": {
+    "queryLimit": 100
+  },
+  "presentation": {
+    "axes": {
+      "dimension": {
+        "labelsVisible": true,
+        "title": "Manufacturer",
+        "titleVisible": true
+      },
+      "primaryMeasure": {
+        "labelsVisible": true,
+        "title": "Sales",
+        "titleVisible": true
+      },
+      "secondaryMeasure": {
+        "labelsVisible": true,
+        "title": "Horsepower",
+        "titleVisible": true
+      }
+    },
+    "dataLabels": {
+      "density": "medium",
+      "visible": true
+    },
+    "legend": {
+      "position": "right",
+      "title": "Cars comparison",
+      "visible": true
+    },
+    "orientation": "vertical"
+  },
+  "sorting": [
+    {
+      "by": "sales",
+      "direction": "desc"
+    }
+  ],
+  "type": "line",
+  "version": 1
+}
+```
+
+**Additional scenarios**
+
+### Fixed, inverted measure axis
+
+```json
+{
+  "data": {
+    "dimensions": [
+      {
+        "fieldKey": "[Cars].[Manufacturer]",
+        "format": {
+          "formatType": "none"
+        },
+        "ref": "manufacturer"
+      }
+    ],
+    "measures": [
+      {
+        "aggregation": "SUM",
+        "fieldKey": "[Cars].[Sales In Thousands]",
+        "format": {
+          "formatType": "number2Decimal",
+          "negativeType": "parenthesis"
+        },
+        "ref": "sales",
+        "dataPointShape": "circle"
+      }
+    ]
+  },
+  "presentation": {
+    "axes": {
+      "primaryMeasure": {
+        "inverted": true,
+        "range": {
+          "max": 100,
+          "min": 1
+        },
+        "title": "Rank"
+      }
+    }
+  },
+  "type": "line",
+  "version": 1
+}
+```
+
+### Series colored by dimension value
+
+```json
+{
+  "data": {
+    "dimensions": [
+      {
+        "fieldKey": "[Cars].[Manufacturer]",
+        "format": {
+          "formatType": "none"
+        },
+        "ref": "manufacturer"
+      },
+      {
+        "fieldKey": "[Cars].[Model]",
+        "format": {
+          "formatType": "none"
+        },
+        "ref": "model"
+      }
+    ],
+    "measures": [
+      {
+        "aggregation": "SUM",
+        "fieldKey": "[Cars].[Sales In Thousands]",
+        "format": {
+          "formatType": "number2Decimal",
+          "negativeType": "parenthesis"
+        },
+        "ref": "sales",
+        "dataPointShape": "circle"
+      }
+    ]
+  },
+  "presentation": {
+    "coloring": {
+      "overwrites": [
+        {
+          "color": "#7C3AED",
+          "operator": "startsWith",
+          "value": "A"
+        }
+      ]
+    }
+  },
+  "type": "line",
+  "version": 1
+}
+```
+
+## `radar`: Radar chart
+
+Radial comparison chart for one or more measures with optional categorical dimensions.
+
+**Data requirements**
+
+- Zero to two dimensions.
+- Two to five measures without dimensions, or one with dimensions.
+
+**Supported features**
+
+`dimensions`, `filters`, `measures`, `value-formatting`, `conditional-coloring`, `legend`
+
+**Constraints and semantics**
+
+- Without dimensions, at least two measures are required.
+- With dimensions, exactly one measure is supported.
+- Value colors in presentation.coloring require two dimensions; measure color rules are not supported.
+
+**Canonical example**
+
+```json
+{
+  "data": {
+    "dimensions": [
+      {
+        "fieldKey": "[Cars].[Manufacturer]",
+        "format": {
+          "formatType": "none"
+        },
+        "ref": "manufacturer"
+      }
+    ],
+    "measures": [
+      {
+        "aggregation": "SUM",
+        "fieldKey": "[Cars].[Sales In Thousands]",
+        "format": {
+          "formatType": "number2Decimal",
+          "negativeType": "parenthesis"
+        },
+        "ref": "sales"
+      }
+    ]
+  },
+  "filterGroup": {
+    "filters": [
+      {
+        "fieldKey": "[Cars].[Manufacturer]",
+        "operator": "inList",
+        "values": ["Acura", "Audi", "BMW"]
+      }
+    ],
+    "operator": "and"
+  },
+  "presentation": {
+    "legend": {
+      "position": "right",
+      "title": "Cars comparison",
+      "visible": true
+    }
+  },
+  "type": "radar",
+  "version": 1
+}
+```
+
+## `pie`: Pie chart
+
+Part-to-whole chart with optional secondary radial measure.
+
+**Data requirements**
+
+- Exactly one dimension.
+- One or two measures.
+
+**Supported features**
+
+`dimensions`, `filters`, `measures`, `value-formatting`, `conditional-coloring`, `legend`, `query-limit`, `sorting`
+
+**Constraints and semantics**
+
+- The first measure is the slice value; the optional second measure receives the length role.
+
+**Canonical example**
+
+```json
+{
+  "data": {
+    "dimensions": [
+      {
+        "fieldKey": "[Cars].[Manufacturer]",
+        "format": {
+          "formatType": "none"
+        },
+        "ref": "manufacturer"
+      }
+    ],
+    "measures": [
+      {
+        "aggregation": "SUM",
+        "fieldKey": "[Cars].[Sales In Thousands]",
+        "format": {
+          "formatType": "number2Decimal",
+          "negativeType": "parenthesis"
+        },
+        "ref": "sales"
+      }
+    ]
+  },
+  "filterGroup": {
+    "filters": [
+      {
+        "fieldKey": "[Cars].[Manufacturer]",
+        "operator": "inList",
+        "values": ["Acura", "Audi", "BMW"]
+      }
+    ],
+    "operator": "and"
+  },
+  "limiting": {
+    "queryLimit": 100
+  },
+  "presentation": {
+    "legend": {
+      "position": "right",
+      "title": "Cars comparison",
+      "visible": true
+    }
+  },
+  "sorting": [
+    {
+      "by": "sales",
+      "direction": "desc"
+    }
+  ],
+  "type": "pie",
+  "version": 1
+}
+```
+
+**Additional scenarios**
+
+### Ordered bands colored along a ramp
+
+```json
+{
+  "data": {
+    "dimensions": [
+      {
+        "fieldKey": "[Cars].[Manufacturer]",
+        "format": {
+          "formatType": "none"
+        },
+        "ref": "manufacturer"
+      }
+    ],
+    "measures": [
+      {
+        "aggregation": "SUM",
+        "fieldKey": "[Cars].[Sales In Thousands]",
+        "format": {
+          "formatType": "number2Decimal",
+          "negativeType": "parenthesis"
+        },
+        "ref": "sales"
+      }
+    ]
+  },
+  "presentation": {
+    "coloring": {
+      "overwrites": [
+        {
+          "color": "#134E4A",
+          "value": "Audi"
+        },
+        {
+          "color": "#2DD4BF",
+          "value": "BMW"
+        },
+        {
+          "color": "#CCFBF1",
+          "value": "Buick"
+        }
+      ]
+    }
+  },
+  "type": "pie",
+  "version": 1
+}
+```
+
+## `tree`: Tree chart
+
+Hierarchical tree built from dimensions, measures, or both.
+
+**Data requirements**
+
+- Zero to ten dimensions.
+- Zero to one hundred measures, or at most one with dimensions.
+
+**Supported features**
+
+`dimensions`, `filters`, `measures`, `value-formatting`, `layout`, `query-limit`, `sorting`
+
+**Constraints and semantics**
+
+- At least one dimension or measure must be supplied.
+- Trees with dimensions support at most one measure; measure-only trees may contain multiple measures.
+
+**Canonical example**
+
+```json
+{
+  "data": {
+    "dimensions": [
+      {
+        "fieldKey": "[Cars].[Manufacturer]",
+        "format": {
+          "formatType": "none"
+        },
+        "ref": "manufacturer"
+      },
+      {
+        "fieldKey": "[Cars].[Model]",
+        "format": {
+          "formatType": "none"
+        },
+        "ref": "model"
+      }
+    ],
+    "measures": [
+      {
+        "aggregation": "SUM",
+        "fieldKey": "[Cars].[Sales In Thousands]",
+        "format": {
+          "formatType": "number2Decimal",
+          "negativeType": "parenthesis"
+        },
+        "ref": "sales"
+      }
+    ]
+  },
+  "filterGroup": {
+    "filters": [
+      {
+        "fieldKey": "[Cars].[Manufacturer]",
+        "operator": "inList",
+        "values": ["Acura", "Audi", "BMW"]
+      }
+    ],
+    "operator": "and"
+  },
+  "limiting": {
+    "queryLimit": 100
+  },
+  "presentation": {
+    "layout": {
+      "compact": true,
+      "direction": "top",
+      "forceAutoFit": false,
+      "initialExpandedLevels": 1
+    }
+  },
+  "sorting": [
+    {
+      "by": "sales",
+      "direction": "desc"
+    }
+  ],
+  "type": "tree",
+  "version": 1
+}
+```
+
+## `treemap`: Treemap
+
+Hierarchical area chart using ordered dimensions and one size measure.
+
+**Data requirements**
+
+- Between one and ten dimensions.
+- Exactly one measure.
+
+**Supported features**
+
+`dimensions`, `filters`, `measures`, `value-formatting`, `conditional-coloring`, `legend`
+
+**Constraints and semantics**
+
+- Dimension order defines hierarchy depth.
+
+**Canonical example**
+
+```json
+{
+  "data": {
+    "dimensions": [
+      {
+        "fieldKey": "[Cars].[Manufacturer]",
+        "format": {
+          "formatType": "none"
+        },
+        "ref": "manufacturer"
+      },
+      {
+        "fieldKey": "[Cars].[Model]",
+        "format": {
+          "formatType": "none"
+        },
+        "ref": "model"
+      }
+    ],
+    "measures": [
+      {
+        "aggregation": "SUM",
+        "fieldKey": "[Cars].[Sales In Thousands]",
+        "format": {
+          "formatType": "number2Decimal",
+          "negativeType": "parenthesis"
+        },
+        "ref": "sales"
+      }
+    ]
+  },
+  "filterGroup": {
+    "filters": [
+      {
+        "fieldKey": "[Cars].[Manufacturer]",
+        "operator": "inList",
+        "values": ["Acura", "Audi", "BMW"]
+      }
+    ],
+    "operator": "and"
+  },
+  "presentation": {
+    "legend": {
+      "position": "right",
+      "title": "Cars comparison",
+      "visible": true
+    }
+  },
+  "type": "treemap",
+  "version": 1
+}
+```
+
+## `sankey`: Sankey chart
+
+Flow chart across an ordered sequence of categorical dimensions.
+
+**Data requirements**
+
+- Between two and fifteen dimensions.
+- Exactly one measure.
+
+**Supported features**
+
+`dimensions`, `filters`, `measures`, `value-formatting`, `conditional-coloring`
+
+**Constraints and semantics**
+
+- Dimension order defines the source-to-target flow stages.
+- Every value color in presentation.coloring must name the dimension it applies to.
+
+**Canonical example**
+
+```json
+{
+  "data": {
+    "dimensions": [
+      {
+        "fieldKey": "[Cars].[Manufacturer]",
+        "format": {
+          "formatType": "none"
+        },
+        "ref": "manufacturer"
+      },
+      {
+        "fieldKey": "[Cars].[Model]",
+        "format": {
+          "formatType": "none"
+        },
+        "ref": "model"
+      }
+    ],
+    "measures": [
+      {
+        "aggregation": "SUM",
+        "fieldKey": "[Cars].[Sales In Thousands]",
+        "format": {
+          "formatType": "number2Decimal",
+          "negativeType": "parenthesis"
+        },
+        "ref": "sales"
+      }
+    ]
+  },
+  "filterGroup": {
+    "filters": [
+      {
+        "fieldKey": "[Cars].[Manufacturer]",
+        "operator": "inList",
+        "values": ["Acura", "Audi", "BMW"]
+      }
+    ],
+    "operator": "and"
+  },
+  "type": "sankey",
+  "version": 1
+}
+```
+
+**Additional scenarios**
+
+### A color bound to a value of one flow stage
+
+```json
+{
+  "data": {
+    "dimensions": [
+      {
+        "fieldKey": "[Cars].[Manufacturer]",
+        "format": {
+          "formatType": "none"
+        },
+        "ref": "manufacturer"
+      },
+      {
+        "fieldKey": "[Cars].[Model]",
+        "format": {
+          "formatType": "none"
+        },
+        "ref": "model"
+      }
+    ],
+    "measures": [
+      {
+        "aggregation": "SUM",
+        "fieldKey": "[Cars].[Sales In Thousands]",
+        "format": {
+          "formatType": "number2Decimal",
+          "negativeType": "parenthesis"
+        },
+        "ref": "sales"
+      }
+    ]
+  },
+  "presentation": {
+    "coloring": {
+      "overwrites": [
+        {
+          "color": "#CA8A04",
+          "dimension": "manufacturer",
+          "value": "Audi"
+        }
+      ]
+    }
+  },
+  "type": "sankey",
+  "version": 1
+}
+```
+
+## `scatter`: Scatter chart
+
+Relationship chart using horizontal and vertical measures with optional size and image roles.
+
+**Data requirements**
+
+- One or two dimensions.
+- Two or three measures.
+
+**Supported features**
+
+`dimensions`, `filters`, `measures`, `value-formatting`, `conditional-coloring`, `axes`, `axis-range`, `legend`, `query-limit`, `sorting`
+
+**Constraints and semantics**
+
+- Measure order maps to horizontal, vertical, and optional size roles.
+- The optional second dimension receives the image role.
+- Roles come from item order only; a ref is a label and does not select a role.
+- With a size measure, points scale between the setPointSize and setMaxPointSize operation values.
+- Set range on a measure axis to fix its min, max, or both, for example to give several charts one shared scale; leave both unset and set startsAtZero to keep an auto-fitted axis anchored at zero. Set inverted on a measure axis to reverse its values, for example to put rank 1 at the top.
+
+**Canonical example**
+
+```json
+{
+  "data": {
+    "dimensions": [
+      {
+        "fieldKey": "[Cars].[Manufacturer]",
+        "format": {
+          "formatType": "none"
+        },
+        "ref": "manufacturer"
+      }
+    ],
+    "measures": [
+      {
+        "aggregation": "SUM",
+        "fieldKey": "[Cars].[Sales In Thousands]",
+        "format": {
+          "formatType": "number2Decimal",
+          "negativeType": "parenthesis"
+        },
+        "ref": "sales"
+      },
+      {
+        "aggregation": "AVG",
+        "fieldKey": "[Cars].[Horsepower]",
+        "format": {
+          "formatType": "number2Decimal",
+          "negativeType": "parenthesis"
+        },
+        "ref": "horsepower"
+      },
+      {
+        "aggregation": "AVG",
+        "fieldKey": "[Cars].[Sales In Thousands]",
+        "format": {
+          "formatType": "number2Decimal",
+          "negativeType": "parenthesis"
+        },
+        "ref": "size"
+      }
+    ]
+  },
+  "filterGroup": {
+    "filters": [
+      {
+        "fieldKey": "[Cars].[Manufacturer]",
+        "operator": "inList",
+        "values": ["Acura", "Audi", "BMW"]
+      }
+    ],
+    "operator": "and"
+  },
+  "presentation": {
+    "axes": {
+      "primaryMeasure": {
+        "labelsVisible": true,
+        "title": "Sales",
+        "titleVisible": true
+      },
+      "secondaryMeasure": {
+        "labelsVisible": true,
+        "title": "Horsepower",
+        "titleVisible": true
+      }
+    },
+    "legend": {
+      "position": "right",
+      "title": "Cars comparison",
+      "visible": true
+    }
+  },
+  "type": "scatter",
+  "version": 1
+}
+```
+
+## `table`: Table
+
+Normal, expandable, or pivot tabular output with formatting, filtering, sorting, query limiting, and totals.
+
+**Data requirements**
+
+- Normal tables require at least one ordered dimension or measure column.
+- Expandable tables require at least one dimension and one measure.
+- Pivot tables require at least one row dimension, one column dimension, and one measure.
+
+**Supported features**
+
+`dimensions`, `filters`, `layout`, `measures`, `query-limit`, `sorting`, `table-structure`, `totals`, `value-formatting`
+
+**Constraints and semantics**
+
+- Normal table column order is preserved, and each column declares whether it is a dimension or measure.
+- Expandable table dimension order defines the expansion hierarchy.
+- Pivot tables explicitly separate row dimensions, column dimensions, and measures.
+- Measure definitions require valid aggregation for raw fields.
+- Presentation settings initialize table appearance and layout; later runtime operations preserve them.
+- Totals settings are optional; omitted totals properties preserve their values from the fresh default or preset vSpec.
+
+**Canonical example**
+
+```json
+{
+  "data": {
+    "columns": [
+      {
+        "fieldKey": "[Cars].[Manufacturer]",
+        "format": {
+          "formatType": "none"
+        },
+        "ref": "manufacturer",
+        "role": "dimension"
+      },
+      {
+        "fieldKey": "[Cars].[Model]",
+        "format": {
+          "formatType": "none"
+        },
+        "ref": "model",
+        "role": "dimension"
+      },
+      {
+        "aggregation": "SUM",
+        "fieldKey": "[Cars].[Sales In Thousands]",
+        "format": {
+          "formatType": "number2Decimal",
+          "negativeType": "parenthesis"
+        },
+        "ref": "sales",
+        "role": "measure"
+      }
+    ],
+    "structure": "normal"
+  },
+  "filterGroup": {
+    "filters": [
+      {
+        "fieldKey": "[Cars].[Manufacturer]",
+        "operator": "inList",
+        "values": ["Acura", "Audi", "BMW"]
+      }
+    ],
+    "operator": "and"
+  },
+  "limiting": {
+    "queryLimit": 100
+  },
+  "presentation": {
+    "background": {
+      "color": "#ffffff",
+      "type": "single"
+    },
+    "body": {
+      "fontColor": "#1f1c3b",
+      "fontFamily": "Roboto",
+      "fontSize": 13,
+      "horizontalAlign": "center",
+      "verticalAlign": "middle"
+    },
+    "borders": {
+      "color": "#e0e0e0",
+      "dividerColor": "#e0e0e0",
+      "dividers": "all",
+      "enabled": true,
+      "lineStyle": "line",
+      "radius": 4,
+      "strokeWidth": 1
+    },
+    "header": {
+      "backgroundColor": "#ffffff",
+      "borderColor": "#e0e0e0",
+      "fontColor": "#1f1c3b",
+      "fontFamily": "Roboto",
+      "fontSize": 13
+    },
+    "highlight": {
+      "backgroundColor": "#f2f2f2",
+      "mode": "row"
+    },
+    "layout": {
+      "columnWidthBehavior": "responsive",
+      "rowHeight": 41
+    }
+  },
+  "sorting": [
+    {
+      "by": "sales",
+      "direction": "desc"
+    }
+  ],
+  "totals": {
+    "applyTo": "both",
+    "enabled": true,
+    "showRecordsCount": true,
+    "style": {
+      "backgroundColor": "#f3f4f6",
+      "fontColor": "#111827",
+      "fontStyle": {
+        "bold": true
+      },
+      "position": "bottom",
+      "responsiveHeight": true
+    }
+  },
+  "type": "table",
+  "version": 1
+}
+```
+
+**Additional scenarios**
+
+### Expandable table
+
+```json
+{
+  "data": {
+    "dimensions": [
+      {
+        "fieldKey": "[Cars].[Manufacturer]",
+        "format": {
+          "formatType": "none"
+        },
+        "ref": "manufacturer"
+      },
+      {
+        "fieldKey": "[Cars].[Model]",
+        "format": {
+          "formatType": "none"
+        },
+        "ref": "model"
+      }
+    ],
+    "measures": [
+      {
+        "aggregation": "SUM",
+        "fieldKey": "[Cars].[Sales In Thousands]",
+        "format": {
+          "formatType": "number2Decimal",
+          "negativeType": "parenthesis"
+        },
+        "ref": "sales"
+      }
+    ],
+    "structure": "expandable"
+  },
+  "filterGroup": {
+    "filters": [
+      {
+        "fieldKey": "[Cars].[Manufacturer]",
+        "operator": "inList",
+        "values": ["Acura", "Audi", "BMW"]
+      }
+    ],
+    "operator": "and"
+  },
+  "limiting": {
+    "queryLimit": 100
+  },
+  "sorting": [
+    {
+      "by": "sales",
+      "direction": "desc"
+    }
+  ],
+  "type": "table",
+  "version": 1
+}
+```
+
+### Pivot table
+
+```json
+{
+  "data": {
+    "columnDimensions": [
+      {
+        "fieldKey": "[Cars].[Model]",
+        "format": {
+          "formatType": "none"
+        },
+        "ref": "model"
+      }
+    ],
+    "measures": [
+      {
+        "aggregation": "SUM",
+        "fieldKey": "[Cars].[Sales In Thousands]",
+        "format": {
+          "formatType": "number2Decimal",
+          "negativeType": "parenthesis"
+        },
+        "ref": "sales"
+      }
+    ],
+    "rowDimensions": [
+      {
+        "fieldKey": "[Cars].[Manufacturer]",
+        "format": {
+          "formatType": "none"
+        },
+        "ref": "manufacturer"
+      }
+    ],
+    "structure": "pivot"
+  },
+  "filterGroup": {
+    "filters": [
+      {
+        "fieldKey": "[Cars].[Manufacturer]",
+        "operator": "inList",
+        "values": ["Acura", "Audi", "BMW"]
+      }
+    ],
+    "operator": "and"
+  },
+  "limiting": {
+    "queryLimit": 100
+  },
+  "sorting": [
+    {
+      "by": "sales",
+      "direction": "desc"
+    }
+  ],
+  "type": "table",
+  "version": 1
+}
+```
+
+## `waterfall`: Waterfall chart
+
+Sequential contribution chart composed from one or more measures.
+
+**Data requirements**
+
+- Between one and one hundred measures.
+
+**Supported features**
+
+`axes`, `axis-bands`, `axis-range`, `data-labels`, `filters`, `measures`, `orientation`, `value-formatting`
+
+**Constraints and semantics**
+
+- Dimensions are not supported. Measure order defines the waterfall sequence.
+- Set range on the primary measure axis to fix its min, max, or both, for example to give several charts one shared scale; leave both unset and set startsAtZero to keep an auto-fitted axis anchored at zero. Set inverted on the primary measure axis to reverse its values.
+- presentation.axes.primaryMeasure.bands shades the plot between two primary measure axis values; start and end are measure values, and the bands replace any on the base vSpec.
+
+**Canonical example**
+
+```json
+{
+  "data": {
+    "measures": [
+      {
+        "aggregation": "SUM",
+        "fieldKey": "[Cars].[Sales In Thousands]",
+        "format": {
+          "formatType": "number2Decimal",
+          "negativeType": "parenthesis"
+        },
+        "ref": "sales",
+        "dataLabels": {
+          "visible": true
+        }
+      },
+      {
+        "aggregation": "AVG",
+        "fieldKey": "[Cars].[Horsepower]",
+        "format": {
+          "formatType": "number2Decimal",
+          "negativeType": "parenthesis"
+        },
+        "ref": "horsepower",
+        "dataLabels": {
+          "visible": true
+        }
+      }
+    ]
+  },
+  "filterGroup": {
+    "filters": [
+      {
+        "fieldKey": "[Cars].[Manufacturer]",
+        "operator": "inList",
+        "values": ["Acura", "Audi", "BMW"]
+      }
+    ],
+    "operator": "and"
+  },
+  "presentation": {
+    "axes": {
+      "dimension": {
+        "labelsVisible": true,
+        "title": "Measure",
+        "titleVisible": true
+      },
+      "primaryMeasure": {
+        "labelsVisible": true,
+        "title": "Value",
+        "titleVisible": true
+      }
+    },
+    "dataLabels": {
+      "visible": true
+    },
+    "orientation": "vertical"
+  },
+  "type": "waterfall",
+  "version": 1
+}
+```
+
+## `word-cloud`: Word cloud
+
+Weighted word display using one label dimension and one measure.
+
+**Data requirements**
+
+- Exactly one dimension.
+- Exactly one measure.
+
+**Supported features**
+
+`dimensions`, `filters`, `measures`, `value-formatting`, `conditional-coloring`
+
+**Constraints and semantics**
+
+- The dimension supplies words and the measure supplies their weight.
+
+**Canonical example**
+
+```json
+{
+  "data": {
+    "dimensions": [
+      {
+        "fieldKey": "[Cars].[Manufacturer]",
+        "format": {
+          "formatType": "none"
+        },
+        "ref": "manufacturer"
+      }
+    ],
+    "measures": [
+      {
+        "aggregation": "SUM",
+        "fieldKey": "[Cars].[Sales In Thousands]",
+        "format": {
+          "formatType": "number2Decimal",
+          "negativeType": "parenthesis"
+        },
+        "ref": "sales"
+      }
+    ]
+  },
+  "filterGroup": {
+    "filters": [
+      {
+        "fieldKey": "[Cars].[Manufacturer]",
+        "operator": "inList",
+        "values": ["Acura", "Audi", "BMW"]
+      }
+    ],
+    "operator": "and"
+  },
+  "type": "word-cloud",
+  "version": 1
+}
+```
+
+## `date-picker`: Date picker
+
+Date selection control with single/range modes, labels, quick select, and responsive settings.
+
+**Data requirements**
+
+- Exactly one field.
+
+**Supported features**
+
+`dimensions`, `filter-settings`
+
+**Constraints and semantics**
+
+- The selected field must be date- or timestamp-compatible.
+
+**Canonical example**
+
+```json
+{
+  "data": {
+    "field": {
+      "fieldKey": "[Cars].[Latest Launch]",
+      "ref": "latestLaunch"
+    }
+  },
+  "settings": {
+    "endDateLabel": "To",
+    "pickerState": "expanded",
+    "pickerType": "range",
+    "quickSelect": true,
+    "responsive": true,
+    "startDateLabel": "From",
+    "timePickerVisibility": "never",
+    "weekStart": "1"
+  },
+  "type": "date-picker",
+  "version": 1
+}
+```
+
+## `filter`: Filter
+
+Interactive field filter with list/dropdown presentation and search/quick-select controls.
+
+**Data requirements**
+
+- Exactly one field.
+
+**Supported features**
+
+`dimensions`, `filter-settings`
+
+**Constraints and semantics**
+
+- The selected field is used as a filter dimension.
+
+**Canonical example**
+
+```json
+{
+  "data": {
+    "field": {
+      "fieldKey": "[Cars].[Manufacturer]",
+      "ref": "manufacturer"
+    }
+  },
+  "presentation": {
+    "mode": "listbox",
+    "quickSelect": true,
+    "responsive": true,
+    "searchable": true,
+    "showProgressBar": false
+  },
+  "type": "filter",
+  "version": 1
+}
+```
+
+## `iframe`: Iframe
+
+Embedded external web content.
+
+**Data requirements**
+
+- No query data.
+
+**Supported features**
+
+`content`
+
+**Constraints and semantics**
+
+- The URL must be absolute and valid; null clears the source.
+
+**Canonical example**
+
+```json
+{
+  "settings": {
+    "url": "https://example.com"
+  },
+  "type": "iframe",
+  "version": 1
+}
+```
+
+## `image`: Image
+
+Image content with fit, opacity, blur, saturation, and shadow controls.
+
+**Data requirements**
+
+- No query data.
+
+**Supported features**
+
+`content`, `object-settings`
+
+**Constraints and semantics**
+
+- The source must use one of the supported image source variants.
+
+**Canonical example**
+
+```json
+{
+  "settings": {
+    "blur": 0,
+    "fit": "contain",
+    "opacity": 0.95,
+    "saturation": 0.9,
+    "shadow": true,
+    "source": {
+      "imageUrl": "https://example.com/image.png",
+      "sourceKind": "url"
+    }
+  },
+  "type": "image",
+  "version": 1
+}
+```
+
+## `number`: Number
+
+Single aggregated or semantic value with value formatting and static filters.
+
+**Data requirements**
+
+- Exactly one measure.
+
+**Supported features**
+
+`filters`, `measures`, `value-formatting`
+
+**Constraints and semantics**
+
+- A raw field measure requires aggregation; semantic measures and calculations omit it.
+
+**Canonical example**
+
+```json
+{
+  "data": {
+    "measure": {
+      "aggregation": "SUM",
+      "fieldKey": "[Cars].[Sales In Thousands]",
+      "format": {
+        "formatType": "number2Decimal",
+        "negativeType": "parenthesis"
+      },
+      "ref": "sales"
+    }
+  },
+  "filterGroup": {
+    "filters": [
+      {
+        "fieldKey": "[Cars].[Manufacturer]",
+        "operator": "inList",
+        "values": ["Acura", "Audi", "BMW"]
+      }
+    ],
+    "operator": "and"
+  },
+  "type": "number",
+  "version": 1
+}
+```
+
+## `shape`: Shape
+
+Decorative shape with fill, stroke, sizing, rotation, and border controls.
+
+**Data requirements**
+
+- No query data.
+
+**Supported features**
+
+`object-settings`
+
+**Constraints and semantics**
+
+- Image-specific settings apply only when the selected shape/background mode supports them.
+
+**Canonical example**
+
+```json
+{
+  "settings": {
+    "backgroundColor": {
+      "code": "#2e6e9e"
+    },
+    "backgroundType": "color",
+    "borderEnabled": true,
+    "borderRadius": 8,
+    "heightBasedSize": false,
+    "lineThickness": 4,
+    "preserveAspectRatio": true,
+    "rotate": 12,
+    "scale": 0.7,
+    "shape": "hexagon",
+    "strokeColor": {
+      "code": "#18212b"
+    }
+  },
+  "type": "shape",
+  "version": 1
+}
+```
+
+## `simpleTextObject`: Text object
+
+Text or Markdown content with typography, alignment, wrapping, and responsive controls.
+
+**Data requirements**
+
+- No query data.
+
+**Supported features**
+
+`content`, `object-settings`
+
+**Constraints and semantics**
+
+- Content interpretation follows the selected representation.
+
+**Canonical example**
+
+```json
+{
+  "settings": {
+    "align": "center",
+    "content": "## Revenue overview",
+    "fontFamily": "Arial",
+    "fontSize": 30,
+    "position": "middle",
+    "representation": "markdown",
+    "responsive": true,
+    "textColor": "#18212b",
+    "wordWrap": true
+  },
+  "type": "simpleTextObject",
+  "version": 1
+}
+```
+
+## `atomic-input`: Atomic input
+
+Variable input control with input type, label, placeholder, and responsive settings.
+
+**Data requirements**
+
+- No query data; variable-backed input.
+
+**Supported features**
+
+`input-settings`
+
+**Constraints and semantics**
+
+- The referenced variable must exist in the host variable service when variable behavior is used.
+
+**Canonical example**
+
+```json
+{
+  "settings": {
+    "customLabel": {
+      "enabled": true,
+      "text": "Target"
+    },
+    "inputType": "text",
+    "placeholder": "Enter target",
+    "responsive": true,
+    "variableId": "target-variable"
+  },
+  "type": "atomic-input",
+  "version": 1
+}
+```
+
+## `astrato-app-filter-bar`: Astrato App Filter Bar
+
+App filter bar settings for selection behavior, filter creation, associative filtering, and selectable fields.
+
+**Data requirements**
+
+- No query data; uses field metadata and selections supplied by the host.
+
+**Supported features**
+
+`selection-settings`
+
+**Constraints and semantics**
+
+- Orientation defaults to horizontal. Use vertical for stacked sidebar filters; editors open beside the sidebar when space permits.
+- The bar displays active selections from its selection group, regardless of the fields allowed for creating new filters.
+- An empty selectableFieldKeys list allows users to create filters on any selectable field.
+- Selection mode overrides apply only to selections created by this bar; apply, cancel, and clear affect the shared selection group.
+- Chart breakdown switching is hidden by default. Enable showChartBreakdown only when the app uses dimension groups; a group must have multiple available fields for the control to appear.
+
+**Canonical example**
+
+```json
+{
+  "settings": {
+    "enableAddingNewFilters": true,
+    "enableAssociativeFilter": true,
+    "selectableFieldKeys": ["[Cars].[Manufacturer]", "[Cars].[Model]"],
+    "selectionMode": "inherit",
+    "showChartBreakdown": false,
+    "showClearAll": true
+  },
+  "type": "astrato-app-filter-bar",
+  "version": 1
+}
+```
+
+## `slider`: Slider
+
+Numeric or date range control with single/multi layout, step, and quick select.
+
+**Data requirements**
+
+- Exactly one field.
+
+**Supported features**
+
+`dimensions`, `filter-settings`
+
+**Constraints and semantics**
+
+- The field must be numeric or date-compatible with the configured range and step.
+- Providing range enables manual bounds; omitting it keeps data-derived bounds.
+
+**Canonical example**
+
+```json
+{
+  "data": {
+    "field": {
+      "fieldKey": "[Cars].[Horsepower]",
+      "ref": "horsepower"
+    }
+  },
+  "settings": {
+    "layout": "multi",
+    "quickSelect": true,
+    "range": {
+      "max": 500,
+      "min": 0
+    },
+    "step": 10
+  },
+  "type": "slider",
+  "version": 1
+}
+```