View schema — UI Protocol property reference

View protocol schemas — the view metadata type and its three persisted body spellings.

View protocol schemas — the view metadata type and its three persisted body spellings.

Covers the authoring surfaces (defineView, defineViewItem), the wire doors Studio and the REST layer write through, and ViewMetadataSchema — the union every persisted view body is judged by.

Name grammar depends on the body spelling

ViewMetadataSchema is a union over three persisted body shapes, and they do not share one name grammar. Which grammar applies is decided by the shape of the body — something an author never names explicitly — so neither failure direction below is discoverable from the key being written:

body spelling	recognised by	`name` is declared as	flat (undotted) name
standalone ViewItem record	a nested `config`	`ViewItemNameSchema` — `QUALIFIED_ITEM_NAME_PATTERN`, dot REQUIRED	rejected, located at `["name"]`
flattened runtime overlay	an inline view config; no `config`, no container slot	`z.string().optional()` — no grammar at all	accepted
`defineView` container	a container slot (`list` / `form` / `listViews` / `formViews`)	`z.string().optional()` on `ViewSchema` — no grammar at all	accepted, and normally IS flat

The two permissive rows are deliberate, not gaps left to tighten later:

A container's own name is the bare object key. ADR-0017 §3.2's dual-read loader registers the aggregated container under <object> and each expanded item under <object>.<viewKey>, so an object-scoped container is named crm_lead — a name with no dot to carry.
An overlay's name is stamped by the write path, not authored: normalizeViewMetadata puts it on every view body at the single write chokepoint, and a personalization PUT inherits the identity of the entry it shadows.

So both of the readings an author naturally forms are wrong:

"the dot is mandatory on every view row" — read off ViewItemNameSchema alone. It is not: overlay and container rows accept flat names, and rows in this repo legitimately use them (case_grid, cases, the container row crm_lead). Those rows are correct as written, not defects awaiting a dotted rewrite.
"flat names are fine generally" — read off one of those flat-named rows. It is not: put the same name on a standalone ViewItem record and it is refused, on the one field the flat-named row told you to fill.

This describes what the three shapes already do; it widens and narrows nothing. The one item-name grammar itself lives in shared/identifiers.zod.ts — grammar changes belong there, not here.

Source: packages/spec/src/ui/view.zod.ts

TypeScript Usage

import { AddRecordConfigSchema, AppearanceConfigSchema, CalendarConfigSchema, ColumnPrefixSchema, ColumnSummarySchema, ColumnSummaryConfigSchema, EmptyStateSchema, FormButtonConfigSchema, FormFieldSchema, FormSectionSchema, FormSelectOptionSchema, FormViewSchema, GalleryConfigSchema, GanttConfigSchema, GanttQuickFilterSchema, GroupingConfigSchema, GroupingFieldSchema, HttpMethodSubsetSchema, HttpRequestSchema, KanbanConfigSchema, ListChartConfigSchema, ListColumnSchema, ListMapConfigSchema, ListViewSchema, NavigationConfigSchema, NavigationModeSchema, ObjectListViewSchema, ObjectUserFiltersSchema, PaginationConfigSchema, RowColorConfigSchema, RowHeightSchema, SelectionConfigSchema, TimelineConfigSchema, TreeConfigSchema, UserActionsConfigSchema, UserFilterFieldSchema, UserFiltersSchema, ViewSchema, ViewDataSchema, ViewFilterRuleSchema, ViewItemSchema, ViewItemNameSchema, ViewItemWireSchema, ViewKindSchema, ViewScopeSchema, ViewSharingSchema, ViewTabSchema, VisualizationTypeSchema } from '@objectstack/spec/ui';
import type { AddRecordConfig, AppearanceConfig, CalendarConfig, ColumnPrefix, ColumnSummary, ColumnSummaryConfig, EmptyState, FormButtonConfig, FormField, FormSection, FormSelectOption, FormView, GalleryConfig, GanttConfig, GanttQuickFilter, GroupingConfig, HttpMethodSubset, HttpRequest, KanbanConfig, ListChartConfig, ListColumn, ListMapConfig, ListView, NavigationConfig, NavigationMode, PaginationConfig, RowColorConfig, RowHeight, SelectionConfig, TimelineConfig, TreeConfig, UserActionsConfig, UserFilterField, UserFilters, View, ViewData, ViewFilterRule, ViewItem, ViewItemName, ViewItemWire, ViewKind, ViewScope, ViewSharing, ViewTab, VisualizationType } from '@objectstack/spec/ui';

// Validate data
const result = AddRecordConfigSchema.parse(data);

AddRecordConfig

Add record entry point configuration

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

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

Property	Type	Required	Description
startDateField	`string`	✅	Field providing the event start date/time
endDateField	`string`	optional	Field providing the event end date/time (defaults to a single-day event)
titleField	`string`	optional	Field displayed as the event title. Omit to fall back to the record display name (ADR-0079 resolver chain)
colorField	`string`	optional	Field to derive each event color from (it names a field, not a color): the option color declared on that field for the record value, else the value itself when it already is a color literal (hex, rgb() or hsl()), else the calendar theme-aware palette color hashed from the value
allDayField	`string`	optional	Field carrying the all-day flag for each event (names a boolean field, not a value): a record whose flag is true is drawn as an all-day band rather than at a clock time, and one whose flag is absent or false is not all-day. Omit to leave the renderer inference in place — an event with no end date draws as all-day

Property	Type	Required	Description
field	`string`	✅	Field whose value renders before the cell value
type	`Enum<'badge' \| 'text'>`	optional (default: `"text"`)	How the prefix value is rendered