Types Reference

Peri provides a comprehensive set of built-in types for schema validation.

Basic Types

Time Types

Collection Types

String Constraints

Integer Constraints

Float Constraints

Choice Types

Modifiers

Schema Metadata

The {:meta, type, opts} wrapper attaches documentation/tooling info to a field without affecting validation. Blessed keys: :doc, :title, :description, :example/:examples, :deprecated. The JSON Schema encoder also recognises :default, :format, :pattern, :read_only, :write_only, :content_encoding, and :content_media_type (see pages/json_schema.md). User keys are preserved opaquely for non-encoder tooling.

defschema accepts schema-level meta opts (any non-validation key), exposed via the generated __schema_meta__/1:

defmodule MySchemas do
  import Peri

  defschema :user, %{
    email: {:meta, {:required, :string}, doc: "Login email", example: "a@b.io"},
    age: {:meta, {:integer, gte: 0}, description: "Years"}
  }, title: "User", description: "Account holder"
end

MySchemas.__schema_meta__(:user)
# => [title: "User", description: "Account holder"]

Tagged Unions (:multi)

{:multi, dispatch_field, branches} is sugar for a discriminated union: the value is dispatched on dispatch_field, then validated against the matching branch schema. Errors localize to the chosen branch, so failures read as shape.radius: invalid rather than "didn't match any of N schemas".

%{
  shape: {:multi, :type, %{
    "circle" => %{type: {:required, :string}, radius: {:required, :float}},
    "rect"   => %{type: {:required, :string}, w: {:required, :float}, h: {:required, :float}}
  }}
}

A missing dispatch field, or a value not present in branches, surfaces as a clear validation error listing the known tags. JSON Schema export emits oneOf plus a discriminator annotation; data generation samples a branch and merges the dispatch tag into the generated value.

For untagged "any of these types" semantics, use {:oneof, types} instead.

Custom Validation

Custom Error Messages

Override the default error template for any field using the error: opt in its options list. Accepted forms: a static string, or an MFA {mod, fun, args} that receives the %Peri.Error{} prepended to args and returns a string.

defmodule MyApp.Schemas do
  import Peri

  defmodule Msgs do
    def email_msg(%Peri.Error{content: ctx}), do: "email is invalid (#{inspect(ctx)})"
  end

  defschema :user, %{
    age:   {:integer, gte: 18, error: "must be adult"},
    email: {:required, :string, [error: {Msgs, :email_msg, []}]}
  }
end

For i18n, post-process the error list with Peri.Error.traverse_errors/2, which walks nested errors and replaces each leaf message with the callback's return value:

{:error, errors} = MyApp.Schemas.user(%{age: 10})

Peri.Error.traverse_errors(errors, fn err ->
  Gettext.dgettext(MyAppWeb.Gettext, "errors", err.message, err.content || %{})
end)

The MFA / static override fires first; traverse_errors/2 runs over whatever message remains (overridden or default). No hard dependency on Gettext — the callback is opaque.

Schema Transformation (Peri.walk/2)

Peri.walk/2 is a depth-first rewrite over a schema tree — a building block for derivations like "make every field optional" or "drop internal-only fields from a public DTO". The callback is invoked on every subtree, and its contract depends on context:

Map keys, constraint option lists (e.g. [gte: 18, error: "..."]), :enum members, :literal values, :ref names, :multi tags, callbacks, and transforms are not visited — only sub-schemas and field entries are.

Make every field optional

Peri.walk(schema, fn
  {:required, t} -> {:cont, t}
  {:required, t, _opts} -> {:cont, t}
  other -> {:cont, other}
end)

Strip private fields from a DTO

Peri.walk(internal_schema, fn
  {:field, k, _v} when k in [:internal_id, :secret_token] -> :drop
  other -> {:cont, other}
end)

Rename a field

Peri.walk(schema, fn
  {:field, :email, v} -> {:cont, {:field, :login, v}}
  other -> {:cont, other}
end)

Compose with other tools

The result of walk/2 is a plain Peri schema, ready to feed to Peri.validate/2, Peri.to_json_schema/1, Peri.generate/1, or another walker pass.

Generator Overrides (gen: opt)

Constrained types like {:string, {:regex, …}} or {:integer, gt: 1_000_000} can be slow to generate via Peri.generate/1 because StreamData's default strategy is rejection sampling. Supply a gen: opt with a custom generator to skip rejection altogether:

Accepted positions:

%{
  # multi-options on a constrained primitive
  age:    {:integer, gte: 18, lte: 120, gen: {MyApp.Gens, :age, []}},

  # required wrapper
  login:  {:required, :string, [gen: {MyApp.Gens, :login}]},

  # meta wrapper (combines with docs/examples)
  email:  {:meta, {:required, {:string, {:regex, ~r/@/}}},
                  doc: "Login email",
                  gen: {MyApp.Gens, :email, []}}
}

Without an override, Peri.generate/1 falls back to chaining StreamData.filter/2 for each constraint.

Simple User Schema

%{
  name: {:required, :string},
  age: {:integer, {:gte, 0}},
  email: {:required, {:string, {:regex, ~r/@/}}},
  role: {:enum, [:admin, :user]}
}

Complex Nested Schema

%{
  user: %{
    profile: {:required, %{
      name: {:required, :string},
      bio: {:string, {:max, 500}}
    }},
    preferences: {:map, :string, :boolean},
    tags: {:list, :string}
  }
}