Chart Chart protocol schemas
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
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); Inline aggregation for an object-bound chart
Property Type Required Description field stringoptional Field to aggregate — required for sum/avg/min/max, optional for count function Enum<'count' | 'sum' | 'avg' | 'min' | 'max'>✅ Aggregation function groupBy string | { field: string; dateGranularity?: Enum<'day' | 'week' | 'month' | 'quarter' | 'year'>; alias?: string }✅ Field the rows are grouped by — the chart category axis
Property Type Required Description field string✅ Field to group by dateGranularity Enum<'day' | 'week' | 'month' | 'quarter' | 'year'>optional Bucket date values into uniform periods alias stringoptional Alias for the projected group value (defaults to field) — this becomes the category column
Property Type Required Description type Enum<'line' | 'region'>optional (default: "line") axis Enum<'x' | 'y'>optional (default: "y") value number | string✅ Start value endValue number | stringoptional End value for regions color stringoptional label string | Record<string, string>optional Display label — the default-language string, or an inline locale map ({ en, "zh-CN" }) resolved at render time style Enum<'solid' | 'dashed' | 'dotted'>optional (default: "dashed")
Property Type Required Description field string✅ Data field key title string | Record<string, string>optional Axis display title format stringoptional Value format string (e.g., "$0,0.00") min numberoptional Minimum value max numberoptional Maximum value stepSize numberoptional Step size for ticks showGridLines booleanoptional (default: true) position Enum<'left' | 'right' | 'top' | 'bottom'>optional Axis position logarithmic booleanoptional (default: false)
Property Type Required Description type Enum<'bar' | 'horizontal-bar' | 'column' | 'line' | 'area' | 'pie' | 'donut' | 'funnel' | 'scatter' | 'treemap' | 'sankey' | 'combo' | 'gauge' | 'solid-gauge' | … +6 more>✅ title string | Record<string, string>optional Chart title subtitle string | Record<string, string>optional Chart subtitle description string | Record<string, string>optional Accessibility description — announced to screen readers as the chart’s label xAxis { field: string; title?: string | Record<string, string>; format?: string; min?: number; … }optional X-Axis configuration yAxis { field: string; title?: string | Record<string, string>; format?: string; min?: number; … }[]optional Y-Axis configuration (support dual axis) series { name: string; label?: string | Record<string, string>; type?: Enum<'bar' | 'horizontal-bar' | 'column' | 'line' | 'area' | 'pie' | 'donut' | …>; color?: string; … }[]optional Defined series configuration colors string[] | Record<string, string>optional Color palette (string[]) or value→color map ({ value: color }) height numberoptional Fixed plot height in pixels (overrides the container default) showLegend booleanoptional (default: true) Display legend showDataLabels booleanoptional (default: false) Display data labels annotations { type: Enum<'line' | 'region'>; axis: Enum<'x' | 'y'>; value: number | string; endValue?: number | string; … }[]optional Reference lines/bands drawn over the plot: { type: "line" | "region", axis: "x" | "y", value, endValue?, color?, label?, style? } interaction { tooltips: boolean; brush: boolean }optional Interaction toggles: { tooltips?, brush? } aria { ariaLabel?: string | Record<string, string>; ariaDescribedBy?: string; role?: string }optional ARIA accessibility attributes
barhorizontal-barcolumnlineareapiedonutfunnelscattertreemapsankeycombogaugesolid-gaugemetrickpibulletradartablepivot
Property Type Required Description field string✅ Data field key title string | Record<string, string>optional Axis display title format stringoptional Value format string (e.g., "$0,0.00") min numberoptional Minimum value max numberoptional Maximum value stepSize numberoptional Step size for ticks showGridLines booleanoptional (default: true) position Enum<'left' | 'right' | 'top' | 'bottom'>optional Axis position logarithmic booleanoptional (default: false)
Property Type Required Description field string✅ Data field key title string | Record<string, string>optional Axis display title format stringoptional Value format string (e.g., "$0,0.00") min numberoptional Minimum value max numberoptional Maximum value stepSize numberoptional Step size for ticks showGridLines booleanoptional (default: true) position Enum<'left' | 'right' | 'top' | 'bottom'>optional Axis position logarithmic booleanoptional (default: false)
Property Type Required Description name string✅ Field name or series identifier label string | Record<string, string>optional Series display label type Enum<'bar' | 'horizontal-bar' | 'column' | 'line' | 'area' | 'pie' | 'donut' | …>optional Override chart type for this series color stringoptional Series color (hex/rgb/token) stack stringoptional Stack identifier to group series yAxis Enum<'left' | 'right'>optional (default: "left") Bind to specific Y-Axis variant Enum<'primary' | 'comparison'>optional (default: "primary") Series visual role dashArray stringoptional SVG stroke-dasharray override opacity numberoptional Series opacity override
Property Type Required Description type Enum<'line' | 'region'>optional (default: "line") axis Enum<'x' | 'y'>optional (default: "y") value number | string✅ Start value endValue number | stringoptional End value for regions color stringoptional label string | Record<string, string>optional Display label — the default-language string, or an inline locale map ({ en, "zh-CN" }) resolved at render time style Enum<'solid' | 'dashed' | 'dotted'>optional (default: "dashed")
Property Type Required Description tooltips booleanoptional (default: true) Show the hover tooltip brush booleanoptional (default: false) Show the range selector under the plot
Property Type Required Description ariaLabel string | Record<string, string>optional Accessible label for screen readers (WAI-ARIA aria-label). Plain string, or an inline locale map — no translation-bundle slot addresses this key, so a plain string is announced in the source language. ariaDescribedBy stringoptional ID of element providing additional description (WAI-ARIA aria-describedby) role stringoptional WAI-ARIA role attribute (e.g., "dialog", "navigation", "alert")
Property Type Required Description enabled booleanoptional Turn the segment drill on/off; the block being present already means on, so this is only needed to force it off filter Record<string, any>optional Filter for the drilled list; values support ${event.*}. Omit to derive it from the clicked category title stringoptional Drill drawer/dialog heading; supports ${event.*} interpolation target Enum<'drawer' | 'dialog' | 'navigate'>optional Where 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') columns string[]optional Field names to show as columns in the drilled list (default: the table's own columns) maxRows integeroptional Rows per page in the drilled list
This schema accepts one of the following structures:
Field to group by
Type: string
Property Type Required Description field string✅ Field to group by dateGranularity Enum<'day' | 'week' | 'month' | 'quarter' | 'year'>optional Bucket date values into uniform periods alias stringoptional Alias for the projected group value (defaults to field) — this becomes the category column
Property Type Required Description tooltips booleanoptional (default: true) Show the hover tooltip brush booleanoptional (default: false) Show the range selector under the plot
Property Type Required Description name string✅ Field name or series identifier label string | Record<string, string>optional Series display label type Enum<'bar' | 'horizontal-bar' | 'column' | 'line' | 'area' | 'pie' | 'donut' | 'funnel' | 'scatter' | 'treemap' | 'sankey' | 'combo' | 'gauge' | 'solid-gauge' | … +6 more>optional Override chart type for this series color stringoptional Series color (hex/rgb/token) stack stringoptional Stack identifier to group series yAxis Enum<'left' | 'right'>optional (default: "left") Bind to specific Y-Axis variant Enum<'primary' | 'comparison'>optional (default: "primary") Series visual role dashArray stringoptional SVG stroke-dasharray override opacity numberoptional Series opacity override
barhorizontal-barcolumnlineareapiedonutfunnelscattertreemapsankeycombogaugesolid-gaugemetrickpibulletradartablepivot
barhorizontal-barcolumnlineareapiedonutfunnelscattertreemapsankeycombogaugesolid-gaugemetrickpibulletradartablepivot
ObjectStack