Skip to main content
A Workflow Definition is a JSON object that acts as the blueprint for an executable backend workflow. It describes the individual components, their configurations, and how they are wired together to process information linearly or conditionally.

​
High-Level Structure

Every Workflow Definition adheres to the following core JSON schema:

​
Top-Level Properties

​
Components Array

The components array contains objects detailing the individual processing units. Each component has an ID, a type definition, and configurations for its specific behavior and positional placement if rendered visually in the UI.
For an exhaustive list of components and their configurations, refer to the Workflow Components page.

​
Connections Array

The connections array defines how control passes between components upon execution. Connections are directional edges between a specific output “route” of a source component and a specific input “route” of a target component.

​
Connection Properties

  • id: The connection’s own identifier, unique within the definition. Required — a definition whose connections omit it, or reuse one, fails validation and will not execute. Visual editors key their edges by this value, so connections without one collapse into a single edge when the workflow is drawn.
  • source_id: The ID of the component yielding control.
  • target_id: The ID of the component receiving control.
  • source_port: The physical output port the connection originates from.
  • target_port: The physical input port the connection arrives at.
  • route: The semantic logic path dictating when this edge fires (e.g., "success", "failure", "next").

​
Connector Placement

Every component exposes its connectors at fixed positions on the node. Knowing where each one sits lets you place components (via their position) so edges stay short and non-crossing — clean, readable flows. The diagram below shows all connector types on a single component (logic.code) and the components they connect to:
Workflow connector placement — flow in/out on top/bottom, data on the right, provider on the left
Data and provider components expose the matching reference ports (data_reference, provider_reference) so the edges land on their facing side.

​
Laying out clean flows

Because the connectors are fixed, a few conventions produce tidy definitions:
  • Flow runs top → bottom. flow_input is on the top edge and flow_output on the bottom, so stack sequential steps vertically — same x, increasing y.
  • Data sits to the right. data_input and data_output exit the right side, so place the message / list / data components a step reads or produces to its right.
  • Providers sit to the left. provider_input is on the left edge, so place provider components to the left.
The position field ({ "x", "y" }) on each component is what the editor renders from; following these conventions keeps the graph legible.