Omni.Schema (Omni v2.0.0)

Copy Markdown View Source

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.

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:

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.

Summary

Types

t()

A schema, as taken wherever Omni takes one.

Functions

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

Builds a JSON Schema array type.

Builds a JSON Schema array with the given items schema.

Builds a JSON Schema boolean type.

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

Builds a JSON Schema integer type.

Builds a JSON Schema number type.

Builds a JSON Schema object type.

Builds a JSON Schema object with the given properties map.

Builds a JSON Schema string type.

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

Merges additional options into an existing schema map.

Validates input against a schema.

Types

t()

@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.

Functions

any_of(schemas, opts \\ [])

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

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

array(opts)

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

Builds a JSON Schema array type.

array(items, opts \\ [])

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

Builds a JSON Schema array with the given items schema.

boolean(opts \\ [])

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

Builds a JSON Schema boolean type.

enum(values, opts \\ [])

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

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

integer(opts \\ [])

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

Builds a JSON Schema integer type.

number(opts \\ [])

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

Builds a JSON Schema number type.

object(opts)

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

Builds a JSON Schema object type.

object(properties, opts \\ [])

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

Builds a JSON Schema object with the given properties map.

string(opts \\ [])

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

Builds a JSON Schema string type.

to_schema(schema)

@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(schema, opts)

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

Merges additional options into an existing schema map.

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

validate(schema, input)

@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, 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.