# `Exdantic.JsonSchema.Resolver`
[🔗](https://github.com/nshkrdotcom/exdantic/blob/v0.1.0/lib/exdantic/json_schema/resolver.ex#L1)

Advanced JSON schema reference resolution and manipulation.

This module provides functionality for resolving $ref entries, flattening
nested schemas, and enforcing structured output requirements for various
LLM providers (OpenAI, Anthropic, etc.).

# `resolution_options`

```elixir
@type resolution_options() :: [
  max_depth: non_neg_integer(),
  preserve_titles: boolean(),
  preserve_descriptions: boolean()
]
```

# `resolver_context`

```elixir
@type resolver_context() :: %{
  definitions: %{optional(String.t()) => schema()},
  max_depth: non_neg_integer(),
  preserve_titles: boolean(),
  preserve_descriptions: boolean(),
  visited: %{optional(String.t()) => true}
}
```

# `schema`

```elixir
@type schema() :: map() | boolean()
```

# `enforce_structured_output`

```elixir
@spec enforce_structured_output(
  schema(),
  keyword()
) :: schema()
```

Enforces structured output requirements for specific LLM providers.

## Parameters
  * `schema` - The JSON schema to enforce requirements on
  * `opts` - Provider-specific options

## Options
  * `:provider` - Target provider (:openai, :anthropic, :generic) (default: :generic)
  * `:remove_unsupported` - Remove unsupported features (default: true)
  * `:add_required_fields` - Add required fields for provider (default: true)

## Returns
  * JSON schema compatible with the specified provider

## Examples

    iex> schema = %{"type" => "object", "additionalProperties" => true}
    iex> Exdantic.JsonSchema.Resolver.enforce_structured_output(schema, provider: :openai)
    %{"type" => "object", "additionalProperties" => false}

# `flatten_schema`

```elixir
@spec flatten_schema(
  schema(),
  keyword()
) :: schema()
```

Flattens nested schemas by expanding all references inline.

This is useful for LLM providers that don't support complex reference structures.

## Parameters
  * `schema` - The JSON schema to flatten
  * `opts` - Flattening options

## Options
  * `:max_depth` - Maximum flattening depth (default: 5)
  * `:inline_simple_refs` - Inline simple type references (default: true)
  * `:preserve_complex_refs` - Keep complex object references as-is (default: false)

## Returns
  * Flattened JSON schema

## Examples

    iex> schema = %{
    ...>   "type" => "object",
    ...>   "properties" => %{
    ...>     "items" => %{
    ...>       "type" => "array",
    ...>       "items" => %{"$ref" => "#/definitions/Item"}
    ...>     }
    ...>   },
    ...>   "definitions" => %{
    ...>     "Item" => %{"type" => "string", "minLength" => 1}
    ...>   }
    ...> }
    iex> Exdantic.JsonSchema.Resolver.flatten_schema(schema)
    %{
      "type" => "object",
      "properties" => %{
        "items" => %{
          "type" => "array",
          "items" => %{"type" => "string", "minLength" => 1}
        }
      }
    }

# `optimize_for_llm`

```elixir
@spec optimize_for_llm(
  schema(),
  keyword()
) :: schema()
```

Optimizes a JSON schema for better LLM performance.

## Parameters
  * `schema` - The JSON schema to optimize
  * `opts` - Optimization options

## Options
  * `:remove_descriptions` - Remove verbose descriptions (default: false)
  * `:simplify_unions` - Simplify complex union types (default: true)
  * `:max_properties` - Maximum properties per object (default: nil)

## Returns
  * Optimized JSON schema

## Examples

    iex> schema = %{"type" => "object", "properties" => %{"a" => %{"type" => "string", "description" => "very long description..."}}}
    iex> Exdantic.JsonSchema.Resolver.optimize_for_llm(schema, remove_descriptions: true)
    %{"type" => "object", "properties" => %{"a" => %{"type" => "string"}}}

# `resolve_references`

```elixir
@spec resolve_references(schema(), resolution_options()) :: schema()
```

Recursively resolves all $ref entries in a schema.

## Parameters
  * `schema` - The JSON schema to resolve references in
  * `opts` - Resolution options

## Options
  * `:max_depth` - Maximum resolution depth to prevent infinite recursion (default: 10)
  * `:preserve_titles` - Keep original titles when resolving (default: true)
  * `:preserve_descriptions` - Keep original descriptions when resolving (default: true)

## Returns
  * Resolved JSON schema with all references expanded

## Examples

    iex> schema = %{
    ...>   "type" => "object",
    ...>   "properties" => %{
    ...>     "user" => %{"$ref" => "#/definitions/User"}
    ...>   },
    ...>   "definitions" => %{
    ...>     "User" => %{"type" => "object", "properties" => %{"name" => %{"type" => "string"}}}
    ...>   }
    ...> }
    iex> Exdantic.JsonSchema.Resolver.resolve_references(schema)
    %{
      "type" => "object",
      "properties" => %{
        "user" => %{"type" => "object", "properties" => %{"name" => %{"type" => "string"}}}
      }
    }

---

*Consult [api-reference.md](api-reference.md) for complete listing*