---
title: Report
description: Report protocol schemas
---

{/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}

Report Type Enum

<Callout type="info">
**Source:** `packages/spec/src/ui/report.zod.ts`
</Callout>

## TypeScript Usage

```typescript
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'>` | ✅ |  |
| **chart** | `Object` | optional |  |
| **dataset** | `string` | optional | Dataset name to bind (ADR-0021) |
| **rows** | `string[]` | optional | Dimension names down (dataset-bound) |
| **values** | `string[]` | optional | Measure names to show (dataset-bound) |
| **runtimeFilter** | `[__schema0](./__schema0)` | optional | Render-time scope filter (dataset-bound) |


---

## 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) |
| **type** | `Enum<'tabular' \| 'summary' \| 'matrix' \| 'joined'>` | ✅ | Report format type |
| **dataset** | `string` | optional | Dataset name to bind (ADR-0021) |
| **rows** | `string[]` | optional | Dimension names down |
| **values** | `string[]` | optional | Measure names to show |
| **runtimeFilter** | `[__schema0](./__schema0)` | optional | Render-time scope filter |
| **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 | 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. |


---

## ReportChart

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **type** | `Enum<'bar' \| 'horizontal-bar' \| 'column' \| 'line' \| 'area' \| 'pie' \| 'donut' \| 'funnel' \| 'scatter' \| '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

* `tabular`
* `summary`
* `matrix`
* `joined`


---

