# `Gemini.Types.Schema`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/types/schema.ex#L1)

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

# `schema_type`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/types/schema.ex#L59)

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

# `t`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/types/schema.ex#L62)

```elixir
@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

# `array`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/types/schema.ex#L266)

```elixir
@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`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/types/schema.ex#L249)

```elixir
@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`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/types/schema.ex#L347)

```elixir
@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`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/types/schema.ex#L211)

```elixir
@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`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/types/schema.ex#L114)

```elixir
@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`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/types/schema.ex#L230)

```elixir
@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`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/types/schema.ex#L288)

```elixir
@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`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/types/schema.ex#L191)

```elixir
@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`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/types/schema.ex#L313)

```elixir
@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"}

---

*Consult [api-reference.md](api-reference.md) for complete listing*