Omni.Schema (Omni v1.4.0)

Builders and validation for JSON Schema maps.

Each builder returns a plain map following JSON Schema conventions. Property keys are preserved as-is — use atoms for idiomatic Elixir, and JSON serialisation handles stringification on the wire.

Option keywords accept snake_case and are normalized to camelCase JSON Schema keywords automatically (e.g. min_length: becomes minLength). Keys without a known mapping pass through unchanged.

Example

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

Custom validators

For schemas that need richer semantics than the built-in Peri-backed validator provides — $ref resolution, oneOf/allOf combinators, custom casting — implement the Omni.Schema.Adapter behaviour and pass a {module, state} tuple anywhere a schema is accepted. See Omni.Schema.Adapter for a worked JSV example.

This module is itself the default Omni.Schema.Adapter — to_schema/1 and validate/2 both implement the behaviour for raw JSON Schema maps, and dispatch to the relevant adapter when given an adapter tuple.

Summary

Types

t()

A schema accepted anywhere Omni takes a JSON Schema. Either a raw map, or a {module, state} tuple where module implements Omni.Schema.Adapter.

Functions

any_of(schemas, opts \\ [])

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

array(opts)

Builds a JSON Schema array type.

array(items, opts \\ [])

Builds a JSON Schema array with the given items schema.

boolean(opts \\ [])

Builds a JSON Schema boolean type.

enum(values, opts \\ [])

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

integer(opts \\ [])

Builds a JSON Schema integer type.

number(opts \\ [])

Builds a JSON Schema number type.

object(opts)

Builds a JSON Schema object type.

object(properties, opts \\ [])

Builds a JSON Schema object with the given properties map.

string(opts \\ [])

Builds a JSON Schema string type.

to_schema(schema)

Returns the JSON Schema map sent on the wire for the given schema.

update(schema, opts)

Merges additional options into an existing schema map.

validate(schema, input)

Validates input against a schema.

Types

t()

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

A schema accepted anywhere Omni takes a JSON Schema. Either a raw map, or a {module, state} tuple where 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 on the wire for the given schema.

When the schema is a raw map, returns it unchanged. When it is a {module, state} adapter tuple, calls module.to_schema(state).

Implements the Omni.Schema.Adapter behaviour for raw maps; delegates to the named module for adapter tuples.

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.

When the schema is a {module, state} adapter tuple, dispatches to the adapter's validate/2. When it is a raw map, runs the built-in validator (Peri-backed via Peri.from_json_schema/1).

The built-in validator enforces JSON Schema constraints including types, required fields, string constraints (minLength, maxLength, pattern, format), numeric constraints (minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf), array constraints (minItems, maxItems, uniqueItems), enums, const literals, union types, and anyOf/oneOf/allOf combinators.

Property key types are preserved: atom-keyed schemas validate and cast string-keyed JSON input back to atom keys, so validated output uses the same key types as the schema definition.

Returns {:ok, validated} or {:error, message} with a human-readable error string.