Report schema — UI Protocol property reference

Report schemas of the ObjectStack UI Protocol: JoinedReportBlock, Report and 3 more — each property with its type, default and a TypeScript example.

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

TypeScript Usage

import { JoinedReportBlockSchema, ReportSchema, ReportChartSchema, ReportSortSchema, ReportType } from '@objectstack/spec/ui';
import type { JoinedReportBlock, Report, ReportChart, ReportSort, ReportType } from '@objectstack/spec/ui';

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

JoinedReportBlock

Properties

Property	Type	Required	Description
name	`string`	✅	Snake case identifier (lowercase with underscores only)
label	`string \| Record<string, string>`	optional	Display label — the default-language string, or an inline locale map (`{ en, "zh-CN" }`) resolved at render time
description	`string \| Record<string, string>`	optional	Display label — the default-language string, or an inline locale map (`{ en, "zh-CN" }`) resolved at render time
type	`Enum<'tabular' \| 'summary' \| 'matrix'>`	optional (default: `"tabular"`)
dataset	`string`	optional	Dataset name to bind (ADR-0021); a joined report refuses a block without one
rows	`string[]`	optional	Dimension names down (dataset-bound)
columns	`string[]`	optional	Dimension names across (matrix, dataset-bound)
values	`string[]`	optional	Measure names to show (dataset-bound)
runtimeFilter	`any`	optional	Render-time scope filter (dataset-bound)
order	`{ by: string; direction?: Enum<'asc' \| 'desc'> }[]`	optional	Result ordering, most significant key first

Nested Shape: `JoinedReportBlock.order[number]`

Property	Type	Required	Description
by	`string`	✅	Dimension or measure name to order by (must be selected by this report)
direction	`Enum<'asc' \| 'desc'>`	optional (default: `"asc"`)	Sort direction (default ascending)

Report

Properties

Property	Type	Required	Description
name	`string`	✅	Report unique name
label	`string \| Record<string, string>`	✅	Report label
description	`string \| Record<string, string>`	optional	Display label — the default-language string, or an inline locale map (`{ en, "zh-CN" }`) resolved at render time
type	`Enum<'tabular' \| 'summary' \| 'matrix' \| 'joined'>`	optional (default: `"tabular"`)	Report format type
dataset	`string`	optional	Dataset name to bind (ADR-0021)
rows	`string[]`	optional	Dimension names down
columns	`string[]`	optional	Dimension names across (matrix)
values	`string[]`	optional	Measure names to show
runtimeFilter	`any`	optional	Render-time scope filter
order	`{ by: string; direction?: Enum<'asc' \| 'desc'> }[]`	optional	Result ordering, most significant key first
drilldown	`boolean`	optional (default: `true`)	Click-through to underlying records
chart	`{ type: Enum<'bar' \| 'horizontal-bar' \| 'column' \| 'line' \| 'area' \| 'pie' \| 'donut' \| …>; title?: string \| Record<string, string>; subtitle?: string \| Record<string, string>; description?: string \| Record<string, string>; … }`	optional	Embedded chart configuration (refused on a joined report, which draws tables only)
blocks	`{ name: string; label?: string \| Record<string, string>; description?: string \| Record<string, string>; type?: Enum<'tabular' \| 'summary' \| 'matrix'>; … }[]`	optional	Sub-reports for type=joined
protection	`{ lock: Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>; reason: string; docsUrl?: string }`	optional	Package author protection block — lock policy for this report.
_lock	`Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>`	optional	Item-level lock — controls overlay & delete (ADR-0010).
_lockReason	`string`	optional	Human-readable reason shown when a write is refused by _lock.
_lockSource	`Enum<'artifact' \| 'package' \| 'env-forced'>`	optional	Layer that set _lock (artifact \| package \| env-forced).
_provenance	`Enum<'package' \| 'org' \| 'env-forced'>`	optional	Origin of the item (package \| org \| env-forced).
_packageId	`string`	optional	Owning package machine id.
_packageVersion	`string`	optional	Owning package version.
_lockDocsUrl	`string`	optional	Optional documentation link surfaced next to _lockReason.

Nested Shape: `Report.order[number]`

Property	Type	Required	Description
by	`string`	✅	Dimension or measure name to order by (must be selected by this report)
direction	`Enum<'asc' \| 'desc'>`	optional (default: `"asc"`)	Sort direction (default ascending)

Nested Shape: `Report.chart`

Property	Type	Required	Description
type	`Enum<'bar' \| 'horizontal-bar' \| 'column' \| 'line' \| 'area' \| 'pie' \| 'donut' \| …>`	✅
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	`string`	✅	Dataset dimension name for the X-axis (bound-dataset dimension, not a raw field)
yAxis	`string`	✅	Dataset measure name for the Y-axis (bound-dataset measure, not a raw field)
series	`{ name: string; label?: string \| Record<string, string>; type?: Enum<'bar' \| 'horizontal-bar' \| 'column' \| 'line' \| 'area' \| 'pie' \| 'donut' \| …>; color?: string; … }[]`	optional	Defined 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).
colors	`string[] \| Record<string, string>`	optional	Color palette (string[]) or value→color map (`{ value: color }`)
height	`number`	optional	Fixed plot height in pixels (overrides the container default)
showLegend	`boolean`	optional (default: `true`)	Display legend
showDataLabels	`boolean`	optional (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	`never`	optional	[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.

Nested Shape: `Report.blocks[number]`

Property	Type	Required	Description
name	`string`	✅	Snake case identifier (lowercase with underscores only)
label	`string \| Record<string, string>`	optional	Display label — the default-language string, or an inline locale map (`{ en, "zh-CN" }`) resolved at render time
description	`string \| Record<string, string>`	optional	Display label — the default-language string, or an inline locale map (`{ en, "zh-CN" }`) resolved at render time
type	`Enum<'tabular' \| 'summary' \| 'matrix'>`	optional (default: `"tabular"`)
dataset	`string`	optional	Dataset name to bind (ADR-0021); a joined report refuses a block without one
rows	`string[]`	optional	Dimension names down (dataset-bound)
columns	`string[]`	optional	Dimension names across (matrix, dataset-bound)
values	`string[]`	optional	Measure names to show (dataset-bound)
runtimeFilter	`any`	optional	Render-time scope filter (dataset-bound)
order	`{ by: string; direction?: Enum<'asc' \| 'desc'> }[]`	optional	Result ordering, most significant key first

Nested Shape: `Report.protection`

Property	Type	Required	Description
lock	`Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>`	✅	Lock policy — none \| no-overlay \| no-delete \| full.
reason	`string`	✅	User-visible reason shown when the lock blocks an action.
docsUrl	`string`	optional	Optional URL the Studio banner links to for more context.

ReportChart

Properties

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	`string`	✅	Dataset dimension name for the X-axis (bound-dataset dimension, not a raw field)
yAxis	`string`	✅	Dataset measure name for the Y-axis (bound-dataset measure, not a raw field)
series	`{ name: string; label?: string \| Record<string, string>; type?: Enum<'bar' \| 'horizontal-bar' \| 'column' \| 'line' \| 'area' \| 'pie' \| 'donut' \| …>; color?: string; … }[]`	optional	Defined 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).
colors	`string[] \| Record<string, string>`	optional	Color palette (string[]) or value→color map (`{ value: color }`)
height	`number`	optional	Fixed plot height in pixels (overrides the container default)
showLegend	`boolean`	optional (default: `true`)	Display legend
showDataLabels	`boolean`	optional (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	`never`	optional	[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: `ReportChart.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: `ReportChart.series[number]`

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	`string`	optional	Series color (hex/rgb/token)
stack	`string`	optional	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	`string`	optional	SVG stroke-dasharray override
opacity	`number`	optional	Series opacity override

Nested Shape: `ReportChart.annotations[number]`

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 \| string`	optional	End value for regions
color	`string`	optional
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"`)

Nested Shape: `ReportChart.interaction`

Property	Type	Required	Description
tooltips	`boolean`	optional (default: `true`)	Show the hover tooltip
brush	`boolean`	optional (default: `false`)	Show the range selector under the plot

ReportSort

Properties

Property	Type	Required	Description
by	`string`	✅	Dimension or measure name to order by (must be selected by this report)
direction	`Enum<'asc' \| 'desc'>`	optional (default: `"asc"`)	Sort direction (default ascending)

ReportType

Allowed Values

tabular
summary
matrix
joined

Report schema — UI Protocol property reference

On this page