ObjectStackReport
Report protocol schemas
Report Type Enum
Source: packages/spec/src/ui/report.zod.ts
TypeScript Usage
import { JoinedReportBlock, Report, ReportChart, ReportColumn, ReportGrouping, ReportType } from '@objectstack/spec/ui';
import type { JoinedReportBlock, Report, ReportChart, ReportColumn, ReportGrouping, ReportType } from '@objectstack/spec/ui';
// Validate data
const result = JoinedReportBlock.parse(data);JoinedReportBlock
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| name | string | ✅ | Snake case identifier (lowercase with underscores only) |
| label | string | optional | Display label (plain string; i18n keys are auto-generated by the framework) |
| description | string | optional | Display label (plain string; i18n keys are auto-generated by the framework) |
| type | Enum<'tabular' | 'summary' | 'matrix'> | ✅ | |
| objectName | string | optional | |
| columns | Object[] | ✅ | |
| groupingsDown | Object[] | optional | |
| groupingsAcross | Object[] | optional | |
| filter | [__schema0](./__schema0) | optional | |
| chart | Object | optional |
Report
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| name | string | ✅ | Report unique name |
| label | string | ✅ | Report label |
| description | string | optional | Display label (plain string; i18n keys are auto-generated by the framework) |
| objectName | string | ✅ | Primary object |
| type | Enum<'tabular' | 'summary' | 'matrix' | 'joined'> | ✅ | Report format type |
| columns | Object[] | ✅ | Columns to display |
| groupingsDown | Object[] | optional | Row groupings |
| groupingsAcross | Object[] | optional | Column groupings (Matrix only) |
| filter | [__schema0](./__schema0) | optional | Filter criteria |
| chart | Object | optional | Embedded chart configuration |
| aria | Object | optional | ARIA accessibility attributes |
| performance | Object | optional | Performance optimization settings |
| blocks | Object[] | optional | Sub-reports for type=joined |
| protection | Object | 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 |
| _provenance | Enum<'package' | 'org' | 'env-forced'> | optional | Origin of the item (package |
| _packageId | string | optional | Owning package machine id. |
| _packageVersion | string | optional | Owning package version. |
| _lockDocsUrl | string | optional | Optional documentation link surfaced next to _lockReason. |
ReportChart
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| type | Enum<'bar' | 'horizontal-bar' | 'column' | 'grouped-bar' | 'stacked-bar' | 'bi-polar-bar' | 'line' | 'area' | 'stacked-area' | 'step-line' | 'spline' | 'pie' | 'donut' | 'funnel' | 'pyramid' | 'scatter' | 'bubble' | 'treemap' | 'sankey' | 'gauge' | 'solid-gauge' | 'metric' | 'kpi' | 'bullet' | 'radar' | 'table' | 'pivot'> | ✅ | |
| title | string | optional | Chart title |
| subtitle | string | optional | Chart subtitle |
| description | string | optional | Accessibility description |
| xAxis | string | ✅ | Grouping field for X-Axis |
| yAxis | string | ✅ | Summary field for Y-Axis |
| series | Object[] | optional | Defined series configuration |
| colors | string[] | optional | Color palette |
| height | number | optional | Fixed height in pixels |
| showLegend | boolean | ✅ | Display legend |
| showDataLabels | boolean | ✅ | Display data labels |
| annotations | Object[] | optional | |
| interaction | Object | optional | |
| aria | Object | optional | ARIA accessibility attributes |
| groupBy | string | optional | Additional grouping field |
ReportColumn
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| field | string | ✅ | Field name |
| label | string | optional | Override label |
| aggregate | Enum<'sum' | 'avg' | 'max' | 'min' | 'count' | 'unique'> | optional | Aggregation function |
| responsive | Object | optional | Responsive visibility for this column |
ReportGrouping
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| field | string | ✅ | Field to group by |
| sortOrder | Enum<'asc' | 'desc'> | ✅ | |
| dateGranularity | Enum<'day' | 'week' | 'month' | 'quarter' | 'year'> | optional | For date fields |
ReportType
Allowed Values
tabularsummarymatrixjoined