OpenAI.Responses.Schema (openai_responses v0.2.1)

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

array(items, opts \\ [])

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
  • 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
  })
)

boolean()

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

integer(opts \\ [])

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
)

nullable(schema)

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

number(opts \\ [])

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
)

object(fields, opts \\ [])

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
  • 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-4o", "Extract the event...", 
  response_format: %{type: "json_schema", schema: schema}
)

string(opts \\ [])

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