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