OpenAI.Responses.Schema (OpenAI.Responses v0.8.2)

Helper module for defining structured output schemas and function calling tools.

Converts simple Elixir syntax into JSON Schema format for structured outputs and function parameters.

Array Support (New in 0.6.0)

Arrays can now be used at the root level of schema definitions. The library automatically handles OpenAI's requirement that the root level must be an object by wrapping arrays in a temporary object structure and unwrapping them in the response.

Examples

Structured Output Schema with Object

iex> Responses.Schema.build_output(%{
...>   name: {:string, description: "The name of the user"},
...>   username: {:string, description: "The username of the user. Must start with @", pattern: "^@[a-zA-Z0-9_]+$"},
...>   email: {:string, description: "The email of the user", format: "email"}
...> })
%{
  "name" => "data",
  "type" => "json_schema",
  "strict" => true,
  "schema" => %{
    "type" => "object",
    "properties" => %{
      "name" => %{
        "type" => "string",
        "description" => "The name of the user"
      },
      "username" => %{
        "type" => "string",
        "description" => "The username of the user. Must start with @",
        "pattern" => "^@[a-zA-Z0-9_]+$"
      },
      "email" => %{
        "type" => "string",
        "description" => "The email of the user",
        "format" => "email"
      }
    },
    "additionalProperties" => false,
    "required" => ["name", "username", "email"]
  }
}

Structured Output Schema with Array at Root

iex> Responses.Schema.build_output({:array, %{
...>   title: :string,
...>   completed: :boolean,
...>   priority: {:integer, minimum: 1, maximum: 5}
...> }})
%{
  "name" => "data",
  "type" => "json_schema",
  "strict" => true,
  "schema" => %{
    "type" => "object",
    "properties" => %{
      "items" => %{
        "type" => "array",
        "items" => %{
          "type" => "object",
          "properties" => %{
            "title" => %{"type" => "string"},
            "completed" => %{"type" => "boolean"},
            "priority" => %{"type" => "integer", "minimum" => 1, "maximum" => 5}
          },
          "additionalProperties" => false,
          "required" => ["completed", "priority", "title"]
        }
      }
    },
    "additionalProperties" => false,
    "required" => ["items"]
  }
}

When using array schemas, the response will be automatically unwrapped so that response.parsed contains the array directly, not wrapped in an object.

Function Calling Tool

iex> Responses.Schema.build_function("get_weather", "Get current temperature for a given location.", %{
...>   location: {:string, description: "City and country e.g. Bogotá, Colombia"}
...> })
%{
  "name" => "get_weather",
  "type" => "function",
  "strict" => true,
  "description" => "Get current temperature for a given location.",
  "parameters" => %{
    "type" => "object",
    "properties" => %{
      "location" => %{
        "type" => "string",
        "description" => "City and country e.g. Bogotá, Colombia"
      }
    },
    "additionalProperties" => false,
    "required" => ["location"]
  }
}

Summary

Functions

build_function(name, description, parameters)

Builds a function calling tool schema.

build_output(fields)

Builds a structured output schema from a simple Elixir map or keyword list format.

Functions

build_function(name, description, parameters)

Builds a function calling tool schema.

Parameters

name - The function name
description - A description of what the function does
parameters - A map or keyword list of parameter definitions (same format as build_output/1)

Example

iex> build_function("get_weather", "Get weather for a location", %{
...>   location: {:string, description: "City name"},
...>   units: {:string, enum: ["celsius", "fahrenheit"], description: "Temperature units"}
...> })

build_output(fields)

Builds a structured output schema from a simple Elixir map or keyword list format.

The input should be a map or keyword list where:

Keys are field names (atoms)
Values are either:
- A single atom like :string, :number, :boolean, etc.
- A tuple like {:string, description: "...", pattern: "..."}
- For arrays: {:array, :string} or {:array, %{field: :type}}

When using keyword lists, the order of fields is preserved in the required array. When using maps, fields are sorted alphabetically in the required array.

If the root schema is an array, it will be automatically wrapped in an object to comply with OpenAI's Structured Outputs requirements.