Jido.Tools.ZoiExample (Jido Action v2.0.0-rc.0)

View Source

Production-quality example demonstrating Zoi schema features in Jido actions.

This action showcases best practices for using Zoi schemas:

  • Email validation with transformations (trim, downcase)
  • Password validation with refinements
  • Enums for constrained choices
  • Optional fields with defaults
  • Nested object schemas
  • Output validation
  • Custom refinements for business logic

Example Usage

iex> params = %{
...>   user: %{
...>     email: "  JOHN@EXAMPLE.COM  ",
...>     password: "SecurePass123!",
...>     name: "John Doe"
...>   },
...>   priority: :high,
...>   metadata: %{source: "web"}
...> }
iex> {:ok, result} = Jido.Tools.ZoiExample.run(params, %{})
iex> result.user.email
"john@example.com"
iex> result.status
:validated

Zoi Features Demonstrated

Transformations

Validators

Refinements

Type System

Summary

Functions

__action_metadata__()

Returns the Action metadata. Alias for to_json/0.

category()

Returns the category of the Action.

description()

Returns the description of the Action.

name()

Returns the name of the Action.

on_after_run(result)

Lifecycle hook called after Action execution.

on_after_validate_output(output)

Lifecycle hook called after output validation.

on_after_validate_params(params)

Lifecycle hook called after parameter validation.

on_before_validate_output(output)

Lifecycle hook called before output validation.

on_before_validate_params(params)

Lifecycle hook called before parameter validation.

on_error(failed_params, error, context, opts)

Lifecycle hook called when an error occurs.

output_schema()

Returns the output schema of the Action.

run(params, context)

Validates user registration data with comprehensive checks.

schema()

Returns the input schema of the Action.

tags()

Returns the tags associated with the Action.

to_json()

Returns the Action metadata as a JSON-serializable map.

to_tool()

Converts the Action to an LLM-compatible tool format.

validate_output(output)

Validates the output result for the Action.

validate_params(params)

Validates the input parameters for the Action.

vsn()

Returns the version of the Action.

Functions

__action_metadata__()

Returns the Action metadata. Alias for to_json/0.

category()

Returns the category of the Action.

description()

Returns the description of the Action.

name()

Returns the name of the Action.

on_after_run(result)

@spec on_after_run({:ok, map()} | {:error, any()}) :: {:ok, map()} | {:error, any()}

Lifecycle hook called after Action execution.

on_after_validate_output(output)

@spec on_after_validate_output(map()) :: {:ok, map()} | {:error, any()}

Lifecycle hook called after output validation.

on_after_validate_params(params)

@spec on_after_validate_params(map()) :: {:ok, map()} | {:error, any()}

Lifecycle hook called after parameter validation.

on_before_validate_output(output)

@spec on_before_validate_output(map()) :: {:ok, map()} | {:error, any()}

Lifecycle hook called before output validation.

on_before_validate_params(params)

@spec on_before_validate_params(map()) :: {:ok, map()} | {:error, any()}

Lifecycle hook called before parameter validation.

on_error(failed_params, error, context, opts)

@spec on_error(map(), any(), map(), keyword()) :: {:ok, map()} | {:error, any()}

Lifecycle hook called when an error occurs.

output_schema()

Returns the output schema of the Action.

run(params, context)

@spec run(map(), map()) :: {:ok, map()} | {:ok, map(), any()} | {:error, any()}

Validates user registration data with comprehensive checks.

This action demonstrates how validated and transformed parameters flow through the action pipeline. The input params are automatically:

  • Validated against schema constraints
  • Transformed (trimmed, case-converted)
  • Checked against custom refinements

Parameters

  • :user - User object with email, password, name, and optional age
  • :priority - Registration priority (defaults to :normal)
  • :metadata - Optional metadata about the registration

Returns

  • {:ok, result} - Validated user data with status and timestamp
  • {:error, reason} - Validation or processing errors

schema()

Returns the input schema of the Action.

tags()

Returns the tags associated with the Action.

to_json()

Returns the Action metadata as a JSON-serializable map.

to_tool()

Converts the Action to an LLM-compatible tool format.

validate_output(output)

@spec validate_output(map()) :: {:ok, map()} | {:error, String.t()}

Validates the output result for the Action.

Examples

iex> defmodule ExampleAction do
...>   use Jido.Action,
...>     name: "example_action",
...>     output_schema: [
...>       result: [type: :string, required: true]
...>     ]
...> end
...> ExampleAction.validate_output(%{result: "test", extra: "ignored"})
{:ok, %{result: "test", extra: "ignored"}}

iex> ExampleAction.validate_output(%{extra: "ignored"})
{:error, "Invalid output for Action: Required key :result not found"}

validate_params(params)

@spec validate_params(map()) :: {:ok, map()} | {:error, String.t()}

Validates the input parameters for the Action.

Examples

iex> defmodule ExampleAction do
...>   use Jido.Action,
...>     name: "example_action",
...>     schema: [
...>       input: [type: :string, required: true]
...>     ]
...> end
...> ExampleAction.validate_params(%{input: "test"})
{:ok, %{input: "test"}}

iex> ExampleAction.validate_params(%{})
{:error, "Invalid parameters for Action: Required key :input not found"}

vsn()

Returns the version of the Action.