ObjectStackObjectStack
ReferenceUI Protocol

Chart schema — UI Protocol property reference

Shared by Dashboard and Report widgets. Provides a comprehensive set of chart types for data visualization.

Unified Chart Type Taxonomy

Shared by Dashboard and Report widgets. Provides a comprehensive set of chart types for data visualization.

Source: packages/spec/src/ui/chart.zod.ts

TypeScript Usage

import { ChartAggregateSchema, ChartAggregateFunctionSchema, ChartAnnotationSchema, ChartAxisSchema, ChartConfigSchema, ChartDrillDownSchema, ChartGroupBySchema, ChartInteractionSchema, ChartSeriesSchema, ChartTypeSchema } from '@objectstack/spec/ui';
import type { ChartAggregate, ChartAggregateFunction, ChartAnnotation, ChartAxis, ChartConfig, ChartDrillDown, ChartGroupBy, ChartInteraction, ChartSeries, ChartType } from '@objectstack/spec/ui';

// Validate data
const result = ChartAggregateSchema.parse(data);

ChartAggregate

Inline aggregation for an object-bound chart

Properties

PropertyTypeRequiredDescription
fieldstringoptionalField to aggregate — required for sum/avg/min/max, optional for count
functionEnum<'count' | 'sum' | 'avg' | 'min' | 'max'>✅Aggregation function
groupBystring | { field: string; dateGranularity?: Enum<'day' | 'week' | 'month' | 'quarter' | 'year'>; alias?: string }✅Field the rows are grouped by — the chart category axis

Nested Shape: ChartAggregate.groupBy

PropertyTypeRequiredDescription
fieldstring✅Field to group by
dateGranularityEnum<'day' | 'week' | 'month' | 'quarter' | 'year'>optionalBucket date values into uniform periods
aliasstringoptionalAlias for the projected group value (defaults to field) — this becomes the category column

ChartAggregateFunction

Allowed Values

  • count
  • sum
  • avg
  • min
  • max

ChartAnnotation

Properties

PropertyTypeRequiredDescription
typeEnum<'line' | 'region'>optional (default: "line")
axisEnum<'x' | 'y'>optional (default: "y")
valuenumber | string✅Start value
endValuenumber | stringoptionalEnd value for regions
colorstringoptional
labelstring | Record<string, string>optionalDisplay label — the default-language string, or an inline locale map ({ en, "zh-CN" }) resolved at render time
styleEnum<'solid' | 'dashed' | 'dotted'>optional (default: "dashed")

ChartAxis

Properties

PropertyTypeRequiredDescription
fieldstring✅Data field key
titlestring | Record<string, string>optionalAxis display title
formatstringoptionalValue format string (e.g., "$0,0.00")
minnumberoptionalMinimum value
maxnumberoptionalMaximum value
stepSizenumberoptionalStep size for ticks
showGridLinesbooleanoptional (default: true)
positionEnum<'left' | 'right' | 'top' | 'bottom'>optionalAxis position
logarithmicbooleanoptional (default: false)

ChartConfig

Properties

PropertyTypeRequiredDescription
typeEnum<'bar' | 'horizontal-bar' | 'column' | 'line' | 'area' | 'pie' | 'donut' | 'funnel' | 'scatter' | 'treemap' | 'sankey' | 'combo' | 'gauge' | 'solid-gauge' | … +6 more>✅
titlestring | Record<string, string>optionalChart title
subtitlestring | Record<string, string>optionalChart subtitle
descriptionstring | Record<string, string>optionalAccessibility description — announced to screen readers as the chart’s label
xAxis{ field: string; title?: string | Record<string, string>; format?: string; min?: number; … }optionalX-Axis configuration. Structure, not appearance — authorable where the chart has inline data; refused by name on a dataset-bound dashboard widget, where the dataset decides it (ADR-0021).
yAxis{ field: string; title?: string | Record<string, string>; format?: string; min?: number; … }[]optionalY-Axis configuration (support dual axis). Structure, not appearance — authorable where the chart has inline data; refused by name on a dataset-bound dashboard widget, where the dataset decides it (ADR-0021).
series{ name: string; label?: string | Record<string, string>; type?: Enum<'bar' | 'horizontal-bar' | 'column' | 'line' | 'area' | 'pie' | 'donut' | …>; color?: string; … }[]optionalDefined series configuration. Structure, not appearance — authorable where the chart has inline data; refused by name on a dataset-bound dashboard widget, where the dataset decides it (ADR-0021).
colorsstring[] | Record<string, string>optionalColor palette (string[]) or value→color map ({ value: color })
heightnumberoptionalFixed plot height in pixels (overrides the container default)
showLegendbooleanoptional (default: true)Display legend
showDataLabelsbooleanoptional (default: false)Display data labels
annotations{ type?: Enum<'line' | 'region'>; axis?: Enum<'x' | 'y'>; value: number | string; endValue?: number | string; … }[]optionalReference lines/bands drawn over the plot: { type: "line" | "region", axis: "x" | "y", value, endValue?, color?, label?, style? }
interaction{ tooltips?: boolean; brush?: boolean }optionalInteraction toggles: { tooltips?, brush? }
arianeveroptional[REMOVED] ChartConfig.aria — authored as dashboard.widgets[].chartConfig.aria, report.chart.aria and report.blocks[].chart.aria — was removed in @objectstack/spec 17 (ADR-0049 D2). No chart renderer ever applied it: the chart implementation declares no aria prop, the presentation lowering names it nowhere, and the react <ObjectChart> block never published it, so ARIA attributes declared here parsed and then silently did not reach the DOM. Delete the key. The accessible name that IS applied on this same chart config is its sibling description, which the chart renderer lowers onto the chart graphic as role="img" plus aria-label. The shared AriaProps shape is NOT gone — ariaLabel / ariaDescribedBy / role stay live in the aria block on page.aria, page.components[].aria and the list view aria. Run os migrate meta --from 17 to list the mechanical edits for existing sources; --write applies the ones it can prove, and you apply the rest by hand.

Allowed Values: ChartConfig.type

  • bar
  • horizontal-bar
  • column
  • line
  • area
  • pie
  • donut
  • funnel
  • scatter
  • treemap
  • sankey
  • combo
  • gauge
  • solid-gauge
  • metric
  • kpi
  • bullet
  • radar
  • table
  • pivot

Nested Shape: ChartConfig.xAxis

PropertyTypeRequiredDescription
fieldstring✅Data field key
titlestring | Record<string, string>optionalAxis display title
formatstringoptionalValue format string (e.g., "$0,0.00")
minnumberoptionalMinimum value
maxnumberoptionalMaximum value
stepSizenumberoptionalStep size for ticks
showGridLinesbooleanoptional (default: true)
positionEnum<'left' | 'right' | 'top' | 'bottom'>optionalAxis position
logarithmicbooleanoptional (default: false)

Nested Shape: ChartConfig.yAxis[number]

PropertyTypeRequiredDescription
fieldstring✅Data field key
titlestring | Record<string, string>optionalAxis display title
formatstringoptionalValue format string (e.g., "$0,0.00")
minnumberoptionalMinimum value
maxnumberoptionalMaximum value
stepSizenumberoptionalStep size for ticks
showGridLinesbooleanoptional (default: true)
positionEnum<'left' | 'right' | 'top' | 'bottom'>optionalAxis position
logarithmicbooleanoptional (default: false)

Nested Shape: ChartConfig.series[number]

PropertyTypeRequiredDescription
namestring✅Field name or series identifier
labelstring | Record<string, string>optionalSeries display label
typeEnum<'bar' | 'horizontal-bar' | 'column' | 'line' | 'area' | 'pie' | 'donut' | …>optionalOverride chart type for this series
colorstringoptionalSeries color (hex/rgb/token)
stackstringoptionalStack identifier to group series
yAxisEnum<'left' | 'right'>optional (default: "left")Bind to specific Y-Axis
variantEnum<'primary' | 'comparison'>optional (default: "primary")Series visual role
dashArraystringoptionalSVG stroke-dasharray override
opacitynumberoptionalSeries opacity override

Nested Shape: ChartConfig.annotations[number]

PropertyTypeRequiredDescription
typeEnum<'line' | 'region'>optional (default: "line")
axisEnum<'x' | 'y'>optional (default: "y")
valuenumber | string✅Start value
endValuenumber | stringoptionalEnd value for regions
colorstringoptional
labelstring | Record<string, string>optionalDisplay label — the default-language string, or an inline locale map ({ en, "zh-CN" }) resolved at render time
styleEnum<'solid' | 'dashed' | 'dotted'>optional (default: "dashed")

Nested Shape: ChartConfig.interaction

PropertyTypeRequiredDescription
tooltipsbooleanoptional (default: true)Show the hover tooltip
brushbooleanoptional (default: false)Show the range selector under the plot

ChartDrillDown

Properties

PropertyTypeRequiredDescription
enabledbooleanoptionalTurn the segment drill on/off; the block being present already means on, so this is only needed to force it off
filterRecord<string, any>optionalFilter for the drilled list; values support ${event.*}. Omit to derive it from the clicked category
titlestringoptionalDrill drawer/dialog heading; supports ${event.*} interpolation
targetEnum<'drawer' | 'dialog' | 'navigate'>optionalWhere the drilled list opens: 'drawer' (default, side sheet), 'dialog' (centered modal), or 'navigate' (skip the in-place view and open the object's full list page; needs host drill navigation, else falls back to 'drawer')
columnsstring[]optionalField names to show as columns in the drilled list (default: the table's own columns)
maxRowsintegeroptionalRows per page in the drilled list

ChartGroupBy

Union Options

This schema accepts one of the following structures:

Option 1

Field to group by

Type: string

Option 2

Properties

PropertyTypeRequiredDescription
fieldstring✅Field to group by
dateGranularityEnum<'day' | 'week' | 'month' | 'quarter' | 'year'>optionalBucket date values into uniform periods
aliasstringoptionalAlias for the projected group value (defaults to field) — this becomes the category column

ChartInteraction

Properties

PropertyTypeRequiredDescription
tooltipsbooleanoptional (default: true)Show the hover tooltip
brushbooleanoptional (default: false)Show the range selector under the plot

ChartSeries

Properties

PropertyTypeRequiredDescription
namestring✅Field name or series identifier
labelstring | Record<string, string>optionalSeries display label
typeEnum<'bar' | 'horizontal-bar' | 'column' | 'line' | 'area' | 'pie' | 'donut' | 'funnel' | 'scatter' | 'treemap' | 'sankey' | 'combo' | 'gauge' | 'solid-gauge' | … +6 more>optionalOverride chart type for this series
colorstringoptionalSeries color (hex/rgb/token)
stackstringoptionalStack identifier to group series
yAxisEnum<'left' | 'right'>optional (default: "left")Bind to specific Y-Axis
variantEnum<'primary' | 'comparison'>optional (default: "primary")Series visual role
dashArraystringoptionalSVG stroke-dasharray override
opacitynumberoptionalSeries opacity override

Allowed Values: ChartSeries.type

  • bar
  • horizontal-bar
  • column
  • line
  • area
  • pie
  • donut
  • funnel
  • scatter
  • treemap
  • sankey
  • combo
  • gauge
  • solid-gauge
  • metric
  • kpi
  • bullet
  • radar
  • table
  • pivot

ChartType

Allowed Values

  • bar
  • horizontal-bar
  • column
  • line
  • area
  • pie
  • donut
  • funnel
  • scatter
  • treemap
  • sankey
  • combo
  • gauge
  • solid-gauge
  • metric
  • kpi
  • bullet
  • radar
  • table
  • pivot

View

View protocol schemas — the view metadata type and its three persisted body spellings.

Component

Component schemas of the ObjectStack UI Protocol: ActionButtonProps and 43 more — each property with its type, default and a TypeScript example.

On this page

TypeScript UsageChartAggregatePropertiesNested Shape: ChartAggregate.groupByChartAggregateFunctionAllowed ValuesChartAnnotationPropertiesChartAxisPropertiesChartConfigPropertiesAllowed Values: ChartConfig.typeNested Shape: ChartConfig.xAxisNested Shape: ChartConfig.yAxis[number]Nested Shape: ChartConfig.series[number]Nested Shape: ChartConfig.annotations[number]Nested Shape: ChartConfig.interactionChartDrillDownPropertiesChartGroupByUnion OptionsOption 1Option 2PropertiesChartInteractionPropertiesChartSeriesPropertiesAllowed Values: ChartSeries.typeChartTypeAllowed Values