Journey 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.

A guided, data-defined process (spec schema 2). Mirrors the reference Swift runner in cococo/Gateway/Journeys/. See docs/journeys/specification.md.

Top level

Component shapes

AgentHint

Field	Type	Required	Description
canSuggest	boolean	—	Form steps only: enable one-shot whole-form value proposal where the runner has an agent.
context	string	yes	Prose handed to the assistant for step-aware help. {{ $. }} templating applies.

AgentPayload

Field	Type	Required	Description
goal	string	yes	Goal handed to the assistant ({{ $. }} templating applies).
manualFallback	InfoPayload	—	Rendered as an info step on runners without agent capability. Absent ⇒ the journey is unsupported there (spec §2.2/§5.6).

CaptureRule

Field	Type	Required	Description
key	string	yes
path	string	yes	Dot-path into the response data; the leaf is written to state preserving its JSON type.

ChoiceOption

Field	Type	Required	Description
detail	string	—
label	string	yes
value	string	yes

Condition

Spec §4. Exactly one operator per object — one of {eq, neq, lt, lte, gt, gte, exists} on a leaf, or a composite {all, any, not}. path is a $. expression; eq/neq compare with strict semantic equality (no coercion); ordering operators are defined only for number↔number or string↔string pairs and yield false for any other combination.

Set exactly one of: path + eq, or path + neq, or path + lt, or path + lte, or path + gt, or path + gte, or path + exists, or all, or any, or not.

ExecutePayload

Field	Type	Required	Description
capture	array of CaptureRule	—	Load-bearing: a missing path fails the step.
description	string	yes	User-facing; shown on the run button.
document	string	yes	GraphQL document; exactly one root operation field, aliased result.
mutating	boolean	—	Require the platform confirm-it's-you gate before running.
reveal	array of RevealRule	—
variables	Variables	—	Structured GraphQL variables (spec §6). Each string leaf is either a whole-value $. reference or a literal that may interpolate {{ $. }} placeholders; non-string leaves are typed literals. Leaf-level $. well-formedness is enforced by the runner/server, not by this schema.

FetchPayload

Read-only 'load one object' step (spec §5.3c). Never mutates — no confirm-it's-you gate.

Field	Type	Required	Description
capture	array of CaptureRule	yes	state[key] <- value at a dot-path into the response data (whole objects included). Load-bearing: a missing path fails the step.
description	string	yes	Shown while loading.
document	string	yes	GraphQL query document; the root selection SHOULD alias to result.
variables	Variables	—	Structured GraphQL variables (spec §6). Each string leaf is either a whole-value $. reference or a literal that may interpolate {{ $. }} placeholders; non-string leaves are typed literals. Leaf-level $. well-formedness is enforced by the runner/server, not by this schema.

Field

Field	Type	Required	Description
condition	Condition	—	Spec §4. Exactly one operator per object — one of {eq, neq, lt, lte, gt, gte, exists} on a leaf, or a composite {all, any, not}. path is a $. expression; eq/neq compare with strict semantic equality (no coercion); ordering operators are defined only for number↔number or string↔string pairs and yield false for any other combination.
defaultValue	string	—	Written to state when the step first shows.
help	string	—	Short inline explanation under the field.
key	string	yes
kind	text | multiline | number | toggle | choice | date | resourcePicker	yes
label	string	yes
options	array of ChoiceOption	—	choice kind only.
placeholder	string	—
required	boolean	—
resourceType	customer | order | job | workcenter	—	resourcePicker kind only.
validation	FieldValidation	—

FieldValidation

Field	Type	Required	Description
max	number	—	Numeric upper bound (number kind).
min	number	—	Numeric lower bound (number kind).
pattern	string	—	Whole-value regular expression (text/multiline). Empty values pass — required handles presence.

FormPayload

Field	Type	Required	Description
fields	array of Field	yes

InfoPayload

Field	Type	Required	Description
body	string	yes	Markdown-lite prose. {{ $. }} templating applies.
checklist	array of string	—

Input

Field	Type	Required	Description
key	string	yes	Read-only launch-context key, addressed as $.inputs[key].
kind	text | resource	yes
label	string	yes
required	boolean	—
resourceType	customer | order | job | workcenter	—	Required when kind == resource.

Journey

Field	Type	Required	Description
estimatedMinutes	integer	yes
icon	device | network | customer | order | job | note | wrench | check | flag | generic	yes	Icon vocabulary token (spec §2.3). Unknown tokens render the generic icon.
id	string	yes	Stable, kebab-case, unique per instance. Resume state and analytics key on it; on collision a server definition overrides a bundled default (spec §8).
inputs	array of Input	—
invariants	array of object	—	Spec §6.4. Authored assertions that must hold on every reachable state. assert reuses the shared condition dialect.
knowledgeCaptureTemplate	string	—	Optional prose template ({{ $.state.x }}) offered as an editable shop note on completion (spec §9).
requiredDomains	array of string	yes	Offered only if the user's effective permissions grant ANY listed domain. [] = everyone.
schemaVersion	integer	yes	This document describes schema 2. A runner hides any journey whose schemaVersion exceeds what it supports (spec §2.2).
steps	array of Step	yes	At least one; the last reachable step should be done.
summary	string	yes
title	string	yes

Journey.invariants[]

Field	Type	Required	Description
assert	Condition	yes	Spec §4. Exactly one operator per object — one of {eq, neq, lt, lte, gt, gte, exists} on a leaf, or a composite {all, any, not}. path is a $. expression; eq/neq compare with strict semantic equality (no coercion); ordering operators are defined only for number↔number or string↔string pairs and yield false for any other combination.
description	string	—
id	string	yes	Stable, author-facing identifier.

QueryPickPayload

Read-only 'run a query, pick a result' step (spec §5.3a). Never mutates — no confirm-it's-you gate.

Field	Type	Required	Description
capture	array of CaptureRule	yes	state[key] <- value at a dot-path WITHIN the chosen result object.
description	string	yes	User-facing prose shown above the result list.
document	string	yes	GraphQL query document.
labelPath	string	yes	Dot-path, relative to each result object, to its display label.
listPath	string	yes	Dot-path into the response data to the array of result objects.
sublabelPath	string	—	Optional dot-path (relative to each result) to a secondary line.
variables	Variables	—	Structured GraphQL variables (spec §6). Each string leaf is either a whole-value $. reference or a literal that may interpolate {{ $. }} placeholders; non-string leaves are typed literals. Leaf-level $. well-formedness is enforced by the runner/server, not by this schema.

RevealRule

Field	Type	Required	Description
copyable	boolean	—
key	string	yes
label	string	yes
monospaced	boolean	—

SchemaFormPayload

Hosts a platform draft-07 JSON Schema form (spec §5.2b). Never mutates — no confirm-it's-you gate.

Field	Type	Required	Description
outputKey	string	—	When set, the whole form output is written as one object to $.state[outputKey]; otherwise each top-level property writes $.state[property].
schema	object	yes	An inline draft-07 JSON Schema object, or a $. expression string resolving to a schema captured into state at runtime.

Step

Field	Type	Required	Description
agent	AgentPayload	—
condition	Condition	—	Spec §4. Exactly one operator per object — one of {eq, neq, lt, lte, gt, gte, exists} on a leaf, or a composite {all, any, not}. path is a $. expression; eq/neq compare with strict semantic equality (no coercion); ordering operators are defined only for number↔number or string↔string pairs and yield false for any other combination.
execute	ExecutePayload	—
fetch	FetchPayload	—	Read-only 'load one object' step (spec §5.3c). Never mutates — no confirm-it's-you gate.
form	FormPayload	—
hint	AgentHint	—
id	string	yes	Unique within the journey; resume targets it.
info	InfoPayload	—
kind	info | form | schemaForm | fetch | queryPick | execute | waitFor | agent | done	yes
queryPick	QueryPickPayload	—	Read-only 'run a query, pick a result' step (spec §5.3a). Never mutates — no confirm-it's-you gate.
schemaForm	SchemaFormPayload	—	Hosts a platform draft-07 JSON Schema form (spec §5.2b). Never mutates — no confirm-it's-you gate.
title	string	yes
waitFor	WaitPayload	—

Variables

Structured GraphQL variables (spec §6). Each string leaf is either a whole-value $. reference or a literal that may interpolate {{ $. }} placeholders; non-string leaves are typed literals. Leaf-level $. well-formedness is enforced by the runner/server, not by this schema.

WaitPayload

Field	Type	Required	Description
description	string	yes
document	string	yes
equals	any	yes	Typed JSON literal the polled value must equal.
intervalSeconds	number	—
path	string	yes	Dot-path into data whose value must equal equals.
timeoutSeconds	number	—
variables	Variables	—	Structured GraphQL variables (spec §6). Each string leaf is either a whole-value $. reference or a literal that may interpolate {{ $. }} placeholders; non-string leaves are typed literals. Leaf-level $. well-formedness is enforced by the runner/server, not by this schema.