Generate sample data based on Peri schemas using StreamData. Add StreamData to your dependencies to enable Peri.generate/1:

# mix.exs
defp deps do
  [
    {:peri, "~> 0.12.0"}, # x-release-please-version
    {:stream_data, "~> 1.0", only: [:test, :dev]}
  ]
end

Basic Usage

Peri.generate/1 returns {:ok, generator} for a valid schema, or {:error, errors} when schema validation fails. The returned StreamData generator implements Enumerable:

schema = %{
  name: {:required, :string},
  age: {:integer, gte: 18, lte: 120},
  active: :boolean
}

{:ok, generator} = Peri.generate(schema)
Enum.take(generator, 3)

Map fields are optional unless wrapped with {:required, type}. The generator includes optional fields with generated values; required fields are also always included.

Supported Types

Generators are provided for all built-in scalar types:

TypeGenerated values
:anyBounded StreamData terms
:atom, :atom!Alphanumeric atoms
:booleanBooleans
:dateDates from 1970 through 2100
:datetimeUTC datetimes from 1970 through 2100
:durationA finite one-second duration
:floatStreamData floats
:integerStreamData integers
:listLists of at most five terms
:mapEmpty maps
:naive_datetimeNaive datetimes from 1970 through 2100
:pidThe current process PID
:stringAlphanumeric strings
:timeTimes from midnight through 23:59:59

Composite schemas also support constrained lists, typed maps, tuples, enums, literals, :either, :oneof, :multi, refs, defaults, coercions and custom validators. Regex constraints and custom predicates use filtering, which can be slow when only a small fraction of values match.

Schema and Dependent Wrappers

{:schema, type}, {:schema, type, opts} and {:schema, map, {:additional_keys, value_type}} generate from the wrapped schema. Additional-key wrappers generate the declared fields only; random extra keys are not necessary for a valid sample.

The fixed dependent form {:dependent, field, condition, type} generates values from type and does not call condition during generation. Validation still calls the condition with the real root data, so a dependent field should be generated inside its parent map. Dynamic dependent forms such as {:dependent, callback} select their schema at runtime and raise an ArgumentError during generation; generation does not invoke that callback or invent root data.

Constraint-Aware Generation

Integer gt, gte, lt, lte and range constraints use bounded integer generators. Combined bounds are intersected, including inclusive and exclusive edges. Integer multiple_of constraints are combined with integer bounds when the step is an integer. String min and max constraints set generator length bounds; eq generates the exact value. Other constraints, including neq, regex and custom predicates, are applied as filters where needed. Float ranges and float multiple_of retain their existing generator behavior.

schema = %{
  username: {:string, [min: 3, max: 12]},
  score: {:integer, [gt: 0, lte: 100]},
  role: {:enum, [:admin, :user, :guest]},
  tags: {:list, :string}
}

{:ok, generator} = Peri.generate(schema)
samples = Enum.take(generator, 5)
Enum.all?(samples, &(match?({:ok, _}, Peri.validate(schema, &1))))

Property-Based Testing

Use the returned generator with ExUnitProperties:

defmodule UserTest do
  use ExUnit.Case
  use ExUnitProperties

  @schema %{
    name: {:required, :string},
    age: {:integer, [gte: 0, lte: 120]},
    email: {:string, {:regex, ~r/@/}}
  }

  property "generated user data passes validation" do
    {:ok, generator} = Peri.generate(@schema)

    check all user_data <- generator do
      assert {:ok, _} = Peri.validate(@schema, user_data)
    end
  end
end

Transforms

Generation preserves the existing one-argument transform behavior when the transformed value is still valid input for the underlying schema. If the callback raises for a generated value or returns a value that does not satisfy the underlying schema, that sample remains the original valid input. MFA transforms use their value-plus-arguments arity when available. Root-aware two-argument function transforms, and MFA transforms that require a root value, generate the underlying input without calling the callback. Validation then applies the transform with the real root data; generation does not fabricate root data.

Recursive Refs

Ref generation is bounded to five expansions. At the depth limit, an optional recursive ref is represented as nil, which validation treats as absent. A schema whose recursive path is required at every level has no finite valid value; generation raises an ArgumentError rather than yielding an invalid sample. Add an optional base case to recursive schemas when finite sample generation is needed.

Custom Generators (gen:)

For supported gen: options, provide a function that returns a StreamData generator. Accepted forms are {module, function, args}, {module, function} for a zero-arity function, or a zero-arity function:

defmodule MyApp.Gens do
  def adult_age, do: StreamData.integer(18..120)
  def fixed_login, do: StreamData.constant("system")
end

schema = %{
  age: {:integer, [gte: 18, lte: 120, gen: {MyApp.Gens, :adult_age, []}]},
  login: {:required, :string, [gen: {MyApp.Gens, :fixed_login}]}
}

{:ok, generator} = Peri.generate(schema)
Enum.take(generator, 5)

Limitations

  • Regex and custom predicates remain rejection-filtered and can be inefficient for narrow domains.
  • Dynamic dependent schemas need a user-supplied generation strategy.
  • Required-only recursion has no finite base value and is rejected during generation.
  • Generation requires the optional StreamData dependency.

Use generation primarily for tests and development data, and keep generated collection sizes reasonable.