refactor: improve nested path resolution and add boolean schema support

The settings loader now handles nested environment variables more robustly,
addressing cases where underscores are used as delimiters for fields that
contain underscores. A new prefix-based matching strategy in the decoder
accurately resolves these paths by sorting fields by length.

The JSON schema resolver is updated to support boolean schemas. This allows
true or false to be used as definitions and ensures they are resolved
correctly. When merging metadata into a boolean schema, the resolver now
wraps the elements in an allOf structure to preserve schema validity.

Further changes include:
- Addition of a comprehensive settings_loader.exs example.
- Validation that the :input option in Settings.load/2 is a map.
- Graceful handling of non-map values during definition extraction.
- New tests for boolean schema resolution and underscore delimiters.
- Support for both definitions and $defs in the reference resolver.

Author: nshkrdotcom

examples/README.md

@@ -67,6 +67,7 @@ bash examples/run_all.sh --fail-fast
 | `readme_examples.exs` | Verifies README snippets by executing them as a consistency check | `mix run` |
 | `root_schema.exs` | Root-level validation for non-map data (arrays, unions, primitives) | `mix run` |
 | `runtime_schema.exs` | Dynamic schema creation and validation at runtime | `elixir` |
+| `settings_loader.exs` | End-to-end environment settings loading: prefixes, overrides, nested exploded keys, and error handling | `mix run` |
 | `type_adapter.exs` | TypeAdapter-based runtime validation, coercion, dumping, and batch use | `elixir` |
 | `wrapper_models.exs` | Wrapper model patterns for single-field validation and reuse | `elixir` |
 
@@ -89,7 +90,8 @@ bash examples/run_all.sh --fail-fast
 15. `field_metadata_dspy.exs`
 16. `conditional_recursive_validation.exs`
 17. `advanced_config.exs`
-18. `readme_examples.exs`
+18. `settings_loader.exs`
+19. `readme_examples.exs`
 
 ## Notes
 

examples/settings_loader.exs

@@ -0,0 +1,188 @@
+# Comprehensive Exdantic.Settings example
+# Run with: mix run examples/settings_loader.exs
+
+Mix.Task.run("compile")
+
+defmodule SettingsLoaderExample do
+  alias Exdantic.Settings
+
+  defmodule DatabaseConfig do
+    use Exdantic
+
+    schema do
+      field(:host, :string, required: true)
+      field(:pool_size, :integer, default: 5)
+    end
+  end
+
+  defmodule AppConfig do
+    use Exdantic, define_struct: true
+
+    schema "Settings schema for a sample service" do
+      field(:name, :string, default: "exdantic-service")
+      field(:port, :integer, default: 4000)
+      field(:enabled, :boolean, default: true)
+      field(:mode, :atom, default: :safe)
+      field(:database, DatabaseConfig, required: true)
+      field(:tags, {:array, :string}, default: [])
+      field(:database_url, :string, required: true, extra: %{"env" => "DATABASE_URL"})
+    end
+  end
+
+  def run do
+    IO.puts("=== Exdantic.Settings Comprehensive Example ===")
+    IO.puts("")
+
+    successful_load_demo()
+    input_precedence_demo()
+    empty_string_behavior_demo()
+    case_collision_demo()
+    invalid_json_demo()
+    from_system_env_demo()
+  end
+
+  defp successful_load_demo do
+    IO.puts("1) Successful load with prefixing, nested merge, and absolute override")
+    env = baseline_env()
+
+    {:ok, settings} =
+      Settings.load(AppConfig,
+        env: env,
+        env_prefix: "APP_",
+        env_nested_delimiter: "__",
+        allow_atoms: :existing,
+        ignore_empty: true
+      )
+
+    IO.inspect(settings, label: "Loaded settings")
+    IO.puts("Derived key APP_DATABASE_URL is ignored because DATABASE_URL override wins.")
+    IO.puts("")
+  end
+
+  defp input_precedence_demo do
+    IO.puts("2) Explicit input has higher precedence than env values")
+    env = baseline_env()
+
+    {:ok, settings} =
+      Settings.load(AppConfig,
+        env: env,
+        env_prefix: "APP_",
+        allow_atoms: :existing,
+        input: %{port: 4200, database: %{pool_size: 20}}
+      )
+
+    IO.inspect(settings, label: "Merged settings")
+    IO.puts("")
+  end
+
+  defp empty_string_behavior_demo do
+    IO.puts("3) ignore_empty controls whether empty strings are treated as absent")
+
+    env =
+      baseline_env()
+      |> Map.put("APP_NAME", "")
+
+    {:ok, ignored_empty} =
+      Settings.load(AppConfig,
+        env: env,
+        env_prefix: "APP_",
+        allow_atoms: :existing,
+        ignore_empty: true
+      )
+
+    {:ok, kept_empty} =
+      Settings.load(AppConfig,
+        env: env,
+        env_prefix: "APP_",
+        allow_atoms: :existing,
+        ignore_empty: false
+      )
+
+    IO.inspect(ignored_empty.name, label: "ignore_empty: true")
+    IO.inspect(kept_empty.name, label: "ignore_empty: false")
+    IO.puts("")
+  end
+
+  defp case_collision_demo do
+    IO.puts("4) Case-insensitive collisions are rejected")
+
+    env =
+      baseline_env()
+      |> Map.merge(%{"app_port" => "1111", "APP_PORT" => "2222"})
+
+    case Settings.load(AppConfig, env: env, env_prefix: "APP_", allow_atoms: :existing) do
+      {:ok, _} ->
+        IO.puts("Unexpected success")
+
+      {:error, errors} ->
+        IO.inspect(errors, label: "Collision errors")
+    end
+
+    IO.puts("")
+  end
+
+  defp invalid_json_demo do
+    IO.puts("5) Structured fields require JSON values")
+
+    env =
+      baseline_env()
+      |> Map.put("APP_TAGS", "not-json")
+
+    case Settings.load(AppConfig, env: env, env_prefix: "APP_", allow_atoms: :existing) do
+      {:ok, _} ->
+        IO.puts("Unexpected success")
+
+      {:error, errors} ->
+        IO.inspect(errors, label: "JSON decode errors")
+    end
+
+    IO.puts("")
+  end
+
+  defp from_system_env_demo do
+    IO.puts("6) from_system_env/2 usage")
+
+    env_vars = %{
+      "APP_DATABASE" => ~s({"host":"db.system","pool_size":7}),
+      "APP_PORT" => "4300",
+      "APP_MODE" => "safe",
+      "DATABASE_URL" => "ecto://system@localhost/system_db"
+    }
+
+    previous = Enum.into(env_vars, %{}, fn {k, _} -> {k, System.get_env(k)} end)
+
+    Enum.each(env_vars, fn {k, v} -> System.put_env(k, v) end)
+
+    try do
+      {:ok, settings} =
+        Settings.from_system_env(AppConfig,
+          env_prefix: "APP_",
+          allow_atoms: :existing
+        )
+
+      IO.inspect(settings, label: "System env settings")
+    after
+      Enum.each(previous, fn
+        {k, nil} -> System.delete_env(k)
+        {k, v} -> System.put_env(k, v)
+      end)
+    end
+
+    IO.puts("")
+  end
+
+  defp baseline_env do
+    %{
+      "APP_PORT" => "4100",
+      "APP_ENABLED" => "0",
+      "APP_MODE" => "safe",
+      "APP_DATABASE" => ~s({"host":"db.local","pool_size":5}),
+      "APP_DATABASE__POOL_SIZE" => "12",
+      "APP_TAGS" => ~s(["settings","example"]),
+      "APP_DATABASE_URL" => "ecto://derived@localhost/from_prefix",
+      "DATABASE_URL" => "ecto://override@localhost/main_db"
+    }
+  end
+end
+
+SettingsLoaderExample.run()

lib/exdantic/json_schema/resolver.ex

@@ -7,7 +7,7 @@ defmodule Exdantic.JsonSchema.Resolver do
   LLM providers (OpenAI, Anthropic, etc.).
   """
 
-  @type schema :: map()
+  @type schema :: map() | boolean()
   @type resolver_context :: %{
           definitions: %{optional(String.t()) => schema()},
           max_depth: non_neg_integer(),
@@ -56,7 +56,10 @@ defmodule Exdantic.JsonSchema.Resolver do
       }
   """
   @spec resolve_references(schema(), resolution_options()) :: schema()
-  def resolve_references(schema, opts \\ []) do
+  def resolve_references(schema, opts \\ [])
+  def resolve_references(schema, _opts) when is_boolean(schema), do: schema
+
+  def resolve_references(schema, opts) when is_map(schema) do
     max_depth = Keyword.get(opts, :max_depth, 10)
     preserve_titles = Keyword.get(opts, :preserve_titles, true)
     preserve_descriptions = Keyword.get(opts, :preserve_descriptions, true)
@@ -118,7 +121,10 @@ defmodule Exdantic.JsonSchema.Resolver do
       }
   """
   @spec flatten_schema(schema(), keyword()) :: schema()
-  def flatten_schema(schema, opts \\ []) do
+  def flatten_schema(schema, opts \\ [])
+  def flatten_schema(schema, _opts) when is_boolean(schema), do: schema
+
+  def flatten_schema(schema, opts) when is_map(schema) do
     max_depth = Keyword.get(opts, :max_depth, 5)
     inline_simple_refs = Keyword.get(opts, :inline_simple_refs, true)
     preserve_complex_refs = Keyword.get(opts, :preserve_complex_refs, false)
@@ -206,10 +212,11 @@ defmodule Exdantic.JsonSchema.Resolver do
 
   # Private helper functions
 
-  @spec extract_definitions(schema()) :: map()
-  defp extract_definitions(schema) do
-    Map.get(schema, "definitions", %{})
-    |> Map.merge(Map.get(schema, "$defs", %{}))
+  @spec extract_definitions(map()) :: map()
+  defp extract_definitions(schema) when is_map(schema) do
+    definitions = schema |> Map.get("definitions", %{}) |> ensure_map()
+    defs = schema |> Map.get("$defs", %{}) |> ensure_map()
+    Map.merge(definitions, defs)
   end
 
   @spec resolve_schema_part(schema(), resolver_context(), non_neg_integer()) :: schema()
@@ -289,7 +296,7 @@ defmodule Exdantic.JsonSchema.Resolver do
       nil ->
         {:error, "Definition not found: #{def_name}"}
 
-      definition when is_map(definition) ->
+      definition when is_map(definition) or is_boolean(definition) ->
         if Map.has_key?(context.visited, def_name) do
           {:error, "Circular reference detected: #{def_name}"}
         else
@@ -311,12 +318,45 @@ defmodule Exdantic.JsonSchema.Resolver do
     {:error, "Unsupported reference format: #{ref}"}
   end
 
-  defp merge_schema_properties(resolved, additional_props, context) do
+  defp merge_schema_properties(resolved, additional_props, context) when is_map(resolved) do
     resolved
     |> merge_if_preserve_titles(additional_props, context)
     |> merge_if_preserve_descriptions(additional_props, context)
   end
 
+  defp merge_schema_properties(resolved, additional_props, context) do
+    metadata = build_preserved_metadata(additional_props, context)
+
+    if map_size(metadata) == 0 do
+      resolved
+    else
+      %{"allOf" => [resolved, metadata]}
+    end
+  end
+
+  defp build_preserved_metadata(additional_props, context) do
+    metadata = %{}
+
+    metadata =
+      if context.preserve_titles do
+        case Map.fetch(additional_props, "title") do
+          {:ok, title} -> Map.put(metadata, "title", title)
+          :error -> metadata
+        end
+      else
+        metadata
+      end
+
+    if context.preserve_descriptions do
+      case Map.fetch(additional_props, "description") do
+        {:ok, description} -> Map.put(metadata, "description", description)
+        :error -> metadata
+      end
+    else
+      metadata
+    end
+  end
+
   defp merge_if_preserve_titles(schema, additional_props, context) do
     if context.preserve_titles and Map.has_key?(additional_props, "title") do
       Map.put(schema, "title", additional_props["title"])
@@ -334,12 +374,17 @@ defmodule Exdantic.JsonSchema.Resolver do
   end
 
   @spec remove_definitions(schema()) :: schema()
-  defp remove_definitions(schema) do
+  defp remove_definitions(schema) when is_boolean(schema), do: schema
+
+  defp remove_definitions(schema) when is_map(schema) do
     schema
     |> Map.delete("definitions")
     |> Map.delete("$defs")
   end
 
+  defp ensure_map(value) when is_map(value), do: value
+  defp ensure_map(_value), do: %{}
+
   @spec inline_simple_types(schema(), boolean()) :: schema()
   defp inline_simple_types(
          %{"type" => "object", "properties" => properties} = schema,

lib/exdantic/settings.ex

@@ -34,15 +34,14 @@ defmodule Exdantic.Settings do
           {:ok, map() | struct()} | {:error, [Exdantic.Error.t()]}
   def load(schema_module, opts \\ []) when is_atom(schema_module) do
     with :ok <- ensure_schema_module(schema_module),
+         {:ok, input} <- resolve_input(opts),
          {:ok, env_map} <-
            Env.normalize_env_map(
              resolve_env(opts),
              Keyword.get(opts, :case_sensitive, false)
            ),
          {:ok, env_values} <-
            Loader.load_env_values(schema_module, env_map, opts) do
-      input = Keyword.get(opts, :input, %{})
-
       merged =
         env_values
         |> DeepMerge.deep_merge(input)
@@ -73,6 +72,23 @@ defmodule Exdantic.Settings do
     end
   end
 
+  defp resolve_input(opts) do
+    case Keyword.get(opts, :input, %{}) do
+      input when is_map(input) ->
+        {:ok, input}
+
+      other ->
+        {:error,
+         [
+           Exdantic.Error.new(
+             [],
+             :type,
+             "expected :input to be a map, got #{inspect(other)}"
+           )
+         ]}
+    end
+  end
+
   defp ensure_schema_module(schema_module) do
     if Code.ensure_loaded?(schema_module) and function_exported?(schema_module, :__schema__, 1) do
       :ok