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
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
A schema, as taken wherever Omni takes one.
A JSON Schema map, or a {module, state} tuple whose module implements
Omni.Schema.Adapter.
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.
A map is returned unchanged. An adapter tuple gives its module's
to_schema/1.
Merges additional options into an existing schema map.
Schema.string() |> Schema.update(min_length: 1, max_length: 100)
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, andformatwhen it isemailoruri - numbers:
minimum,maximum,exclusiveMinimum,exclusiveMaximum,multipleOf - arrays:
minItems,maxItems,uniqueItems enumandconstanyOf, andoneOfas if it wereanyOfallOfover object schemas that don't define the same property twice$refto 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.