Canonical schema definition for stage describe/1 callback.

This module defines the structure and validation rules for stage schemas. All stages implementing the Crucible.Stage behaviour must return a schema conforming to this specification from their describe/1 callback.

Schema Structure

A valid schema must contain:

• :name - Stage identifier (atom, required)
• :description - Human-readable description (non-empty string, required)
• :required - List of required option keys (list of atoms, required)
• :optional - List of optional option keys (list of atoms, required)
• :types - Map of option keys to type specifications (map, required)

Optional fields:

• :__schema_version__ - Schema version (semver string, e.g., "1.0.0")
• :defaults - Default values for optional fields (map)
• :version - Stage version (semver string)
• :__extensions__ - Domain-specific metadata (map)

Type Specifications

Supported type specs:

• Primitives: :string, :integer, :float, :boolean, :atom, :map, :list, :module, :any
• Struct: {:struct, Module}
• Enum: {:enum, [values]}
• Typed list: {:list, inner_type}
• Typed map: {:map, key_type, value_type}
• Function: {:function, arity}
• Union: {:union, [types]}
• Tuple: {:tuple, [types]}

Example

%{
  __schema_version__: "1.0.0",
  name: :my_stage,
  description: "Processes data according to configuration",
  required: [:input_path],
  optional: [:format, :batch_size],
  types: %{
    input_path: :string,
    format: {:enum, [:json, :csv]},
    batch_size: :integer
  },
  defaults: %{
    format: :json,
    batch_size: 100
  }
}