OpenAI.Responses.Schema (OpenAI.Responses v0.5.0)

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.

Examples

Structured Output Schema

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

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.