# `Omni.Schema`
[🔗](https://github.com/aaronrussell/omni/blob/v2.0.0/lib/omni/schema.ex#L1)

Builders and validation for JSON Schema maps.

Schemas describe a tool's input and structured output (the `:output`
option). Each builder returns a plain map in JSON Schema form, so builders
nest, and a map you write by hand works wherever a built one does.

```elixir
iex> Omni.Schema.object(%{
...>   city: Omni.Schema.string(description: "City name"),
...>   temp: Omni.Schema.number()
...> }, required: [:city])
%{
  type: "object",
  properties: %{
    city: %{type: "string", description: "City name"},
    temp: %{type: "number"}
  },
  required: [:city]
}
```

## Keys

Property keys are kept as you write them. Write atoms, and validated data
(a tool's input, `response.output`) comes back with atom keys, whatever
the model sent.

## Options

Every builder takes options, which become keywords of the schema:
`description:`, `minimum:`, `default:` and so on. Keywords that JSON
Schema spells in camelCase can be written in snake_case:

```elixir
Omni.Schema.string(min_length: 1, max_length: 100)
#=> %{type: "string", minLength: 1, maxLength: 100}
```

These are `min_length`, `max_length`, `min_items`, `max_items`,
`unique_items`, `multiple_of`, `exclusive_minimum`, `exclusive_maximum`,
`additional_properties`, `min_properties`, `max_properties` and
`pattern_properties`. Any other key passes through unchanged.

## Other validators

Omni's own validator is deliberately small. It is meant for schemas of
simple shape: objects, arrays and constrained values, which is what
models handle best. `validate/2` lists what it checks and where it stops.

For schemas that need more, such as exact `oneOf`, recursive references
or checked date formats, or to use a JSON Schema library you already
have, pass an `Omni.Schema.Adapter` tuple, `{module, state}`, wherever a
schema is taken.

# `t`

```elixir
@type t() :: map() | {module(), term()}
```

A schema, as taken wherever Omni takes one.

A JSON Schema map, or a `{module, state}` tuple whose module implements
`Omni.Schema.Adapter`.

# `any_of`

```elixir
@spec any_of(
  [map()],
  keyword()
) :: map()
```

Builds a JSON Schema `anyOf`: valid when at least one subschema matches.

# `array`

```elixir
@spec array(keyword()) :: map()
```

Builds a JSON Schema array type.

# `array`

```elixir
@spec array(
  map(),
  keyword()
) :: map()
```

Builds a JSON Schema array with the given `items` schema.

# `boolean`

```elixir
@spec boolean(keyword()) :: map()
```

Builds a JSON Schema boolean type.

# `enum`

```elixir
@spec enum(
  list(),
  keyword()
) :: map()
```

Builds a JSON Schema enum: a list of allowed literal values.

# `integer`

```elixir
@spec integer(keyword()) :: map()
```

Builds a JSON Schema integer type.

# `number`

```elixir
@spec number(keyword()) :: map()
```

Builds a JSON Schema number type.

# `object`

```elixir
@spec object(keyword()) :: map()
```

Builds a JSON Schema object type.

# `object`

```elixir
@spec object(
  map(),
  keyword()
) :: map()
```

Builds a JSON Schema object with the given `properties` map.

# `string`

```elixir
@spec string(keyword()) :: map()
```

Builds a JSON Schema string type.

# `to_schema`

```elixir
@spec to_schema(t()) :: map()
```

Returns the JSON Schema map sent to the provider for a schema.

A map is returned unchanged. An adapter tuple gives its module's
`to_schema/1`.

# `update`

```elixir
@spec update(
  map(),
  keyword()
) :: map()
```

Merges additional options into an existing schema map.

```elixir
Schema.string() |> Schema.update(min_length: 1, max_length: 100)
```

# `validate`

```elixir
@spec validate(t(), term()) :: {:ok, term()} | {:error, String.t()}
```

Validates input against a schema.

An adapter tuple is validated by its module's `validate/2`. A map is
validated by Omni's own validator, built on
[Peri](https://hex.pm/packages/peri), which checks:

- types, union types and required fields
- strings: `minLength`, `maxLength`, `pattern`, and `format` when it is
  `email` or `uri`
- numbers: `minimum`, `maximum`, `exclusiveMinimum`, `exclusiveMaximum`,
  `multipleOf`
- arrays: `minItems`, `maxItems`, `uniqueItems`
- `enum` and `const`
- `anyOf`, and `oneOf` as if it were `anyOf`
- `allOf` over object schemas that don't define the same property twice
- `$ref` to one of the schema's own `$defs`, but not recursively

Everything else in the schema is sent to the model but not checked,
including other formats such as `date` and `date-time`, and keywords
such as `not` and `if`. Properties the schema doesn't list are dropped
from the validated data, not rejected, unless `additionalProperties` is
`true`. A schema the validator can't convert, such as `allOf` over
strings, fails every input with a message saying so. When a schema needs
any of these, use an `Omni.Schema.Adapter`.

Validated data has the schema's keys: a schema written with atom keys
turns string-keyed JSON back into atom keys. This follows `properties`
and `items` only. An object reached through `anyOf`, `oneOf`, `allOf` or
`$ref` keeps its string keys.

Returns `{:ok, validated}`, or `{:error, message}` with a message fit to
show the model.

---

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