Store Flows As JSON
View SourceJido.Flow.Codec is the one serialization and deserialization boundary for
canonical Flows. It uses a trusted Jido.Flow.Registry to map portable
identifiers to host modules, schemas, and atoms.
Build A Trusted Registry
registry =
Jido.Flow.Registry.new!(%{
"actions/create-greeting" => {:action, MyApp.Actions.CreateGreeting},
"flows/greeting" => {:flow, MyApp.Flows.Greeting},
"schemas/greeting-input" => {:schema, MyApp.Flows.Greeting.schema()},
"schemas/greeting-output" => {:schema, MyApp.Flows.Greeting.output_schema()},
"atoms/name" => {:atom, :name},
"atoms/owner" => {:atom, :owner},
"atoms/priority" => {:atom, :priority},
"actions/old-greeting" => {:alias, "actions/create-greeting"}
})Each typed entry is the canonical write identifier for one value. An alias is read-only and must point directly to a typed entry. The Registry rejects ambiguous write identifiers.
The host application owns the Registry. Stored data never creates atoms, derives module names, or selects an unregistered schema.
Generate A Temporary Registry
Use Jido.Flow.Codec.encode/1 when stable application identifiers are not
required:
{:ok, document, registry} = Jido.Flow.Codec.encode(flow)
{:ok, json} = Jason.encode(document)
{:ok, decoded_document} = Jason.decode(json)
{:ok, decoded_flow} = Jido.Flow.Codec.decode(decoded_document, registry)encode/1 validates the executable Flow. It collects its Action modules,
child Flow modules, schemas, and data atoms. It assigns generated identifiers
and returns the Registry separately.
The generated identifiers are deterministic only for the exact Flow value. They can change after a Flow, module, or schema change. Use them only for temporary storage, tests, or transport within one application version. Keep the Registry available until decoding is complete. Use an application-owned Registry for durable storage.
Encode And Decode
flow = MyApp.Flows.Greeting.flow()
{:ok, document} = Jido.Flow.Codec.encode(flow, registry)
{:ok, json} = Jason.encode(document)
{:ok, decoded_document} = Jason.decode(json)
{:ok, decoded_flow} = Jido.Flow.Codec.decode(decoded_document, registry)The Codec document is JSON-compatible and versioned. Use the JSON library that your application already owns.
%{
"type" => "jido.flow",
"version" => 1,
"name" => "greeting"
} = Map.take(document, ["type", "version", "name"])The root also contains description, schema, output_schema, components,
and output.
The exact component and expression fields are owned by Codec. Do not hand-edit
a semantic Jido.Flow.to_map/1 result into a stored document.
Document Versions And Operations
The writer uses version 2 for documents with operations and version 1 for
documents without operations. Every operation, including a condition, uses
$expr:
{"$expr": {"operator": "multiply", "operands": [2, 3]}}The reader accepts versions 1 and 2. It converts $condition records in
either version to Jido.Expr; version 1 rejects $expr. Literal maps use
their own tag, so a literal $expr key is not an operation. Operand reference
atoms use Registry IDs. Document versions and semantic identity versions
are separate contracts.
V3 beta operator corrections do not change these document versions. Existing
membership and ordering records use native Elixir behavior. Binary and and
or now have distinct operators; existing all and any records retain their
strict Boolean behavior. Rebuild earlier source expressions to obtain the new
binary operators. Review stored branch rules after upgrading. See
Beta behavior corrections.
Store A Compiled Inline Step
First define FirstFlow.Greeting from Build Your First Flow.
The host registers its compiled Actions under application-owned identifiers.
Named binding keys, such as :name, also need atom identifiers.
registry =
Jido.Flow.Registry.new!(%{
"actions/greeting/normalize/v1" => {:action, FirstFlow.Greeting.step_action("normalize")},
"actions/greeting/greet/v1" => {:action, FirstFlow.Greeting.step_action("greet")},
"schemas/greeting/input/v1" => {:schema, FirstFlow.Greeting.schema()},
"schemas/greeting/output/v1" => {:schema, FirstFlow.Greeting.output_schema()},
"atoms/name" => {:atom, :name}
})
flow = FirstFlow.Greeting.flow()
{:ok, document} = Jido.Flow.Codec.encode(flow, registry)
json = JSON.encode!(document)
{:ok, restored} = Jido.Flow.Codec.decode(JSON.decode!(json), registry)
true = restored == flow
{:ok, %{message: "Hello, Ada!"}} = Jido.Exec.run(restored, %{name: " Ada "})This example uses Elixir's built-in JSON module. No new stored format is
needed. The encoded Steps still contain only these version 1 fields:
%{"type" => "jido.flow", "version" => 1} = document
[normalize, greet] = document["components"]
"actions/greeting/greet/v1" = greet["action"]
["action", "kind", "meta", "name", "needs", "params"] = Enum.sort(Map.keys(greet))
%{
"$type" => "map",
"entries" => [
%{
"key" => %{"$type" => "atom", "id" => "atoms/name"},
"value" => %{
"$ref" => %{
"source" => "input",
"component" => nil,
"path" => [%{"$type" => "atom", "id" => "atoms/name"}]
}
}
}
]
} = normalize["params"]Stored JSON selects trusted deployed Actions. It cannot define a body, carry a closure or MFA, or evaluate Elixir. Deploy both the owning Flow module and its generated Actions. Keep identifiers under host control; do not store the internal generated module name as the public Action identifier.
A body change can retain the same target and semantic graph identity. Neither the stored document nor its graph identity is a code snapshot. Select the application release and Registry version needed to run stored work.
The same Registry rule applies to an inline Step target. Resolve it through
the owner Flow's step_action/1, then register that ordinary Action. Inline
metadata and schemas belong to the deployed target, not to stored body code.
Inline Steps add no Codec version. See Inline Actions.
Validation And Limits
Decode first checks the stored grammar and resource limits. It rejects:
- invalid UTF-8;
- nesting deeper than 100 levels;
- one map or list with more than 10,000 items;
- a document with more than 100,000 data nodes;
- unknown or extra fields;
- unknown Registry identifiers; and
- invalid canonical Flow data.
Encode checks the completed document against the same storage limits. It returns an error if format overhead makes the document too large or too deep for the reader.
These limits do not bound HTTP bytes or the JSON parser. Apply transport and
parser limits before decode/2.
Decode is inert. It does not run Actions. Call
Jido.Flow.validate_executable/1 when you want a target-contract check, or
run through Jido.Exec.
Diagnose An Editor Draft
decode/2 returns the first error. Use diagnose/2 when a browser editor must
show all independent document and graph errors:
case Jido.Flow.Codec.diagnose(editor_document, registry) do
{:ok, flow} ->
{:ok, flow}
{:error, errors} ->
{:error, Jido.Flow.Error.to_map(errors)}
endThe error is one %Jido.Flow.Error.Invalid{} Splode group. Its ordered leaf
errors have JSON paths when a path applies. The public error map contains the
leaf errors under details.errors.
Diagnostics collect errors across root fields, components, nested Choice records, expressions, conditions, lists, maps, and graph references. They do not return a partial Flow. Unknown-reference errors suppress a derived cycle error because that cycle result would be misleading.
Document size, collection size, nesting, root type, and document version errors are terminal. Diagnostics do not traverse a document after one of these failures.
diagnose/2 checks the stored and canonical Flow contract. It does not check
whether resolved Action or child Flow modules are executable. After a valid
decode, call Jido.Flow.validate_executable/1 when the editor also needs that
host-runtime check.
Store the encoded document, not Jido.Flow.Compiled, a raw struct map, or an
Instruction.