Visualization definition reference

17 min read · Updated 29 Oct 2026

Reference for @astrato-io/visualizations@0.6.5.

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:

descriptor.jsonSchema, which defines the allowed JSON structure.
descriptor.documentation, which explains what the properties mean and lists chart-specific rules.
descriptor.examples, which shows valid definitions.
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:

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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "data": {
    "field": {
      "fieldKey": "[Cars].[Horsepower]",
      "ref": "horsepower"
    }
  },
  "settings": {
    "layout": "multi",
    "quickSelect": true,
    "range": {
      "max": 500,
      "min": 0
    },
    "step": 10
  },
  "type": "slider",
  "version": 1
}

Visualization definition reference

How To Use This Reference

Integrating With AI

Finishing A Chart Before Mounting

Common Feature Names

Capability Index

bar: Bar chart

Colors bound to dimension values and a measure threshold

combo: Combo chart

distribution-gauge: Distribution gauge

dot: Dot chart

gauge: Gauge chart

heatMap: Heat map

histogram: Histogram

line: Line chart

Fixed, inverted measure axis

Series colored by dimension value

radar: Radar chart

pie: Pie chart

Ordered bands colored along a ramp

tree: Tree chart

treemap: Treemap

sankey: Sankey chart

A color bound to a value of one flow stage

scatter: Scatter chart

table: Table

Expandable table

Pivot table

waterfall: Waterfall chart

word-cloud: Word cloud

date-picker: Date picker

filter: Filter

iframe: Iframe

image: Image

number: Number

shape: Shape

simpleTextObject: Text object

atomic-input: Atomic input

astrato-app-filter-bar: Astrato App Filter Bar

slider: Slider

`bar`: Bar chart

`combo`: Combo chart

`distribution-gauge`: Distribution gauge

`dot`: Dot chart

`gauge`: Gauge chart

`heatMap`: Heat map

`histogram`: Histogram

`line`: Line chart

`radar`: Radar chart

`pie`: Pie chart

`tree`: Tree chart

`treemap`: Treemap

`sankey`: Sankey chart

`scatter`: Scatter chart

`table`: Table

`waterfall`: Waterfall chart

`word-cloud`: Word cloud

`date-picker`: Date picker

`filter`: Filter

`iframe`: Iframe

`image`: Image

`number`: Number

`shape`: Shape

`simpleTextObject`: Text object

`atomic-input`: Atomic input

`astrato-app-filter-bar`: Astrato App Filter Bar

`slider`: Slider