---
title: View
description: View protocol schemas
---

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

HTTP Method Enum & HTTP Request Schema

Migrated to shared/http.zod.ts. Re-exported here for backward compatibility.

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

## TypeScript Usage

```typescript
import { AddRecordConfig, AppearanceConfig, CalendarConfig, ColumnSummary, GalleryConfig, GanttConfig, GroupingConfig, GroupingField, KanbanConfig, ListChartConfig, ListColumn, NavigationConfig, NavigationMode, PaginationConfig, RowColorConfig, RowHeight, SelectionConfig, TimelineConfig, UserActionsConfig, ViewData, ViewFilterRule, ViewItemName, ViewKind, ViewScope, ViewSharing, ViewTab, VisualizationType } from '@objectstack/spec/ui';
import type { AddRecordConfig, AppearanceConfig, CalendarConfig, ColumnSummary, GalleryConfig, GanttConfig, GroupingConfig, GroupingField, KanbanConfig, ListChartConfig, ListColumn, NavigationConfig, NavigationMode, PaginationConfig, RowColorConfig, RowHeight, SelectionConfig, TimelineConfig, UserActionsConfig, ViewData, ViewFilterRule, ViewItemName, ViewKind, ViewScope, ViewSharing, ViewTab, VisualizationType } from '@objectstack/spec/ui';

// Validate data
const result = AddRecordConfig.parse(data);
```

---

## AddRecordConfig

Add record entry point configuration

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **enabled** | `boolean` | ✅ | Show the add record entry point |
| **position** | `Enum<'top' \| 'bottom' \| 'both'>` | ✅ | Position of the add record button |
| **mode** | `Enum<'inline' \| 'form' \| 'modal'>` | ✅ | How to add a new record |
| **formView** | `string` | optional | Named form view to use when mode is "form" or "modal" |


---

## AppearanceConfig

Appearance and visualization configuration

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **showDescription** | `boolean` | ✅ | Show the view description text |
| **allowedVisualizations** | `Enum<'grid' \| 'kanban' \| 'gallery' \| 'calendar' \| 'timeline' \| 'gantt' \| 'map'>[]` | optional | Whitelist of visualization types users can switch between (e.g. ["grid", "gallery", "kanban"]) |


---

## CalendarConfig

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **startDateField** | `string` | ✅ |  |
| **endDateField** | `string` | optional |  |
| **titleField** | `string` | ✅ |  |
| **colorField** | `string` | optional |  |


---

## ColumnSummary

Aggregation function for column footer summary

### Allowed Values

* `none`
* `count`
* `count_empty`
* `count_filled`
* `count_unique`
* `percent_empty`
* `percent_filled`
* `sum`
* `avg`
* `min`
* `max`


---

## GalleryConfig

Gallery/card view configuration

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **coverField** | `string` | optional | Attachment/image field to display as card cover |
| **coverFit** | `Enum<'cover' \| 'contain'>` | ✅ | Image fit mode for card cover |
| **cardSize** | `Enum<'small' \| 'medium' \| 'large'>` | ✅ | Card size in gallery view |
| **titleField** | `string` | optional | Field to display as card title |
| **visibleFields** | `string[]` | optional | Fields to display on card body |


---

## GanttConfig

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **startDateField** | `string` | ✅ |  |
| **endDateField** | `string` | ✅ |  |
| **titleField** | `string` | ✅ |  |
| **progressField** | `string` | optional |  |
| **dependenciesField** | `string` | optional |  |


---

## GroupingConfig

Record grouping configuration

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **fields** | `Object[]` | ✅ | Fields to group by (supports up to 3 levels) |


---

## GroupingField

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **field** | `string` | ✅ | Field name to group by |
| **order** | `Enum<'asc' \| 'desc'>` | ✅ | Group sort order |
| **collapsed** | `boolean` | ✅ | Collapse groups by default |


---

## KanbanConfig

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **groupByField** | `string` | ✅ | Field to group columns by (usually status/select) |
| **summarizeField** | `string` | optional | Field to sum at top of column (e.g. amount) |
| **columns** | `string[]` | ✅ | Fields to show on cards |


---

## ListChartConfig

List chart view configuration

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **chartType** | `Enum<'bar' \| 'line' \| 'pie' \| 'area' \| 'scatter'>` | ✅ | Chart visualisation type |
| **dataset** | `string` | ✅ | Dataset name to bind (ADR-0021) |
| **dimensions** | `string[]` | optional | Dimension names — X/group/split |
| **values** | `string[]` | ✅ | Measure names — Y (at least one) |


---

## ListColumn

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **field** | `string` | ✅ | Field name (snake_case) |
| **label** | `string` | optional | Display label override |
| **width** | `number` | optional | Column width in pixels |
| **align** | `Enum<'left' \| 'center' \| 'right'>` | optional | Text alignment |
| **hidden** | `boolean` | optional | Hide column by default |
| **sortable** | `boolean` | optional | Allow sorting by this column |
| **resizable** | `boolean` | optional | Allow resizing this column |
| **wrap** | `boolean` | optional | Allow text wrapping |
| **type** | `string` | optional | Renderer type override (e.g., "currency", "date") |
| **pinned** | `Enum<'left' \| 'right'>` | optional | Pin/freeze column to left or right side |
| **summary** | `Enum<'none' \| 'count' \| 'count_empty' \| 'count_filled' \| 'count_unique' \| 'percent_empty' \| 'percent_filled' \| 'sum' \| 'avg' \| 'min' \| 'max'>` | optional | Footer aggregation function for this column |
| **link** | `boolean` | optional | Functions as the primary navigation link (triggers View navigation) |
| **action** | `string` | optional | Registered Action ID to execute when clicked |


---

## NavigationConfig

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **mode** | `Enum<'page' \| 'drawer' \| 'modal' \| 'split' \| 'popover' \| 'new_window' \| 'none'>` | ✅ |  |
| **view** | `string` | optional | Name of the form view to use for details (e.g. "summary_view", "edit_form") |
| **preventNavigation** | `boolean` | ✅ | Disable standard navigation entirely |
| **openNewTab** | `boolean` | ✅ | Force open in new tab (applies to page mode) |
| **width** | `string \| number` | optional | Width of the drawer/modal (e.g. "600px", "50%") |


---

## NavigationMode

### Allowed Values

* `page`
* `drawer`
* `modal`
* `split`
* `popover`
* `new_window`
* `none`


---

## PaginationConfig

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **pageSize** | `integer` | ✅ | Number of records per page |
| **pageSizeOptions** | `integer[]` | optional | Available page size options |


---

## RowColorConfig

Row color configuration based on field values

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **field** | `string` | ✅ | Field to derive color from (typically a select/status field) |
| **colors** | `Record<string, string>` | optional | Map of field value to color (hex/token) |


---

## RowHeight

Row height / density setting for list view

### Allowed Values

* `compact`
* `short`
* `medium`
* `tall`
* `extra_tall`


---

## SelectionConfig

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **type** | `Enum<'none' \| 'single' \| 'multiple'>` | ✅ | Selection mode |


---

## TimelineConfig

Timeline view configuration

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **startDateField** | `string` | ✅ | Field for timeline item start date |
| **endDateField** | `string` | optional | Field for timeline item end date |
| **titleField** | `string` | ✅ | Field to display as timeline item title |
| **groupByField** | `string` | optional | Field to group timeline rows |
| **colorField** | `string` | optional | Field to determine item color |
| **scale** | `Enum<'hour' \| 'day' \| 'week' \| 'month' \| 'quarter' \| 'year'>` | ✅ | Default timeline scale |


---

## UserActionsConfig

User action toggles for the view toolbar

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **sort** | `boolean` | ✅ | Allow users to sort records |
| **search** | `boolean` | ✅ | Allow users to search records |
| **filter** | `boolean` | ✅ | Allow users to filter records |
| **rowHeight** | `boolean` | ✅ | Allow users to toggle row height/density |
| **addRecordForm** | `boolean` | ✅ | Add records through a form instead of inline |
| **buttons** | `string[]` | optional | Custom action button IDs to show in the toolbar |


---

## ViewData

### Union Options

This schema accepts one of the following structures:

#### Option 1

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **provider** | `string` | ✅ |  |
| **object** | `string` | ✅ | Target object name |

---

#### Option 2

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **provider** | `string` | ✅ |  |
| **read** | `Object` | optional | Configuration for fetching data |
| **write** | `Object` | optional | Configuration for submitting data (for forms/editable tables) |

---

#### Option 3

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **provider** | `string` | ✅ |  |
| **items** | `any[]` | ✅ | Static data array |

---

#### Option 4

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **provider** | `string` | ✅ |  |
| **schemaId** | `string` | ✅ | Schema identifier — typically the metadata type name |
| **schema** | `Record<string, any>` | optional | Inline JSON Schema (Draft 2020-12). Optional when schemaId is resolvable. |

---


---

## ViewFilterRule

View filter rule

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **field** | `string` | ✅ | Field name to filter on |
| **operator** | `string` | ✅ | Filter operator (e.g. equals, not_equals, contains, this_quarter) |
| **value** | `string \| number \| boolean \| null \| string \| number[]` | optional | Filter value |


---


---

## ViewKind

Whether `config` is a ListView (list family) or a FormView.

### Allowed Values

* `list`
* `form`


---

## ViewScope

View identity layer: package | shared | personal.

### Allowed Values

* `package`
* `shared`
* `personal`


---

## ViewSharing

View sharing and access configuration

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **type** | `Enum<'personal' \| 'collaborative'>` | ✅ | View ownership type |
| **lockedBy** | `string` | optional | User who locked the view configuration |


---

## ViewTab

Tab configuration for multi-tab view interface

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **name** | `string` | ✅ | Tab identifier (snake_case) |
| **label** | `string` | optional | Display label |
| **icon** | `string` | optional | Tab icon name |
| **view** | `string` | optional | Referenced list view name from listViews |
| **filter** | `Object[]` | optional | Tab-specific filter criteria |
| **order** | `integer` | optional | Tab display order |
| **pinned** | `boolean` | ✅ | Pin tab (cannot be removed by users) |
| **isDefault** | `boolean` | ✅ | Set as the default active tab |
| **visible** | `boolean` | ✅ | Tab visibility |


---

## VisualizationType

Visualization type that users can switch to

### Allowed Values

* `grid`
* `kanban`
* `gallery`
* `calendar`
* `timeline`
* `gantt`
* `map`


---

