View
View protocol schemas
HTTP Method Enum & HTTP Request Schema
Migrated to shared/http.zod.ts. Re-exported here for backward compatibility.
Source: packages/spec/src/ui/view.zod.ts
import { AddRecordConfig, AppearanceConfig, CalendarConfig, ColumnSummary, FormField, GalleryConfig, GanttConfig, GroupingConfig, GroupingField, KanbanConfig, ListColumn, ListView, NavigationConfig, NavigationMode, PaginationConfig, RowColorConfig, RowHeight, SelectionConfig, TimelineConfig, UserActionsConfig, ViewData, ViewFilterRule, ViewSharing, ViewTab, VisualizationType } from '@objectstack/spec/ui';
import type { AddRecordConfig, AppearanceConfig, CalendarConfig, ColumnSummary, FormField, GalleryConfig, GanttConfig, GroupingConfig, GroupingField, KanbanConfig, ListColumn, ListView, NavigationConfig, NavigationMode, PaginationConfig, RowColorConfig, RowHeight, SelectionConfig, TimelineConfig, UserActionsConfig, ViewData, ViewFilterRule, ViewSharing, ViewTab, VisualizationType } from '@objectstack/spec/ui';
// Validate data
const result = AddRecordConfig.parse(data);
Add record entry point configuration
| 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" |
Appearance and visualization configuration
| 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"]) |
| Property | Type | Required | Description |
|---|
| startDateField | string | ✅ | |
| endDateField | string | optional | |
| titleField | string | ✅ | |
| colorField | string | optional | |
Aggregation function for column footer summary
nonecountcount_emptycount_filledcount_uniquepercent_emptypercent_filledsumavgminmax
| Property | Type | Required | Description |
|---|
| field | string | ✅ | Field name (snake_case) |
| label | string | Object | optional | Display label override |
| placeholder | string | Object | optional | Placeholder text |
| helpText | string | Object | optional | Help/hint text |
| readonly | boolean | optional | Read-only override |
| required | boolean | optional | Required override |
| hidden | boolean | optional | Hidden override |
| colSpan | integer | optional | Column span in grid layout (1-4) |
| widget | string | optional | Custom widget/component name |
| dependsOn | string | optional | Parent field name for cascading |
| visibleOn | string | optional | Visibility condition expression |
Gallery/card view configuration
| 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 |
| Property | Type | Required | Description |
|---|
| startDateField | string | ✅ | |
| endDateField | string | ✅ | |
| titleField | string | ✅ | |
| progressField | string | optional | |
| dependenciesField | string | optional | |
Record grouping configuration
| Property | Type | Required | Description |
|---|
| fields | Object[] | ✅ | Fields to group by (supports up to 3 levels) |
| Property | Type | Required | Description |
|---|
| field | string | ✅ | Field name to group by |
| order | Enum<'asc' | 'desc'> | ✅ | Group sort order |
| collapsed | boolean | ✅ | Collapse groups by default |
| 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 |
| Property | Type | Required | Description |
|---|
| field | string | ✅ | Field name (snake_case) |
| label | string | Object | 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 |
| Property | Type | Required | Description |
|---|
| name | string | optional | Internal view name (lowercase snake_case) |
| label | string | Object | optional | Display label: plain string or i18n translation object |
| type | Enum<'grid' | 'kanban' | 'gallery' | 'calendar' | 'timeline' | 'gantt' | 'map'> | ✅ | |
| data | Object | Object | Object | optional | Data source configuration (defaults to "object" provider) |
| columns | string[] | Object[] | ✅ | Fields to display as columns |
| filter | Object[] | optional | Filter criteria (JSON Rules) |
| sort | string | Object[] | optional | |
| searchableFields | string[] | optional | Fields enabled for search |
| filterableFields | string[] | optional | Fields enabled for end-user filtering in the top bar |
| quickFilters | Object[] | optional | One-click filter chips for quick record filtering |
| resizable | boolean | optional | Enable column resizing |
| striped | boolean | optional | Striped row styling |
| bordered | boolean | optional | Show borders |
| selection | Object | optional | Row selection configuration |
| navigation | Object | optional | Configuration for item click navigation (page, drawer, modal, etc.) |
| pagination | Object | optional | Pagination configuration |
| kanban | Object | optional | |
| calendar | Object | optional | |
| gantt | Object | optional | |
| gallery | Object | optional | Gallery/card view configuration |
| timeline | Object | optional | Timeline view configuration |
| description | string | Object | optional | View description for documentation/tooltips |
| sharing | Object | optional | View sharing and access configuration |
| rowHeight | Enum<'compact' | 'short' | 'medium' | 'tall' | 'extra_tall'> | optional | Row height / density setting |
| grouping | Object | optional | Group records by one or more fields |
| rowColor | Object | optional | Color rows based on field value |
| hiddenFields | string[] | optional | Fields to hide in this specific view |
| fieldOrder | string[] | optional | Explicit field display order for this view |
| rowActions | string[] | optional | Actions available for individual row items |
| bulkActions | string[] | optional | Actions available when multiple rows are selected |
| virtualScroll | boolean | optional | Enable virtual scrolling for large datasets |
| conditionalFormatting | Object[] | optional | Conditional formatting rules for list rows |
| inlineEdit | boolean | optional | Allow inline editing of records directly in the list view |
| exportOptions | Enum<'csv' | 'xlsx' | 'pdf' | 'json'>[] | optional | Available export format options |
| userActions | Object | optional | User action toggles for the view toolbar |
| appearance | Object | optional | Appearance and visualization configuration |
| tabs | Object[] | optional | Tab definitions for multi-tab view interface |
| addRecord | Object | optional | Add record entry point configuration |
| showRecordCount | boolean | optional | Show record count at the bottom of the list |
| allowPrinting | boolean | optional | Allow users to print the view |
| emptyState | Object | optional | Empty state configuration when no records found |
| aria | Object | optional | ARIA accessibility attributes for the list view |
| responsive | Object | optional | Responsive layout configuration |
| performance | Object | optional | Performance optimization settings |
| 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%") |
pagedrawermodalsplitpopovernew_windownone
| Property | Type | Required | Description |
|---|
| pageSize | integer | ✅ | Number of records per page |
| pageSizeOptions | integer[] | optional | Available page size options |
Row color configuration based on field values
| 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) |
Row height / density setting for list view
compactshortmediumtallextra_tall
| Property | Type | Required | Description |
|---|
| type | Enum<'none' | 'single' | 'multiple'> | ✅ | Selection mode |
Timeline view configuration
| 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 |
User action toggles for the view toolbar
| 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 |
This schema accepts one of the following structures:
| Property | Type | Required | Description |
|---|
| provider | string | ✅ | |
| object | string | ✅ | Target object name |
| Property | Type | Required | Description |
|---|
| provider | string | ✅ | |
| read | Object | optional | Configuration for fetching data |
| write | Object | optional | Configuration for submitting data (for forms/editable tables) |
| Property | Type | Required | Description |
|---|
| provider | string | ✅ | |
| items | any[] | ✅ | Static data array |
View filter rule
| 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 |
View sharing and access configuration
| Property | Type | Required | Description |
|---|
| type | Enum<'personal' | 'collaborative'> | ✅ | View ownership type |
| lockedBy | string | optional | User who locked the view configuration |
Tab configuration for multi-tab view interface
| Property | Type | Required | Description |
|---|
| name | string | ✅ | Tab identifier (snake_case) |
| label | string | Object | 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 |
Visualization type that users can switch to
gridkanbangallerycalendartimelineganttmap
ObjectStack