# Vocabulary reference

The following catalog comes directly from the Journey compiler. Each entry explains what the element is for, then lists its attributes, whether each is required, the values it accepts, and the child elements it may contain. The preceding chapters describe how the elements work together. The compiler and server analysis remain authoritative.

### agent

Hands a goal to an AI assistant when one is configured, with a manual fallback for users without one. Use it where an assistant can help, such as drafting or reviewing.

| Attribute | Required | Type / values | Meaning |
|---|---|---|---|
| `id` | yes | string | Stable identifier, unique within the journey. Saved progress refers to it, so avoid renaming it after publishing. |
| `title` | yes | string | Heading shown for this stage. |

Children: `when`, `hint`, `goal`, `manual-fallback`.

### done

The final stage. Shows closing text and an optional checklist, and clears the user's saved progress. Every Journey ends with one.

| Attribute | Required | Type / values | Meaning |
|---|---|---|---|
| `id` | yes | string | Stable identifier, unique within the journey. Saved progress refers to it, so avoid renaming it after publishing. |
| `title` | yes | string | Heading shown for this stage. |

Children: `when`, `hint`, `body`, `check`.

### execute

Runs a GraphQL operation when the user presses its button, usually a mutation that saves or changes data. It can capture and reveal values from the response, such as a new record's ID.

| Attribute | Required | Type / values | Meaning |
|---|---|---|---|
| `id` | yes | string | Stable identifier, unique within the journey. Saved progress refers to it, so avoid renaming it after publishing. |
| `title` | yes | string | Heading shown for this stage. |
| `description` | yes | string | Text shown on the button that runs the operation. |
| `mutating` | no | boolean | Makes the CoCoCo app ask the user to confirm before sending. Required as `true` when the document is a mutation; optional for a query. |

Children: `when`, `hint`, `document`, `variables`, `capture`, `reveal`.

### fetch

Runs a GraphQL read when the stage opens, captures values from the response into state, and continues once it succeeds. Use it to load data that later stages need.

| Attribute | Required | Type / values | Meaning |
|---|---|---|---|
| `id` | yes | string | Stable identifier, unique within the journey. Saved progress refers to it, so avoid renaming it after publishing. |
| `title` | yes | string | Heading shown for this stage. |
| `description` | yes | string | Text shown while the data loads. |

Children: `when`, `hint`, `document`, `variables`, `capture`.

### form

Asks the user for a known set of answers, such as a name, a quantity or a date. Each field writes its answer to Journey state for later stages.

| Attribute | Required | Type / values | Meaning |
|---|---|---|---|
| `id` | yes | string | Stable identifier, unique within the journey. Saved progress refers to it, so avoid renaming it after publishing. |
| `title` | yes | string | Heading shown for this stage. |

Children: `when`, `hint`, `field`.

### info

Shows text and an optional checklist, then lets the user continue. Use it for instructions, context or a summary part-way through a process.

| Attribute | Required | Type / values | Meaning |
|---|---|---|---|
| `id` | yes | string | Stable identifier, unique within the journey. Saved progress refers to it, so avoid renaming it after publishing. |
| `title` | yes | string | Heading shown for this stage. |

Children: `when`, `hint`, `body`, `check`.

### query-pick

Runs a GraphQL read and shows the results as a list for the user to choose from; the chosen item's values are captured into state. Use it to select a customer, job or other record.

| Attribute | Required | Type / values | Meaning |
|---|---|---|---|
| `id` | yes | string | Stable identifier, unique within the journey. Saved progress refers to it, so avoid renaming it after publishing. |
| `title` | yes | string | Heading shown for this stage. |
| `description` | yes | string | Text shown above the list of results. |
| `listPath` | yes | string | Path into the response data to the list of results. |
| `labelPath` | yes | string | Path, relative to each result, to the label shown for it. |
| `sublabelPath` | no | string | Optional path, relative to each result, to a secondary line of text. |

Children: `when`, `hint`, `document`, `variables`, `capture`.

### schema-form

Builds a form from a JSON Schema, written inline or captured from an API earlier in the Journey. Use it for nested or typed configuration, or when the fields are only known at runtime.

| Attribute | Required | Type / values | Meaning |
|---|---|---|---|
| `id` | yes | string | Stable identifier, unique within the journey. Saved progress refers to it, so avoid renaming it after publishing. |
| `title` | yes | string | Heading shown for this stage. |
| `outputKey` | no | string | When set, the whole form is written as one object to `$.state.<outputKey>`. Otherwise each top-level property is written to its own state key. |
| `schema` | no | path | A `$.` path to a schema captured earlier in the Journey. Alternatively, write the schema inline as a `schema` child; use one or the other. |

Children: `when`, `hint`, `schema`.

### wait-for

Repeatedly runs a GraphQL read until a value in the response equals an expected result, or until it times out. Use it to wait for a job to finish or a status to change; checking only continues while the Journey is open.

| Attribute | Required | Type / values | Meaning |
|---|---|---|---|
| `id` | yes | string | Stable identifier, unique within the journey. Saved progress refers to it, so avoid renaming it after publishing. |
| `title` | yes | string | Heading shown for this stage. |
| `description` | yes | string | Text shown while waiting. |
| `path` | yes | string | Path into the response data whose value must equal the `equals` value. |
| `intervalSeconds` | no | number | Seconds between checks. Defaults to 3. |
| `timeoutSeconds` | no | number | Seconds before the stage stops waiting and offers a retry. Defaults to 120. |

Children: `when`, `hint`, `document`, `variables`, `equals`.

### journey

The root element: a guided process made of ordered stages.

| Attribute | Required | Type / values | Meaning |
|---|---|---|---|
| `id` | yes | string | Stable handle for the journey, unique on the instance. Saved progress refers to it, so choose it before publishing. |
| `title` | yes | string | Name shown to users. |
| `icon` | no | `device`, `network`, `customer`, `order`, `job`, `note`, `wrench`, `check`, `flag`, `generic` | Icon shown with the journey. Defaults to `generic`. |
| `estimatedMinutes` | no | integer | Approximate time to complete, in whole minutes. |

Children: `agent`, `done`, `execute`, `fetch`, `form`, `info`, `query-pick`, `schema-form`, `wait-for`, `summary`, `domain`, `input`, `knowledge-capture`, `invariant`.

### field

A question on a form stage. The answer is written to Journey state under its `key`.

| Attribute | Required | Type / values | Meaning |
|---|---|---|---|
| `key` | yes | string | State key the answer is written to, read as `$.state.<key>`. |
| `label` | yes | string | Label shown to the user. |
| `kind` | yes | `text`, `multiline`, `number`, `toggle`, `choice`, `date`, `resourcePicker` | Type of control, which also sets the type of the answer. |
| `required` | no | boolean | Set to `true` to require an answer before the user can continue. |
| `placeholder` | no | string | Hint text shown inside the empty field. |
| `help` | no | string | Short explanation shown under the field. |
| `resourceType` | no | `customer`, `order`, `job`, `workcenter` | The kind of record to pick. Required when `kind` is `resourcePicker`. |
| `defaultValue` | no | string | Initial value, written to state the first time the stage shows if the key has no value yet. For a `choice` field it must be one of the option values; for a `date` field it is an ISO date such as `2026-09-29`. |

Children: `when`, `validation`, `option`.

### input

Read-only context supplied when the journey is launched, such as the customer it concerns. Read it as `$.inputs.<key>`.

| Attribute | Required | Type / values | Meaning |
|---|---|---|---|
| `key` | yes | string | Launch-context key, read as `$.inputs.<key>`. |
| `label` | yes | string | Label describing the input. |
| `kind` | yes | `text`, `resource` | `text`, or `resource` for a reference to a record. |
| `required` | no | boolean | Set to `true` when the journey cannot start without this input. |
| `resourceType` | no | `customer`, `order`, `job`, `workcenter` | The kind of record. Required when `kind` is `resource`. |

Children: none.

### arg

One GraphQL variable: a typed literal, or a reference to an input or state value.

| Attribute | Required | Type / values | Meaning |
|---|---|---|---|
| `name` | no | string | Variable name. Required inside `variables` and `object`; omitted for items in an `array`. |
| `ref` | no | path | A `$.state` or `$.inputs` path whose value is passed with its type preserved. Cannot be combined with `value`. |
| `value` | no | literal | A literal value. Alternatively, write the literal as the element's text. |
| `type` | no | `string`, `number`, `boolean`, `null` | Type of the literal; the default is `string`. A `null` literal has no value. |

Children: none.

### capture

Copies a value from the response into Journey state for later stages.

| Attribute | Required | Type / values | Meaning |
|---|---|---|---|
| `key` | yes | string | State key the captured value is written to. |
| `path` | yes | string | Path into the response data. The value keeps its JSON type. |

Children: none.

### reveal

Shows a captured value to the user after the stage runs, such as a new record's ID.

| Attribute | Required | Type / values | Meaning |
|---|---|---|---|
| `key` | yes | string | State key of the captured value to show. |
| `label` | yes | string | Label shown with the value. |
| `copyable` | no | boolean | Set to `true` to offer a copy button. |
| `monospaced` | no | boolean | Set to `true` to show the value in a fixed-width font, which suits identifiers. |

Children: none.

### hint

Context for an AI assistant about this stage. It does not set up an assistant by itself.

| Attribute | Required | Type / values | Meaning |
|---|---|---|---|
| `canSuggest` | no | boolean | On form stages, lets an AI assistant propose values for the whole form, where one is configured. |

Children: none.

### validation

Extra rules a field's answer must meet: a pattern for text, or a range for numbers.

| Attribute | Required | Type / values | Meaning |
|---|---|---|---|
| `pattern` | no | string | Regular expression the whole value must match, for text and multiline fields. Empty values pass; use `required` to demand an answer. |
| `min` | no | number | Lowest allowed value, for number fields. |
| `max` | no | number | Highest allowed value, for number fields. |

Children: none.

### option

One choice in a `choice` field.

| Attribute | Required | Type / values | Meaning |
|---|---|---|---|
| `value` | yes | string | Value written to state when this choice is selected. |
| `label` | yes | string | Text shown for the choice. |
| `detail` | no | string | Optional secondary text shown under the label. |

Children: none.

### invariant

A rule the process must always satisfy, such as a count staying positive. It documents intent; it is not a permission check.

| Attribute | Required | Type / values | Meaning |
|---|---|---|---|
| `id` | yes | string | Identifier for the obligation, unique within the journey. |
| `description` | no | string | Plain-language statement of the obligation. |

Children: `when`, `assert`.

### eq

Condition that holds when the value at `path` equals `value`.

| Attribute | Required | Type / values | Meaning |
|---|---|---|---|
| `path` | yes | path | The `$.state` or `$.inputs` path to test. |
| `value` | yes | literal | Value to compare against. Required, except with `type="null"`; use `exists` to test whether a value is present. |
| `type` | no | `string`, `number`, `boolean`, `null` | Type of `value`. Set it when comparing typed answers; the default is `string`. |

Children: none.

### neq

Condition that holds when the value at `path` does not equal `value`.

| Attribute | Required | Type / values | Meaning |
|---|---|---|---|
| `path` | yes | path | The `$.state` or `$.inputs` path to test. |
| `value` | yes | literal | Value to compare against. Required, except with `type="null"`; use `exists` to test whether a value is present. |
| `type` | no | `string`, `number`, `boolean`, `null` | Type of `value`. Set it when comparing typed answers; the default is `string`. |

Children: none.

### lt

Condition that holds when the value at `path` is less than `value`.

| Attribute | Required | Type / values | Meaning |
|---|---|---|---|
| `path` | yes | path | The `$.state` or `$.inputs` path to test. |
| `value` | yes | literal | Number or text to compare against. |
| `type` | no | `string`, `number` | Type of `value`: `number`, or `string` (the default). |

Children: none.

### lte

Condition that holds when the value at `path` is less than or equal to `value`.

| Attribute | Required | Type / values | Meaning |
|---|---|---|---|
| `path` | yes | path | The `$.state` or `$.inputs` path to test. |
| `value` | yes | literal | Number or text to compare against. |
| `type` | no | `string`, `number` | Type of `value`: `number`, or `string` (the default). |

Children: none.

### gt

Condition that holds when the value at `path` is greater than `value`.

| Attribute | Required | Type / values | Meaning |
|---|---|---|---|
| `path` | yes | path | The `$.state` or `$.inputs` path to test. |
| `value` | yes | literal | Number or text to compare against. |
| `type` | no | `string`, `number` | Type of `value`: `number`, or `string` (the default). |

Children: none.

### gte

Condition that holds when the value at `path` is greater than or equal to `value`.

| Attribute | Required | Type / values | Meaning |
|---|---|---|---|
| `path` | yes | path | The `$.state` or `$.inputs` path to test. |
| `value` | yes | literal | Number or text to compare against. |
| `type` | no | `string`, `number` | Type of `value`: `number`, or `string` (the default). |

Children: none.

### exists

Condition that holds when the value at `path` is present and not null; an empty string still exists.

| Attribute | Required | Type / values | Meaning |
|---|---|---|---|
| `path` | yes | path | The `$.state` or `$.inputs` path to test. |
| `value` | no | `true`, `false` | Set to `false` to test that the value is absent. Defaults to `true`. |

Children: none.

### when

Holds the one condition that decides whether a stage or field takes part.

No attributes.

Children: `eq`, `neq`, `lt`, `lte`, `gt`, `gte`, `exists`, `all`, `any`, `not`.

### assert

Holds the one condition an invariant requires.

No attributes.

Children: `eq`, `neq`, `lt`, `lte`, `gt`, `gte`, `exists`, `all`, `any`, `not`.

### all

Condition that holds when every child condition holds.

No attributes.

Children: `eq`, `neq`, `lt`, `lte`, `gt`, `gte`, `exists`, `all`, `any`, `not`.

### any

Condition that holds when at least one child condition holds.

No attributes.

Children: `eq`, `neq`, `lt`, `lte`, `gt`, `gte`, `exists`, `all`, `any`, `not`.

### not

Condition that holds when its single child condition does not.

No attributes.

Children: `eq`, `neq`, `lt`, `lte`, `gt`, `gte`, `exists`, `all`, `any`, `not`.

### variables

The GraphQL variables sent with the stage's `document`.

No attributes.

Children: `arg`, `object`, `array`.

### object

A nested object value within `variables`.

| Attribute | Required | Type / values | Meaning |
|---|---|---|---|
| `name` | no | string | Name of the object within the enclosing `variables` or `object`. |

Children: `arg`, `object`, `array`.

### array

A list value within `variables`.

| Attribute | Required | Type / values | Meaning |
|---|---|---|---|
| `name` | no | string | Name of the array within the enclosing `variables` or `object`. |

Children: `arg`, `object`, `array`.

### body

Text shown on the stage. Supports `{{ }}` interpolation of inputs and state.

No attributes.

Children: none.

### check

One checklist item shown on the stage. Guidance only; the user does not have to tick it.

No attributes.

Children: none.

### summary

A short description of the journey.

No attributes.

Children: none.

### domain

A business domain the journey belongs to. Domains narrow who it is offered to, but never grant permissions.

No attributes.

Children: none.

### document

The GraphQL operation the stage runs, usually inside CDATA.

No attributes.

Children: none.

### schema

An inline form schema: prefer a schema root in urn:cococo:json-schema:1; JSON text or CDATA remains accepted.

No attributes.

Children: none.

### goal

What the AI assistant should achieve in an `agent` stage.

No attributes.

Children: none.

### knowledge-capture

A template for a note built from the run's data, which the user can edit and copy at the end.

No attributes.

Children: none.

### equals

The value a `wait-for` stage waits for.

| Attribute | Required | Type / values | Meaning |
|---|---|---|---|
| `type` | no | `string`, `number`, `boolean`, `null` | Type of `value`; the default is `string`. |
| `value` | no | literal | Value the `path` must equal for the wait to finish. Alternatively, write it as the element's text. |

Children: none.

### manual-fallback

Fallback for runners without an assistant.

No attributes.

Children: `body`, `check`.

There is one journey root. All stages are direct root children, in execution order. Root summary and knowledge-capture are single text elements; domain and input may repeat. Each stage requires id and title. Use unique IDs and one final done stage. In compiled definitions and diagnostic paths, schema-form, query-pick and wait-for appear as schemaForm, queryPick and waitFor.

General stages accept a single when and hint. Body, check, summary, domain, goal and document contain text or CDATA, not nested markup. The schema child contains a JSON object. Field defaultValue is a string attribute; typed variable and comparison literals instead use type plus value. Boolean attributes accept only true and false.