Flow schema reference

A flow is a JSON object. The editor builds it, the backend stores and serves it, and the iOS SDK renders it. This page documents the exact shape so you can read an exported flow, bundle one offline, or debug a resolve response. The schema is the single source of truth for both the editor and the SDK. Its current content version is CURRENT_SCHEMA_VERSION = 9 (see Schema versions).

This is the published and exported shape. The SDK receives it as the flow_schema field of a resolve response. You normally never write this by hand; the editor generates it. Read it when you export a flow, bundle one for offline use, or inspect what the SDK actually received.

Top level: `FlowDefinition`

The root object.

Field	Type	Notes
`id`	`string`	Flow ID.
`name`	`string`	Display name.
`version`	`number`	The flow’s content/migration version (1 to 8). Bumped by migrations on load.
`appId`	`string` (optional)	Owning app, for multi-app setups.
`createdAt`	`string`	ISO 8601 timestamp.
`updatedAt`	`string`	ISO 8601 timestamp.
`nodes`	`FlowNode[]`	The graph nodes. See Nodes.
`edges`	`FlowEdge[]`	The graph connections. See Edges.
`entryNodeId`	`string`	ID of the node where the flow starts.
`chrome`	`GlobalChrome` (optional)	Deprecated. Replaced by `persistentUI`. Kept only so old flows migrate.
`persistentUI`	`PersistentUI` (optional)	Navigation bar, footer, and overlay zones that wrap every screen. See Persistent UI.
`variables`	`FlowVariable[]` (optional)	Flow state. See Variables.
`globalStyles`	`FlowGlobalStyles` (optional)	Theme tokens (colors, typography, spacing, radii, shadows).
`settings`	`FlowSettings` (optional)	Default transitions, localization, analytics provider.
`background`	`ScreenBackground` (optional)	Flow-level default background, inherited by screens. See Backgrounds.
`metadata`	`Record<string, any>` (optional)	Editor/analytics extras.

Nodes

nodes is a discriminated union keyed on kind. Every node extends a base:

Field	Type	Notes
`id`	`string`	Unique within the flow.
`name`	`string`	Display name.
`kind`	`FlowNodeKind`	One of `screen`, `condition`, `assign`, `api`, `abTest`, `event`, `subflow`.
`tags`	`string[]` (optional)	Free-form tags.
`metadata`	`Record<string, any>` (optional)	Editor extras.

Only screen produces UI. condition, assign, and abTest are logic nodes the SDK evaluates to decide the next node. The kinds api, event, and subflow are declared in the schema but are not supported by the current SDKs: they are skipped during rendering. The editor also has no UI to create non-screen nodes today (see Navigation and branching). For A/B testing, use experiments, not abTest nodes.

`ScreenNode` (`kind: "screen"`)

The only node kind that renders UI. It holds a component tree.

Field	Type	Notes
`screenType`	`"standard" \| "modal" \| "bottomSheet" \| "fullScreen"` (optional)	Screen presentation style.
`layout`	`ComponentNode`	The root component (a stack, the “Root Stack”).
`props`	object (optional)	Screen-level settings. See below.
`enterTransition`	`TransitionConfig` (optional)	Per-screen enter transition override.
`exitTransition`	`TransitionConfig` (optional)	Per-screen exit transition override.
`chromeOverrides`	`ScreenChromeOverrides` (optional)	Deprecated. Use `screenSettings`.
`screenSettings`	`ScreenSettings` (optional)	Per-screen zone settings. See Zones.
`timeline`	`ScreenTimelineEvent[]` (optional)	Cross-component sequencing. See Animations.
`analytics`	`{ screenKey?, autoTrackImpressions? }` (optional)	Per-screen analytics hints.

ScreenNode.props fields:

Prop	Type	Notes
`background`	`ScreenBackground`	Layered background for this screen.
`backgroundInherit`	`boolean`	When true (or undefined), inherit the flow-level background.
`backgroundColor`, `gradient`	legacy	Kept for backward compatibility during migration.
`padding`	`number` or `{ top, right, bottom, left }`	Screen padding.
`safeArea`	`boolean`	Respect device safe area.
`statusBarStyle`	`"light" \| "dark" \| "auto"`	Status bar appearance.
`includeInProgress`	`boolean`	Count this screen in auto progress. Defaults to true.
`hideChrome`	`boolean`	Deprecated path; current flows use `screenSettings.hideAllZones`.
`animationSpeed`	`number`	Global multiplier for all animations on the screen. Default 1.0, range 0.25 to 2.0.
`particleEffect`	`ScreenParticleEffect`	Auto-play particle effect. See Particles.

`ConditionNode` (`kind: "condition"`)

If/else branching. Evaluated by the SDK; produces no UI.

Field	Type	Notes
`condition`	`FlowExpression` (string)	A safe-subset expression. See Conditions and expressions.
`outputs`	`{ trueLabel?, falseLabel? }` (optional)	Labels for the true/false edges.

`AssignNode` (`kind: "assign"`)

Sets variables from expressions. Evaluated by the SDK; produces no UI.

Field	Type	Notes
`assignments`	`{ variableKey: string; expression: FlowExpression }[]`	Each entry writes one variable.

`AbTestNode` (`kind: "abTest"`)

A schema-level split. Most A/B testing is done with experiments instead.

Field	Type	Notes
`experimentKey`	`string`	Stable ID for analytics.
`variants`	`{ id, label, weight (0-100), targetNodeId }[]`	The branches.

Declared but unsupported nodes

These exist in the type definitions but are not rendered or evaluated by the current iOS or Expo SDKs. Do not rely on them.

ApiNode (kind: "api"): a backend/external HTTP call (request, responseMapping, onError).
EventNode (kind: "event"): an event-driven entry point (eventType, eventKey).
SubflowNode (kind: "subflow"): reuse another flow (subflowId, inputMapping, outputMapping).

Edges (`FlowEdge`)

Connections between nodes. The editor keeps edges in sync with screen order, so a goNext action follows the default edge to the next screen.

Field	Type	Notes
`id`	`string`	Unique within the flow.
`fromNodeId`	`string`	Source node.
`toNodeId`	`string`	Destination node.
`kind`	`"normal" \| "conditionTrue" \| "conditionFalse" \| "error" \| "event" \| "abVariant"` (optional)	Edge role.
`label`	`string` (optional)	Display label.
`guard`	`FlowExpression` (optional)	Extra condition for multi-branch nodes.
`transition`	`TransitionConfig` (optional)	Per-edge transition (highest priority in the cascade).
`priority`	`number` (optional)	Ordering hint.
`metadata`	`Record<string, any>` (optional)	Editor extras.

Components

Each ScreenNode.layout is a ComponentNode tree:

Field	Type	Notes
`id`	`string`	Unique within the flow.
`type`	`ComponentType`	One of the 15 kinds. See Component reference.
`props`	`Record<string, any>` (optional)	Untyped prop bag. Resolved per renderer.
`children`	`ComponentNode[]` (optional)	For stacks and other containers.
`bindings`	`{ [propName]: FlowExpression }` (optional)	Bind props to expressions.
`interactions`	`ComponentInteraction[]` (optional)	Tap/change/appear handlers. See Actions reference.
`metadata`	`Record<string, any>` (optional)	Editor extras.

Props are stored as an untyped Record<string, any>. The intended shape per component kind is documented in the Component reference.

Persistent UI

persistentUI holds three optional zones that wrap every screen. Full coverage is in Persistent UI zones. The shape:

Field	Type	Notes
`navigationBar`	`PersistentZone` (optional)	Pinned to the top.
`footer`	`PersistentZone` (optional)	Pinned to the bottom.
`overlay`	`OverlayZone` (optional)	Floating layer over content.
`settings.persistDuringTransition`	`boolean` (optional)	Whether zones stay fixed during transitions. Default true.

Variables

variables is an array of FlowVariable. Full coverage is in Variables. The shape:

Field	Type	Notes
`key`	`string`	Stable key referenced everywhere.
`label`	`string` (optional)	Display name.
`type`	`"string" \| "number" \| "boolean" \| "list"`	Data type.
`listItemType`	`"string" \| "number" \| "boolean"` (optional)	Required when `type` is `list`.
`scope`	`"global"`	v1 supports global only.
`lifecycle`	`"static" \| "session"`	Persistence.
`source`	`{ kind: "constant"; value } \| { kind: "sdk"; path }`	Where the value comes from.
`writable`	`boolean`	Whether actions can change it.
`defaultValue`	`VariableValue` (optional)	Fallback when the source is unavailable.
`min`	`number` (optional)	Inclusive lower bound. `number` variables only.
`max`	`number` (optional)	Inclusive upper bound. `number` variables only.

Bounds (`min` / `max`)

min and max declare the range a number variable is allowed to hold. They are a guarantee, not a hint: the SDK clamps every write to the range, so the value can never leave it — whichever path does the writing.

{
  "key": "age",
  "label": "Age",
  "type": "number",
  "scope": "global",
  "lifecycle": "session",
  "source": { "kind": "constant", "value": 25 },
  "writable": true,
  "min": 0,
  "max": 100
}

With the above, age stays within 0–100 for all of:

setVariable number operations (increment, decrement, multiply, divide)
assign expressions
two-way component bindings (slider, picker, ruler, input)
values written by the host app, and progress restored from a previous session

Either bound may be omitted for no limit on that side. An inverted range (min greater than max) is invalid and is ignored rather than pinning the value. Bounds apply only to number variables — for text length use an input’s minLength / maxLength validation instead.

Clamping is silent, with one exception: when a user types an out-of-range number into a number input, the field snaps into range on blur and shows “Must be between X and Y”. Clamping every keystroke would make values below min impossible to type.

min / max are optional additions, so they do not change the schema version — but an SDK build predating them ignores the range. The bound only takes effect once the host app upgrades to an SDK that supports it.

Example

A minimal one-screen flow with a single text and a Continue button:

{
  "id": "flow_welcome",
  "name": "Welcome",
  "version": 8,
  "createdAt": "2026-01-10T12:00:00Z",
  "updatedAt": "2026-01-10T12:00:00Z",
  "entryNodeId": "screen_1",
  "nodes": [
    {
      "id": "screen_1",
      "name": "Welcome",
      "kind": "screen",
      "layout": {
        "id": "root",
        "type": "stack",
        "props": { "axis": "vertical", "spacing": 16, "justify": "center" },
        "children": [
          { "id": "title", "type": "text", "props": { "text": "Welcome to Acme", "fontSize": 28, "fontWeight": "700" } },
          {
            "id": "cta",
            "type": "button",
            "props": { "text": "Continue", "variant": "primary" },
            "interactions": [
              { "id": "i1", "event": "onPress", "actions": [{ "kind": "closeFlow" }] }
            ]
          }
        ]
      }
    }
  ],
  "edges": [],
  "variables": []
}

Notes

The SDK decodes leniently. An unknown ComponentType decodes to an internal unknown case and renders as nothing (or a placeholder in debug builds) rather than failing the whole screen. A single malformed child is skipped, not fatal.
chrome and chromeOverrides are deprecated. New flows use persistentUI and screenSettings.
The integer version here (the content/migration version, up to 9) is not the same as the wire-format schema_version the SDK checks. See Schema versions.

Schema & runtime

APIs & data

Help

Flow schema reference

Top level: `FlowDefinition`

Nodes

`ScreenNode` (`kind: "screen"`)

`ConditionNode` (`kind: "condition"`)

`AssignNode` (`kind: "assign"`)

`AbTestNode` (`kind: "abTest"`)

Declared but unsupported nodes

Edges (`FlowEdge`)

Components

Persistent UI

Variables

Bounds (`min` / `max`)

Example

Notes

​Top level: FlowDefinition

​Nodes

​ScreenNode (kind: "screen")

​ConditionNode (kind: "condition")

​AssignNode (kind: "assign")

​AbTestNode (kind: "abTest")

​Declared but unsupported nodes

​Edges (FlowEdge)

​Components

​Persistent UI

​Variables

​Bounds (min / max)

​Example

​Notes

​Related pages

Top level: `FlowDefinition`

Nodes

`ScreenNode` (`kind: "screen"`)

`ConditionNode` (`kind: "condition"`)

`AssignNode` (`kind: "assign"`)

`AbTestNode` (`kind: "abTest"`)

Declared but unsupported nodes

Edges (`FlowEdge`)

Components

Persistent UI

Variables

Bounds (`min` / `max`)

Example

Notes

Related pages