Report

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"`)
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
dataset	`string`	optional	Dataset name to bind (ADR-0021)
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.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
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	`{ ariaLabel?: string \| Record<string, string>; ariaDescribedBy?: string; role?: string }`	optional	ARIA accessibility attributes

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
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
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	`{ ariaLabel?: string \| Record<string, string>; ariaDescribedBy?: string; role?: string }`	optional	ARIA accessibility attributes

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"`)
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
dataset	`string`	optional	Dataset name to bind (ADR-0021)
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
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	`{ ariaLabel?: string \| Record<string, string>; ariaDescribedBy?: string; role?: string }`	optional	ARIA accessibility attributes

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

Nested Shape: `ReportChart.aria`

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	`string`	optional	ID of element providing additional description (WAI-ARIA aria-describedby)
role	`string`	optional	WAI-ARIA role attribute (e.g., "dialog", "navigation", "alert")

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

On this page