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

The 3-arity form accepts a keyword list with three opts:

• :type — base Peri type that all choices must satisfy. The validator checks the value against the base type before the membership check, and the JSON Schema encoder surfaces it as the "type" keyword alongside "enum" (e.g. {:enum, [1, 2, 3], type: :integer} → %{"type" => "integer", "enum" => [1, 2, 3]}). Without :type, validation is membership-only and JSON Schema output is a bare {"enum": [...]}.
• :error — custom error message; same form as the constraint-list error: opt (static string or MFA returning a string).
• :gen — generator override; same form as the constraint-list gen: opt. | {:literal, value} | Value must exactly match | {:literal, :active} | | {:either, {type1, type2}} | Value matches either type | {:either, {:string, :integer}} | | {:oneof, types} | Value matches one of types | {:oneof, [:string, :integer, :atom]} |

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