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.