A Jido.Flow is the canonical authoring value for a local workflow. It lowers to native Runic workflow data for execution through Jido.Exec.

See Flow Modules for the module API.

Canonical Value

A Flow has six fields:

FieldTypePurpose
namestringStable human-readable name.
descriptionstring or nilOptional description.
schemastatic Zoi schema or []Input contract.
output_schemastatic Zoi schema or []Output contract.
componentsordered component listAuthor-declared graph data.
outputexpressionRequired Flow result.

The component types are:

Each component has a name, explicit needs dependencies, and portable meta data. Data references create inferred dependencies. Jido keeps explicit and inferred dependencies separate.

A Flow can have at most one Dispatch component. Dispatch must be the last component, and the Flow output must be the complete Dispatch result. Its decision Action returns data for its expander Action. A normal expander result completes the Flow. {:continue, input, target} ends the Flow and selects the next executable for the same Jido.Exec.run/4 call.

Dispatch is not available through step-wise execution or as part of a Subflow. These limits keep continuation in one complete Exec call. See Dynamic Flows.

One Expression Grammar

Expressions contain portable scalar values, proper lists, maps, and Jido.Flow.Ref values. Jido.Expr adds fixed Boolean, comparison, numeric, and binary-concatenation operations. Flow fields accept these operations directly or inside an optional expr(...) wrapper.

References can read Flow input, context, prior component results, and component-local Map, Reduce, or Iterate values. A reference is valid only in its defined scope.

Boolean references and literals are also valid conditions. Their evaluated values must be Boolean. See Expressions for the shared helper DSL, exact operations, runtime construction, errors, and limits.

The authoring grammar permits any expression at output. At execution, a normal Flow result must be a map. Use Jido.Action.Output when a Flow must return an intentional raw, stream, batch, or opaque value.

Three Authoring Forms

All supported forms produce the same canonical value:

  1. a module that uses Jido.Flow;
  2. Data definitions with Jido.Flow.new/1, using component maps or constructors; and
  3. Jido.Flow.Codec.decode/2 for stored JSON data.

The module DSL is the normal source-code API. Direct constructors are also an official API. Data definitions and Codec input pass through the same canonical validation.

Author Data And Runtime Data

A Flow stores author intent. Jido.Flow.compile/2 derives a Jido.Flow.Compiled value with a native Runic.Workflow, component indexes, source locations, and a compilation digest. Do not store the compiled value.

Jido.Exec compiles and runs a Flow. Step-wise execution exposes small Jido.Exec.Work descriptions, including Join, input binding, fan-out, and fan-in support work. Select a unit with its revision-scoped token. Use Jido.Exec.native/1 for advanced, read-only native inspection.

Validation And Inspection

{:ok, flow} = Jido.Flow.validate(flow)
{:ok, flow} = Jido.Flow.validate_executable(flow)
{:ok, dependencies} = Jido.Flow.dependencies(flow)
{:ok, explanation} = Jido.Flow.explain(flow)
{:ok, identity} = Jido.Flow.semantic_identity(flow)

validate/1 is inert and does not load or check target modules. validate_executable/1 also checks Action and child Flow contracts. Neither function runs Action work.

All authoring forms use the same graph rules. DSL errors identify the source declaration; new/1 and validate/1 return the first error.

Continue with Flow DSL, Flow Data Definitions, and Store Flows As JSON.

Deferred Effect Requests

Return {:ok, output, requests} from an Action to request effects after success. Flow collects these opaque requests in canonical dependency order and returns the complete batch with its final output. Exec does not execute effects. Failed execution returns no executable batch. The optional third success element must be a proper list of effect requests. See Execution for ordering, collections, continuations, and migration.