Flow Data Definitions

View Source

Use Jido.Flow.new/1 to validate a Flow definition made from maps. The module DSL, data definitions, and stored JSON through Jido.Flow.Codec produce the same canonical %Jido.Flow{} value.

Define A Flow

alias Jido.Flow
alias Jido.Flow.Ref

{:ok, flow} =
  Flow.new(%{
    name: "send_notice",
    components: [
      %{
        kind: :step,
        name: "send",
        action: MyApp.SendNotice,
        params: %{address: Ref.input(:address)}
      }
    ],
    output: Ref.result("send")
  })

new/1 returns {:ok, flow} or a structured validation error. new!/1 raises that error. Maps and keyword lists are accepted for Flow configuration. Each component must be a tagged map or a value from a component constructor. Unknown fields and invalid component kinds are rejected. An explicit, non-nil output is required.

Use normal Elixir list and map operations to assemble runtime definitions. Construct the complete definition, then call Jido.Flow.new/1. There is no separate finalization call.

Component Kinds

kindTarget fieldsOther main fields
:stepactionparams
:subflowflowparams
:choiceoptions, fallbackOrdered routing options
:mapactioncollection, params, on_error
:reduceactioncollection, initial, params
:iterateactionparams, state, completion, max_iterations
:dispatchdecision, expanderparams

All component kinds accept name, needs, and meta. Each tagged map uses its existing component constructor for field and expression validation. Choice options, its fallback, and Iterate state accept maps through their existing constructors.

Keep components and Choice options in lists. Choice evaluates options in list order. Component declaration order does not create dependencies. Result references and needs define dependencies. Canonical dependency and name order define execution results and effect order.

Data definitions use an explicit :subflow kind and flow field for a child Flow module. A :step uses an Action module. The module DSL can derive a Subflow from a step target. Constructor validation is inert; Jido.Flow.validate_executable/1 also checks target contracts.

References And Expressions

Use Jido.Flow.Ref for input, context, component results, collection items, accumulators, and iteration state. Ref.select/2 appends a path after it validates the source reference. Flow validation checks the complete resulting path and its scope.

Use Jido.Expr.new/2, new!/2, or the expression helper DSL for operations. Ordinary map and list values remain literal data. Do not interpret a literal map as an operation or reference based on its field names.

Reuse An Inline Step

A compiled Flow module exposes a Step Action through step_action/1. Supply new parameter expressions, dependencies, and metadata when you reuse it:

alias Jido.Flow
alias Jido.Flow.Ref

Flow.new!(%{
  name: "normalize_names",
  components: [
    %{
      kind: :map,
      name: "names",
      collection: Ref.input(:people),
      action: MyApp.NormalizePerson.step_action("normalize"),
      params: %{name: Ref.item()}
    }
  ],
  output: %{names: Ref.result("names")}
})

Data definitions accept compiled targets. They do not accept inline body code, anonymous functions, or MFA targets.

Stored Or AI-Generated Definitions

Elixir data definitions contain trusted host modules and references. For JSON-compatible definitions from storage or an AI model, use Jido.Flow.Codec.decode/2 with a host-owned Jido.Flow.Registry. The Registry resolves approved identifiers. Input strings must not create atoms or derive module names. Jido.Flow.to_map/1 is an inspection view; use Codec for serialization. See Flow Storage.

Migrate From Builder

Jido.Flow.Builder was removed in V3 beta. Replace its pipeline with a complete Flow map and Jido.Flow.new/1. Replace its reference helpers with Jido.Flow.Ref, its condition helpers with Jido.Expr, and Choice helpers with option and fallback maps. Use an explicit :subflow component for child Flow targets.