Gemini.Types.Schema (GeminiEx v0.8.2)

JSON Schema type for defining function parameters in Gemini tool calling.

This module provides a structured way to define parameter schemas for function declarations. It supports all standard JSON Schema types and converts to the Gemini API format (with UPPERCASE type names).

Supported Types

:string - Text values
:integer - Whole numbers
:number - Decimal numbers
:boolean - True/false values
:array - Lists of items
:object - Nested objects with properties

Examples

# Simple string parameter
schema = Schema.string("User's name")

# Object with required fields
schema = Schema.object(%{
  "name" => Schema.string("Person's name"),
  "age" => Schema.integer("Person's age"),
  "email" => Schema.string("Email address")
}, required: ["name", "email"])

# Array of strings
schema = Schema.array(Schema.string("Tag"), "List of tags")

# Complex nested schema
address = Schema.object(%{
  "street" => Schema.string("Street address"),
  "city" => Schema.string("City"),
  "zip" => Schema.string("ZIP code")
})

person = Schema.object(%{
  "name" => Schema.string("Full name"),
  "address" => address
})

API Conversion

Use to_api_map/1 to convert to the Gemini API format:

schema = Schema.string("A name")
Schema.to_api_map(schema)
#=> %{"type" => "STRING", "description" => "A name"}

Summary

Types

schema_type()

t()

JSON Schema definition for function parameters

Functions

array(items, description \\ nil, opts \\ [])

Create an array schema with item schema.

boolean(description \\ nil, opts \\ [])

Create a boolean schema with optional description.

from_api_map(api_map)

Parse a Schema from Gemini API map format.

integer(description \\ nil, opts \\ [])

Create an integer schema with optional description.

new(opts)

Create a new Schema with the given options.

number(description \\ nil, opts \\ [])

Create a number (float/decimal) schema with optional description.

object(properties, opts \\ [])

Create an object schema with properties.

string(description \\ nil, opts \\ [])

Create a string schema with optional description.

to_api_map(schema)

Convert a Schema struct to Gemini API map format.

Types

schema_type()

@type schema_type() :: :string | :integer | :number | :boolean | :array | :object

t()

@type t() :: %Gemini.Types.Schema{
  default: term(),
  description: String.t() | nil,
  enum: [String.t()] | nil,
  format: String.t() | nil,
  items: t() | map() | nil,
  max_items: non_neg_integer() | nil,
  maximum: number() | nil,
  min_items: non_neg_integer() | nil,
  minimum: number() | nil,
  nullable: boolean() | nil,
  pattern: String.t() | nil,
  properties: %{required(String.t()) => t() | map()} | nil,
  required: [String.t()] | nil,
  type: schema_type()
}

JSON Schema definition for function parameters

Functions

array(items, description \\ nil, opts \\ [])

@spec array(t() | map(), String.t() | nil, keyword()) :: t()

Create an array schema with item schema.

Examples

Schema.array(Schema.string("Tag"), "List of tags")
Schema.array(Schema.integer("Score"), "Test scores", min_items: 1)

boolean(description \\ nil, opts \\ [])

@spec boolean(
  String.t() | nil,
  keyword()
) :: t()

Create a boolean schema with optional description.

Examples

Schema.boolean("Is active")
Schema.boolean("Feature flag")

from_api_map(api_map)

@spec from_api_map(map()) :: {:ok, t()} | {:error, String.t()}

Parse a Schema from Gemini API map format.

Examples

api_map = %{"type" => "STRING", "description" => "A name"}
{:ok, schema} = Schema.from_api_map(api_map)

integer(description \\ nil, opts \\ [])

@spec integer(
  String.t() | nil,
  keyword()
) :: t()

Create an integer schema with optional description.

Examples

Schema.integer("User's age")
Schema.integer("Count", minimum: 0, maximum: 100)

new(opts)

@spec new(keyword()) :: {:ok, t()} | {:error, String.t()}

Create a new Schema with the given options.

Options

:type (required) - The schema type (:string, :integer, :number, :boolean, :array, :object)
:description - Human-readable description
:enum - List of allowed values for strings
:items - Schema for array items (when type is :array)
:properties - Map of property schemas (when type is :object)
:required - List of required property names
:nullable - Whether the value can be null
:format - Format hint (e.g., "date-time", "email")
:minimum - Minimum value for numbers
:maximum - Maximum value for numbers
:min_items - Minimum array length
:max_items - Maximum array length
:pattern - Regex pattern for strings
:default - Default value

Examples

{:ok, schema} = Schema.new(type: :string, description: "A name")

{:ok, schema} = Schema.new(
  type: :object,
  properties: %{
    "name" => %{type: :string},
    "age" => %{type: :integer}
  },
  required: ["name"]
)

number(description \\ nil, opts \\ [])

@spec number(
  String.t() | nil,
  keyword()
) :: t()

Create a number (float/decimal) schema with optional description.

Examples

Schema.number("Price in USD")
Schema.number("Temperature", minimum: -273.15)

object(properties, opts \\ [])

@spec object(
  %{required(String.t()) => t() | map()},
  keyword()
) :: t()

Create an object schema with properties.

Examples

Schema.object(%{
  "name" => Schema.string("Person's name"),
  "age" => Schema.integer("Age")
}, required: ["name"], description: "A person")

string(description \\ nil, opts \\ [])

@spec string(
  String.t() | nil,
  keyword()
) :: t()

Create a string schema with optional description.

Examples

Schema.string("User's name")
Schema.string("Status", enum: ["active", "inactive"])

to_api_map(schema)

@spec to_api_map(t() | map()) :: map()

Convert a Schema struct to Gemini API map format.

The Gemini API uses UPPERCASE type names (STRING, INTEGER, etc.) and camelCase field names.

Examples

schema = Schema.string("A name")
Schema.to_api_map(schema)
#=> %{"type" => "STRING", "description" => "A name"}