Flow Data Definitions
View SourceUse 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
kind | Target fields | Other main fields |
|---|---|---|
:step | action | params |
:subflow | flow | params |
:choice | options, fallback | Ordered routing options |
:map | action | collection, params, on_error |
:reduce | action | collection, initial, params |
:iterate | action | params, state, completion, max_iterations |
:dispatch | decision, expander | params |
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.