# Workspace definition reference

> Generated from the JSON Schema this platform validates against.
> It is the same document served by `iacSchemaDocument`, so it cannot
> disagree with what the server enforces. Fields with no description
> are undocumented in the schema itself.

Authoritative schema for composable, intent-driven workspaces (workspace-v1). This is the contract for every consumer of these records, in and out of the app: the app validates each record against this schema on load and rejects non-conformant ones. Everything the app emits or reads is documented here, and `additionalProperties` is false throughout so undocumented fields fail validation.

## Top level

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `icon` | string | — | Client hint: SF Symbol name for the workspace's shell tab. Consumers without a tab shell may ignore it. |
| `id` | string | yes | Unique identifier for this workspace. |
| `initialization` | `Initialization` | — | Binds URL parameters and fetches preflight context before panels render. |
| `layout` | `LayoutStack` | yes | Root node of the structural layout tree. |
| `mutations` | array of `Mutation` | — | Named graph mutations referenced by MUTATION actions via `mutationId`. |
| `panels` | array of `Panel` | yes | Panel definitions — each an isolated data-fetching boundary. |
| `requiredDomains` | array of string | — | Client hint: permission domains, any of which unlocks the workspace. Empty/absent = always available. |
| `role` | string | yes | The operational persona this workspace is built for (e.g. 'Production Cell', 'Customer Service'). |
| `state` | object | — | Global state dictionary. Values are hardcoded defaults or `$.`-bindings (resolved against the preflight result / URL bindings) at launch. |
| `title` | string | yes | Human-readable title rendered at the top of the workspace. |

## Component shapes

### ActionButton

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `actions` | array of `ActionDef` | — |  |
| `disabledCondition` | string | — | Dot-path that, when truthy, disables the button. |
| `intent` | string | — | Visual intent: 'primary', 'danger', or default. |
| `label` | string | yes |  |

### ActionDef

Maps a user interaction to a state change or graph mutation.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `event` | `onClick` \| `onSelect` \| `onChange` \| `onActionClick` | yes |  |
| `key` | string | — | State variable key to update (SET_STATE / SET_LOCAL_STATE). |
| `mutationId` | string | — | Identifier of the mutation to trigger (MUTATION). |
| `type` | `SET_STATE` \| `SET_LOCAL_STATE` \| `MUTATION` | yes |  |
| `valuePath` | string | — | Dot-path into the event context for the new value. |

### BindingValue

Any JSON value used in a `state`/`variables` tree: a literal, a `$.`-path string, or a nested object/array of the same.

### BlockElement

Polymorphic block. Exactly one variant matches on the `type` discriminator. Each variant is self-contained (base props + its own config/dataBinding) with additionalProperties:false.

### Block_ActionGroup

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `actions` | array of `ActionDef` | — |  |
| `aiHint` | string | — |  |
| `buttons` | array of `ActionButton` | — |  |
| `config` | object | — |  |
| `id` | string | yes |  |
| `subtitle` | string | — |  |
| `title` | string | — |  |
| `type` | any | yes |  |
| `visibilityCondition` | string | — |  |

#### Block_ActionGroup.config

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `layout` | `row` \| `column` | — |  |

### Block_AiInsight

App extension: inline AI analysis of the host panel's data (ai-grounding-v1, capability=analyze). Auto-runs on panel load/refresh; read-only and advisory.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `actions` | array of `ActionDef` | — |  |
| `aiHint` | string | — |  |
| `config` | object | — |  |
| `id` | string | yes |  |
| `subtitle` | string | — |  |
| `title` | string | — |  |
| `type` | any | yes |  |
| `visibilityCondition` | string | — |  |

#### Block_AiInsight.config

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `focus` | string | — | Optional author steer, e.g. "delivery risk". |
| `scope` | `panel` | — | v1: always the host panel. |

### Block_AlertBlock

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `actions` | array of `ActionDef` | — |  |
| `aiHint` | string | — |  |
| `config` | object | — |  |
| `dataBinding` | object | — |  |
| `id` | string | yes |  |
| `subtitle` | string | — |  |
| `title` | string | — |  |
| `type` | any | yes |  |
| `visibilityCondition` | string | — |  |

#### Block_AlertBlock.config

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `severity` | `info` \| `warning` \| `error` \| `critical` | — |  |

#### Block_AlertBlock.dataBinding

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `actionLabel` | string | — | Action label — literal text, or a {{ dot.path }} expression. Currently unused by the renderer — see the design spec's deferred decisions. |
| `message` | string | — | Literal text, or a {{ dot.path }} expression. |

### Block_Checklist

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `actions` | array of `ActionDef` | — |  |
| `aiHint` | string | — |  |
| `config` | object | — |  |
| `dataBinding` | object | — |  |
| `id` | string | yes |  |
| `subtitle` | string | — |  |
| `title` | string | — |  |
| `type` | any | yes |  |
| `visibilityCondition` | string | — |  |

#### Block_Checklist.config

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `showIcons` | boolean | — |  |

#### Block_Checklist.dataBinding

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | string | — | An array of items — literal text, or a {{ dot.path }} expression. |
| `label` | string | — | Within each item — literal text, or a {{ dot.path }} expression. |
| `state` | string | — | Within each item; a done-ish value shows a check — literal text, or a {{ dot.path }} expression. |

### Block_DataList

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `actions` | array of `ActionDef` | — |  |
| `aiHint` | string | — |  |
| `config` | object | — |  |
| `dataBinding` | object | — |  |
| `id` | string | yes |  |
| `subtitle` | string | — |  |
| `title` | string | — |  |
| `type` | any | yes |  |
| `visibilityCondition` | string | — |  |

#### Block_DataList.config

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `isSelectable` | boolean | — |  |

#### Block_DataList.dataBinding

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `badge` | string | — | Within each item — literal text, or a {{ dot.path }} expression. |
| `items` | string | — | An array of rows — literal text, or a {{ dot.path }} expression. |
| `primaryText` | string | — | Within each item — literal text, or a {{ dot.path }} expression. |
| `secondaryText` | string | — | Within each item — literal text, or a {{ dot.path }} expression. |
| `statusDot` | string | — | Within each item — literal text, or a {{ dot.path }} expression. |

### Block_DataTable

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `actions` | array of `ActionDef` | — |  |
| `aiHint` | string | — |  |
| `config` | object | — |  |
| `dataBinding` | object | — |  |
| `id` | string | yes |  |
| `subtitle` | string | — |  |
| `title` | string | — |  |
| `type` | any | yes |  |
| `visibilityCondition` | string | — |  |

#### Block_DataTable.config

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `isSortable` | boolean | — |  |
| `pagination` | boolean | — |  |

#### Block_DataTable.dataBinding

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `columns` | array of object | — | The table's columns — literal text, or a {{ dot.path }} expression. |
| `rows` | string | — | An array of rows — literal text, or a {{ dot.path }} expression. |

##### Block_DataTable.dataBinding.columns[]

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `accessor` | string | yes | Within each item — literal text, or a {{ dot.path }} expression. |
| `header` | string | yes | Column header — literal text, or a {{ dot.path }} expression. |
| `isStatus` | boolean | — | Render this column as a status badge. |
| `width` | number | — | Relative column width hint. |

### Block_FilterBar

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `actions` | array of `ActionDef` | — |  |
| `aiHint` | string | — |  |
| `config` | object | — |  |
| `dataBinding` | object | — |  |
| `id` | string | yes |  |
| `subtitle` | string | — |  |
| `title` | string | — |  |
| `type` | any | yes |  |
| `visibilityCondition` | string | — |  |

#### Block_FilterBar.config

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `multiSelect` | boolean | — |  |

#### Block_FilterBar.dataBinding

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `options` | string | — | An array of options — literal text, or a {{ dot.path }} expression. |
| `value` | string | — | The selected value(s) — literal text, or a {{ dot.path }} expression. |

### Block_Form

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `config` | `FormConfig` | yes |  |
| `id` | string | yes |  |
| `subtitle` | string | — |  |
| `title` | string | — |  |
| `type` | any | yes |  |

### Block_FormBlock

App extension (not in the original web catalog): input fields that write workspace state for a following MUTATION action.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `actions` | array of `ActionDef` | — |  |
| `aiHint` | string | — |  |
| `config` | object | — |  |
| `id` | string | yes |  |
| `subtitle` | string | — |  |
| `title` | string | — |  |
| `type` | any | yes |  |
| `visibilityCondition` | string | — |  |

#### Block_FormBlock.config

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `fields` | array of object | — | The form's input fields. |

##### Block_FormBlock.config.fields[]

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `key` | string | yes | Literal; the state key this field writes. |
| `label` | string | yes | Literal field label text. |
| `options` | array of object | — | Select options. |
| `placeholder` | string | — | Literal placeholder text. |
| `type` | `text` \| `number` \| `toggle` \| `select` | — |  |
| `valuePath` | string | — | The panel-data path to prefill/re-seed from — literal text, or a {{ dot.path }} expression. |

###### Block_FormBlock.config.fields[].options[]

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | string | — | Literal option label text. |
| `value` | string | — | Literal option value. |

### Block_GaugeChart

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `actions` | array of `ActionDef` | — |  |
| `aiHint` | string | — |  |
| `config` | object | — |  |
| `dataBinding` | object | — |  |
| `id` | string | yes |  |
| `subtitle` | string | — |  |
| `title` | string | — |  |
| `type` | any | yes |  |
| `visibilityCondition` | string | — |  |

#### Block_GaugeChart.config

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `max` | number | — |  |
| `min` | number | — |  |
| `thickness` | `thick` \| `thin` | — |  |

#### Block_GaugeChart.dataBinding

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | string | — | Literal text, or a {{ dot.path }} expression. |
| `value` | string | — | The number — literal text, or a {{ dot.path }} expression. |

### Block_Journey

App extension (not in the original web catalog): embeds a Journey (a guided, multi-step wizard) inline as a panel block.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `actions` | array of `ActionDef` | — |  |
| `aiHint` | string | — |  |
| `config` | object | — |  |
| `dataBinding` | object | — |  |
| `id` | string | yes |  |
| `subtitle` | string | — |  |
| `title` | string | — |  |
| `type` | any | yes |  |
| `visibilityCondition` | string | — |  |

#### Block_Journey.config

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `handle` | string | yes | The stable handle of the journey to embed, chosen from the instance's published journey library. Static and author-chosen — not a {{ }}/$. bindable value. |

#### Block_Journey.dataBinding

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `inputs` | object | — | Maps the embedded journey's declared input keys to values. Each value is a literal JSON value, a bare "$.state.x"/"$.data.x" path (typed passthrough, missing path resolves to null), or a "{{ }}" string template — the same $. expression grammar the Journey engine itself uses for its own step variables, resolved against this block's panel data and shared workspace state. This is a deliberately different convention from the rest of this schema's dataBinding fields (which use only {{ dot.path }} against panel data), because a journey's inputs commonly need to reach shared workspace state, not just this panel's own query result. |

### Block_MapBlock

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `actions` | array of `ActionDef` | — |  |
| `aiHint` | string | — |  |
| `config` | object | — |  |
| `dataBinding` | object | — |  |
| `id` | string | yes |  |
| `subtitle` | string | — |  |
| `title` | string | — |  |
| `type` | any | yes |  |
| `visibilityCondition` | string | — |  |

#### Block_MapBlock.config

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `defaultZoom` | number | — |  |

#### Block_MapBlock.dataBinding

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | string | — | Within each item — literal text, or a {{ dot.path }} expression. |
| `lat` | string | — | Within each item — literal text, or a {{ dot.path }} expression. |
| `lng` | string | — | Within each item — literal text, or a {{ dot.path }} expression. |
| `locations` | string | — | An array of locations — literal text, or a {{ dot.path }} expression. |

### Block_MediaPreview

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `actions` | array of `ActionDef` | — |  |
| `aiHint` | string | — |  |
| `config` | object | — |  |
| `dataBinding` | object | — |  |
| `id` | string | yes |  |
| `subtitle` | string | — |  |
| `title` | string | — |  |
| `type` | any | yes |  |
| `visibilityCondition` | string | — |  |

#### Block_MediaPreview.config

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `aspectRatio` | string | — |  |
| `objectFit` | string | — |  |

#### Block_MediaPreview.dataBinding

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `fallbackText` | string | — | Literal text, or a {{ dot.path }} expression. |
| `thumbnailUrl` | string | — | The image URL — literal text, or a {{ dot.path }} expression. |

### Block_MetricGroup

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `actions` | array of `ActionDef` | — |  |
| `aiHint` | string | — |  |
| `config` | object | — |  |
| `dataBinding` | object | — |  |
| `id` | string | yes |  |
| `subtitle` | string | — |  |
| `title` | string | — |  |
| `type` | any | yes |  |
| `visibilityCondition` | string | — |  |

#### Block_MetricGroup.config

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `layout` | `row` \| `grid` \| `list` | — |  |
| `size` | `large` \| `standard` | — |  |

#### Block_MetricGroup.dataBinding

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `metrics` | array of object | — | The metric tiles — literal text, or a {{ dot.path }} expression. |

##### Block_MetricGroup.dataBinding.metrics[]

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | string | — | Label — literal text, or a {{ dot.path }} expression. |
| `trend` | string | — | Literal text, or a {{ dot.path }} expression. |
| `unit` | string | — | Unit — literal text, or a {{ dot.path }} expression. |
| `value` | string | — | Literal text, or a {{ dot.path }} expression. |

### Block_Pager

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `config` | object | yes |  |
| `id` | string | yes |  |
| `title` | string | — |  |
| `type` | any | yes |  |

#### Block_Pager.config

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `hasNext` | string | yes |  |
| `next` | string | yes |  |
| `panel` | string | yes |  |
| `state` | string | yes |  |

### Block_ProgressBar

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `actions` | array of `ActionDef` | — |  |
| `aiHint` | string | — |  |
| `config` | object | — |  |
| `dataBinding` | object | — |  |
| `id` | string | yes |  |
| `subtitle` | string | — |  |
| `title` | string | — |  |
| `type` | any | yes |  |
| `visibilityCondition` | string | — |  |

#### Block_ProgressBar.config

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `color` | string | — |  |

#### Block_ProgressBar.dataBinding

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `labelLeft` | string | — | Literal text, or a {{ dot.path }} expression. |
| `labelRight` | string | — | Literal text, or a {{ dot.path }} expression. |
| `percentage` | string | — | A 0–100 number — literal text, or a {{ dot.path }} expression. |

### Block_RecordCard

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `actions` | array of `ActionDef` | — |  |
| `aiHint` | string | — |  |
| `config` | object | — |  |
| `dataBinding` | object | — |  |
| `id` | string | yes |  |
| `subtitle` | string | — |  |
| `title` | string | — |  |
| `type` | any | yes |  |
| `visibilityCondition` | string | — |  |

#### Block_RecordCard.config

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `layout` | string | — |  |
| `showAvatar` | boolean | — |  |

#### Block_RecordCard.dataBinding

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `fields` | array of `FieldRef` | — | The labelled field rows — literal text, or a {{ dot.path }} expression. |
| `statusBadge` | string | — | Literal text, or a {{ dot.path }} expression. |
| `title` | string | — | Literal text, or a {{ dot.path }} expression. |

### Block_RelationGraph

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `actions` | array of `ActionDef` | — |  |
| `aiHint` | string | — |  |
| `config` | object | — |  |
| `dataBinding` | object | — |  |
| `id` | string | yes |  |
| `subtitle` | string | — |  |
| `title` | string | — |  |
| `type` | any | yes |  |
| `visibilityCondition` | string | — |  |

#### Block_RelationGraph.config

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `layout` | string | — |  |

#### Block_RelationGraph.dataBinding

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `edges` | string | — | An array of edges — literal text, or a {{ dot.path }} expression. |
| `nodes` | string | — | An array of nodes — literal text, or a {{ dot.path }} expression. |

### Block_SparklineChart

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `actions` | array of `ActionDef` | — |  |
| `aiHint` | string | — |  |
| `config` | object | — |  |
| `dataBinding` | object | — |  |
| `id` | string | yes |  |
| `subtitle` | string | — |  |
| `title` | string | — |  |
| `type` | any | yes |  |
| `visibilityCondition` | string | — |  |

#### Block_SparklineChart.config

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `color` | string | — |  |
| `type` | `line` \| `area` | — |  |
| `valueKey` | string | — | The number within each item — literal text, or a {{ dot.path }} expression. |

#### Block_SparklineChart.dataBinding

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `dataPoints` | string | — | An array of numbers, or of objects (see config.valueKey) — literal text, or a {{ dot.path }} expression. |

### Block_StateInput

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `config` | object | yes |  |
| `id` | string | yes |  |
| `title` | string | — |  |
| `type` | any | yes |  |

#### Block_StateInput.config

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `control` | `text` \| `date` \| `number` | yes |  |
| `empty` | `null` \| `string` | — |  |
| `label` | string | yes |  |
| `placeholder` | string | — |  |
| `resetState` | array of string | — |  |
| `state` | string | yes |  |

### Block_SwatchSet

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `actions` | array of `ActionDef` | — |  |
| `aiHint` | string | — |  |
| `config` | object | — |  |
| `dataBinding` | object | — |  |
| `id` | string | yes |  |
| `subtitle` | string | — |  |
| `title` | string | — |  |
| `type` | any | yes |  |
| `visibilityCondition` | string | — |  |

#### Block_SwatchSet.config

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `shape` | `circle` \| `square` | — |  |

#### Block_SwatchSet.dataBinding

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `colorCode` | string | — | Within each item — literal text, or a {{ dot.path }} expression. |
| `label` | string | — | Within each item — literal text, or a {{ dot.path }} expression. |
| `swatches` | string | — | An array of swatches — literal text, or a {{ dot.path }} expression. |

### Block_TabSwitch

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `actions` | array of `ActionDef` | — |  |
| `aiHint` | string | — |  |
| `id` | string | yes |  |
| `subtitle` | string | — |  |
| `tabs` | array of object | — |  |
| `title` | string | — |  |
| `type` | any | yes |  |
| `visibilityCondition` | string | — |  |

#### Block_TabSwitch.tabs[]

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | string | — |  |
| `value` | string | — |  |

### Block_Text

App extension (not in the original web catalog): freeform prose with an optional markdown mode.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `actions` | array of `ActionDef` | — |  |
| `aiHint` | string | — |  |
| `config` | object | — |  |
| `dataBinding` | object | — |  |
| `id` | string | yes |  |
| `subtitle` | string | — |  |
| `title` | string | — |  |
| `type` | any | yes |  |
| `visibilityCondition` | string | — |  |

#### Block_Text.config

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `markdown` | boolean | — |  |
| `style` | `title` \| `heading` \| `body` \| `caption` | — |  |

#### Block_Text.dataBinding

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `text` | string | — | Literal text, or a {{ dot.path }} expression. |

### Block_Timeline

App extension (not in the original web catalog): a vertical event timeline.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `actions` | array of `ActionDef` | — |  |
| `aiHint` | string | — |  |
| `dataBinding` | object | — |  |
| `id` | string | yes |  |
| `subtitle` | string | — |  |
| `title` | string | — |  |
| `type` | any | yes |  |
| `visibilityCondition` | string | — |  |

#### Block_Timeline.dataBinding

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | — | Within each item — literal text, or a {{ dot.path }} expression. |
| `items` | string | — | An array of events — literal text, or a {{ dot.path }} expression. |
| `statusDot` | string | — | Within each item; tints the marker — literal text, or a {{ dot.path }} expression. |
| `timestamp` | string | — | Within each item — literal text, or a {{ dot.path }} expression. |
| `title` | string | — | Within each item — literal text, or a {{ dot.path }} expression. |

### FieldRef

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | string | yes | Label — literal text, or a {{ dot.path }} expression. |
| `value` | string | yes | Literal text, or a {{ dot.path }} expression. |

### FormConfig

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `conditionProfile` | any | — |  |
| `defaults` | object | — |  |
| `errorPrefix` | string | — |  |
| `errors` | string | yes |  |
| `fields` | array of `FormField` | yes |  |
| `groups` | array of object | — |  |
| `identity` | string | — |  |
| `mode` | `create` \| `edit` | — |  |
| `mutationId` | string | yes |  |
| `objects` | array of string | — |  |
| `record` | string | — |  |
| `resetLabel` | string | — |  |
| `result` | string | — |  |
| `sections` | array of object | — |  |
| `submitLabel` | string | — |  |

#### FormConfig.groups[]

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `columns` | `1` \| `2` | yes |  |
| `id` | string | yes |  |
| `parent` | string | — |  |
| `title` | string | yes |  |
| `when` | string | — |  |

#### FormConfig.sections[]

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `columns` | `1` \| `2` | yes |  |
| `id` | string | yes |  |
| `title` | string | yes |  |

### FormField

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `clearable` | boolean | — |  |
| `control` | `text` \| `textarea` \| `email` \| `phone` \| `password` \| `number` \| `toggle` \| `select` \| `record-picker` \| `json` | — |  |
| `group` | string | — |  |
| `help` | string | — |  |
| `hidden` | boolean | — |  |
| `label` | string | yes |  |
| `lookup` | object | — |  |
| `options` | array of object | — |  |
| `path` | string | yes |  |
| `placeholder` | string | — |  |
| `readOnly` | boolean | — |  |
| `section` | string | — |  |
| `source` | string | — |  |
| `state` | string | — |  |
| `submit` | `always` \| `changed` | — |  |
| `value` | `FormValueContract` | yes |  |
| `variant` | `FormVariant` | — |  |

#### FormField.lookup

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | string | yes |  |
| `label` | string | yes |  |
| `panelId` | string | yes |  |
| `value` | string | yes |  |

#### FormField.options[]

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | string | yes |  |
| `value` | any | yes |  |

### FormValueContract

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `additionalProperties` | boolean | — |  |
| `enum` | array | — |  |
| `items` | `FormValueContract` | — |  |
| `maxItems` | integer | — |  |
| `maxLength` | integer | — |  |
| `maximum` | number | — |  |
| `minItems` | integer | — |  |
| `minLength` | integer | — |  |
| `minimum` | number | — |  |
| `nullable` | boolean | — |  |
| `properties` | object | — |  |
| `required` | boolean | — |  |
| `serverValidators` | array of string | — |  |
| `type` | `string` \| `number` \| `integer` \| `boolean` \| `object` \| `array` \| `json` | yes |  |

### FormVariant

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `cases` | array of object | yes |  |
| `clearable` | boolean | — |  |
| `defaultCase` | string | — |  |
| `discriminator` | string | — |  |
| `encoding` | `one-of` \| `discriminator` | yes |  |
| `group` | string | — |  |
| `id` | string | yes |  |
| `label` | string | yes |  |
| `nullable` | boolean | — |  |
| `path` | string | yes |  |
| `required` | boolean | — |  |
| `source` | string | — |  |
| `submit` | `always` \| `changed` | — |  |

#### FormVariant.cases[]

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `children` | array of `FormVariant` | — |  |
| `fields` | array of `FormField` | — |  |
| `groups` | array of object | — |  |
| `key` | string | yes |  |
| `label` | string | yes |  |
| `order` | array of string | — |  |
| `value` | `FormValueContract` | yes |  |

##### FormVariant.cases[].groups[]

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `columns` | `1` \| `2` | yes |  |
| `id` | string | yes |  |
| `parent` | string | — |  |
| `title` | string | yes |  |
| `when` | string | — |  |

### GraphQLMutation

A named graph mutation. `variables` use `$.`-bindings against `$.state`, `$.context` (the triggering record) and `$.preflight`. Runs behind the host's confirm/auth gate.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `confirm` | string | — | Confirmation/auth-prompt copy shown before running. |
| `document` | string | yes | The GraphQL mutation document. |
| `id` | string | yes |  |
| `kind` | any | — |  |
| `runningLabel` | string | — | Status copy while in flight. |
| `successMessage` | string | — | Status copy on success. |
| `variables` | object | — |  |

### Initialization

Binds URL parameters and fetches preflight context before panels render.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `preflight` | object | — | An optional GraphQL query run before the dashboard loads to populate global state via the `$.preflight` root. |
| `urlBindings` | object | — | Maps raw URL parameters/query strings to initialization variables. |

#### Initialization.preflight

An optional GraphQL query run before the dashboard loads to populate global state via the `$.preflight` root.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | yes | The GraphQL query string. |
| `variables` | object | — | Variables for the preflight query, usually mapped from urlBindings. |

### LayoutPanelRef

A layout node referencing a Panel to render at this location.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `panelId` | string | yes | Must match an id in the workspace 'panels' array. |
| `type` | any | yes |  |
| `weight` | number | — | Relative flex-grow within the parent stack. |

### LayoutStack

A structural container arranging children horizontally or vertically.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `children` | array of any | yes |  |
| `direction` | `horizontal` \| `vertical` | yes |  |
| `type` | any | yes |  |
| `weight` | number | — | Relative flex-grow within the parent stack. |

### LuaMutation

Named server Lua action, invoked after confirmation through an authorized host adapter.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `confirm` | string | — | Confirmation/auth-prompt copy shown before running. |
| `handler` | string | yes |  |
| `id` | string | yes |  |
| `kind` | any | yes |  |
| `runningLabel` | string | — | Status copy while in flight. |
| `successMessage` | string | — | Status copy on success. |
| `variables` | object | — |  |

### MagicQuerySpec

The structured request behind a magicQuery panel. `noun` selects a saved query; `identifier` addresses a single record; `parameters` is a flat filter/argument map. String values only (URI-derived); the server checks the noun/params/enum values against the live registry (Tier-2) — the schema checks structure only.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `identifier` | string | — | An optional single-record address (the `#id` fragment of the legacy scalar). |
| `noun` | string | yes | Which saved query to run. Grammar (checked by the kit's Tier-1 validation, not this schema): ^[A-Za-z][A-Za-z0-9_]*$. |
| `parameters` | object | yes | Flat filter/argument map. Enum literals like `CONFIRMED` stay strings; the server checks enum legality. |

### Mutation

### Panel

A logical container that fetches its own GraphQL data and maps it to blocks.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `aiHint` | string | — | Natural-language description grounding LLM assistants on what this panel represents. |
| `blocks` | array of `BlockElement` | yes | The UI blocks rendered inside this panel. |
| `data` | any | yes | The panel's data source. A discriminated union on the optional `kind`: a GraphQL query (`kind:graphql`, or no `kind` — the legacy default), or a structured magic query over the saved-query registry (`kind:magicQuery`). |
| `id` | string | yes |  |
| `title` | string | yes |  |
| `waitForVariables` | array of string | — | Only these top-level variable names suspend loading while null or missing. An empty list allows all null values. Omission retains legacy gating on any null top-level variable. |

### PanelDataGraphQL

GraphQL query and variable bindings for this panel. `kind` is optional here — a legacy panel with no `kind` matches this branch.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | any | — |  |
| `query` | string | yes |  |
| `variables` | object | — | Maps query arguments to workspace state via `$.state.*` bindings. |

### PanelDataLua

Read-only server Lua export. The host binds invocation to the authorized published Workspace; no Lua source is delivered to the client.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `handler` | string | yes |  |
| `kind` | any | yes |  |
| `variables` | object | — |  |

### PanelDataMagicQuery

A structured magic query over the saved-query registry — the first-class alternative to an opaque GraphQL document.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | any | yes |  |
| `spec` | `MagicQuerySpec` | yes | The structured request behind a magicQuery panel. `noun` selects a saved query; `identifier` addresses a single record; `parameters` is a flat filter/argument map. String values only (URI-derived); the server checks the noun/params/enum values against the live registry (Tier-2) — the schema checks structure only. |