Exdantic.JsonSchema.Resolver (exdantic v0.0.2)

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.).

Summary

Types

resolution_options()

schema()

Functions

enforce_structured_output(schema, opts \\ [])

Enforces structured output requirements for specific LLM providers.

flatten_schema(schema, opts \\ [])

Flattens nested schemas by expanding all references inline.

optimize_for_llm(schema, opts \\ [])

Optimizes a JSON schema for better LLM performance.

resolve_references(schema, opts \\ [])

Recursively resolves all $ref entries in a schema.

Types

resolution_options()

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

schema()

@type schema() :: map()

Functions

enforce_structured_output(schema, opts \\ [])

@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(schema, opts \\ [])

@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(schema, opts \\ [])

@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(schema, opts \\ [])

@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"}}}
  }
}