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.