Jido.Action.Schema (Jido Action v2.2.1)

View Source

Unified schema validation interface supporting NimbleOptions, Zoi, and JSON Schema maps.

This adapter provides a consistent API for:

  • Schema validation
  • Key introspection
  • Error formatting
  • JSON Schema generation (for AI tools)

JSON Schema Maps

Plain JSON Schema maps (e.g. produced by json_spec) are supported as a pass-through format. When a JSON Schema map is used:

  • Parameters are not validated at runtime (the schema is for the LLM only)
  • known_keys/1 extracts atom keys from "properties" without creating new atoms
  • to_json_schema/1 returns the map unchanged

Summary

Types

t()

Functions

format_error(error, context, module)

Formats validation errors into Jido.Action.Error structs.

known_keys(schema)

Extracts all known keys from a schema.

schema_type(schema)

Detects the type of schema.

to_json_schema(schema)

Converts a schema to JSON Schema format for AI tools.

to_json_schema(schema, opts)

Converts a schema to JSON Schema format for AI tools with optional strictness controls.

validate(schema, data)

Validates data against a schema.

validate_config_schema(value, opts \\ [])

Validates a schema value for use in configuration.

Types

t()

@type t() :: NimbleOptions.schema() | struct() | map() | []

Functions

format_error(error, context, module)

@spec format_error(term(), String.t(), module()) ::
  Jido.Action.Error.InvalidInputError.t()

Formats validation errors into Jido.Action.Error structs.

Parameters

  • error - The error from validation (NimbleOptions.ValidationError, Zoi.Error, or list)
  • context - Context string describing where the error occurred
  • module - The module where the error occurred

Returns

  • Jido.Action.Error.InvalidInputError.t() - Formatted error struct

known_keys(schema)

@spec known_keys(t()) :: [atom()]

Extracts all known keys from a schema.

Parameters

  • schema - NimbleOptions schema or Zoi schema

Returns

  • List of atom keys defined in the schema

schema_type(schema)

@spec schema_type(t()) :: :nimble | :zoi | :json_schema | :empty | :unknown

Detects the type of schema.

Returns :nimble for NimbleOptions keyword list schemas, :zoi for Zoi schemas, :json_schema for plain JSON Schema maps, :empty for empty lists, or :unknown for unsupported types.

to_json_schema(schema)

@spec to_json_schema(t()) :: map()

Converts a schema to JSON Schema format for AI tools.

For NimbleOptions schemas, converts to OpenAI-compatible JSON Schema. For Zoi schemas, uses Zoi's built-in JSON Schema conversion.

Parameters

  • schema - NimbleOptions schema or Zoi schema

Returns

  • Map representing the JSON Schema

to_json_schema(schema, opts)

@spec to_json_schema(
  t(),
  keyword()
) :: map()

Converts a schema to JSON Schema format for AI tools with optional strictness controls.

Options

  • :strict - when true, recursively sets additionalProperties: false on all object schemas (default: false)

validate(schema, data)

@spec validate(t(), map() | keyword()) :: {:ok, map()} | {:error, term()}

Validates data against a schema.

For NimbleOptions schemas, returns {:ok, map()} with validated data as a map. For Zoi schemas, returns {:ok, struct()} with the validated struct. For empty schemas, returns the data unchanged.

Parameters

  • schema - NimbleOptions schema (keyword list) or Zoi schema
  • data - Data to validate (map or keyword list)

Returns

  • {:ok, validated_data} - Validation succeeded
  • {:error, error} - Validation failed

validate_config_schema(value, opts \\ [])

@spec validate_config_schema(
  term(),
  keyword()
) :: :ok | {:error, String.t()}

Validates a schema value for use in configuration.

Used during compilation to ensure schema configuration is valid.

Parameters

  • value - The schema value to validate
  • _opts - Options (unused, for Zoi refine compatibility)

Returns

  • :ok - Schema is valid
  • {:error, message} - Schema is invalid