OpenAI.Responses.Schema (openai_responses v0.3.2)
Utilities for defining structured output schemas for OpenAI responses.
This module provides a simple, idiomatic Elixir way to define JSON schemas that can be used with the OpenAI Responses API to ensure structured outputs.
Simple Usage
For simple types without constraints, you can use atoms directly:
# Using atoms for simple types
schema = OpenAI.Responses.Schema.object(%{
name: :string,
age: :integer,
is_active: :boolean,
scores: {:array, :number}
})
For types with constraints or additional options, use the corresponding functions:
# Using functions for types with constraints
schema = OpenAI.Responses.Schema.object(%{
username: OpenAI.Responses.Schema.string(min_length: 3),
rating: OpenAI.Responses.Schema.number(minimum: 0, maximum: 5)
})
Summary
Functions
Creates an array schema definition.
Creates a boolean schema definition.
Creates an integer schema definition with optional constraints.
Creates a nullable schema definition.
Creates a number schema definition with optional constraints.
Creates an object schema definition from a map of field specifications.
Creates a string schema definition with optional constraints.
Functions
Creates an array schema definition.
Parameters
items
- The schema for items in the array. Can be:- An atom (
:string
,:number
,:integer
,:boolean
) for simple types - A schema map created by other Schema functions
- An atom (
opts
- Optional parameters:min_items
- Minimum number of items:max_items
- Maximum number of items
Examples
# Array of strings (simple)
participants_schema = {:array, :string}
# or
participants_schema = OpenAI.Responses.Schema.array(:string)
# Array of strings with constraints
tags_schema = OpenAI.Responses.Schema.array(:string, min_items: 1, max_items: 5)
# Array of objects
steps_schema = OpenAI.Responses.Schema.array(
OpenAI.Responses.Schema.object(%{
explanation: :string,
output: :string
})
)
Creates a boolean schema definition.
For a simple boolean, you can use the atom :boolean
directly
in object/2
or array/2
instead of calling this function.
Examples
# Boolean field (in object definition)
is_active_field = :boolean
# Or using the function
is_active_field = OpenAI.Responses.Schema.boolean()
Creates an integer schema definition with optional constraints.
For a simple integer without constraints, you can use the atom :integer
directly
in object/2
or array/2
instead of calling this function.
Parameters
opts
- Optional parameters:minimum
- Minimum value:maximum
- Maximum value:exclusive_minimum
- Whether minimum is exclusive:exclusive_maximum
- Whether maximum is exclusive:multiple_of
- Integer must be multiple of this value
Examples
# Simple integer (in object definition)
count_field = :integer
# Integer with range
age_field = OpenAI.Responses.Schema.integer(
minimum: 0,
maximum: 120
)
# Positive integer
quantity_field = OpenAI.Responses.Schema.integer(
minimum: 1
)
Creates a nullable schema definition.
Parameters
schema
- The base schema or atom type
Examples
# Nullable string
middle_name_field = OpenAI.Responses.Schema.nullable(:string)
# Nullable object
address_field = OpenAI.Responses.Schema.nullable(
OpenAI.Responses.Schema.object(%{
street: :string,
city: :string,
zip: :string
})
)
Creates a number schema definition with optional constraints.
For a simple number without constraints, you can use the atom :number
directly
in object/2
or array/2
instead of calling this function.
Parameters
opts
- Optional parameters:minimum
- Minimum value:maximum
- Maximum value:exclusive_minimum
- Whether minimum is exclusive:exclusive_maximum
- Whether maximum is exclusive:multiple_of
- Number must be multiple of this value
Examples
# Simple number (in object definition)
price_field = :number
# Number with range
rating_field = OpenAI.Responses.Schema.number(
minimum: 0,
maximum: 5
)
# Positive number
quantity_field = OpenAI.Responses.Schema.number(
minimum: 0,
exclusive_minimum: true
)
# Multiple of 0.5
half_step_field = OpenAI.Responses.Schema.number(
multiple_of: 0.5
)
Creates an object schema definition from a map of field specifications.
Parameters
fields
- A map where keys are field names and values are type specifications. Type specifications can be:- Atoms (
:string
,:number
,:integer
,:boolean
) for simple types - Tuples like
{:array, type}
for simple arrays - Schema maps created by other Schema functions
- Atoms (
opts
- Optional parameters:name
- Name for the root schema
Examples
# Simple object schema with atom types
schema = OpenAI.Responses.Schema.object(%{
name: :string,
date: :string,
participants: {:array, :string}
}, name: "event")
# Object schema with mixed simple and complex types
schema = OpenAI.Responses.Schema.object(%{
name: :string,
email: OpenAI.Responses.Schema.string(format: "email"),
age: :integer,
interests: {:array, :string}
})
# Use in a response
{:ok, response} = OpenAI.Responses.create("gpt-4.1", "Extract the event...",
response_format: %{type: "json_schema", schema: schema}
)
Creates a string schema definition with optional constraints.
For a simple string without constraints, you can use the atom :string
directly
in object/2
or array/2
instead of calling this function.
Parameters
opts
- Optional parameters:format
- String format (e.g., "date-time", "email"):pattern
- Regex pattern:min_length
- Minimum length:max_length
- Maximum length:enum
- List of allowed values
Examples
# Simple string (in object definition)
name_field = :string
# Email string
email_field = OpenAI.Responses.Schema.string(format: "email")
# String with length constraints
username_field = OpenAI.Responses.Schema.string(
min_length: 3,
max_length: 20
)
# String with allowed values (enum)
status_field = OpenAI.Responses.Schema.string(
enum: ["pending", "active", "completed"]
)