@spec array(elements :: schema(), opts :: options()) :: schema()

Defines a array type schema.

Use Zoi.array(elements) to define an array of a specific type:

iex> schema = Zoi.array(Zoi.string())
iex> Zoi.parse(schema, ["hello", "world"])
{:ok, ["hello", "world"]}
iex> Zoi.parse(schema, ["hello", 123])
{:error,
 [
   %Zoi.Error{
     code: :invalid_type,
     message: "invalid type: expected string",
     issue: {"invalid type: expected string", [type: :string]},
     path: [1]
   }
 ]}

Built-in validations for integers include:

Zoi.gt(5)
Zoi.gte(5)
Zoi.lt(2)
Zoi.lte(2)
Zoi.min(2) # alias for `Zoi.gte/1`
Zoi.max(5) # alias for `Zoi.lte/1`
Zoi.length(5)

for coercion, you can pass the :coerce option and Zoi will coerce maps and tuples into the array type:

iex> schema = Zoi.array(Zoi.integer(), coerce: true)
iex> Zoi.parse(schema, %{0 => 1, 1 => 2, 2 => 3})
{:ok, [1, 2, 3]}
iex> Zoi.parse(schema, {1, 2, 3})
{:ok, [1, 2, 3]}

@spec enum(values :: [input()] | keyword(), opts :: options()) :: schema()

Defines an enum type schema.

Use Zoi.enum(values) to define a schema that accepts only specific values:

iex> schema = Zoi.enum([:red, :green, :blue])
iex> Zoi.parse(schema, :red)
{:ok, :red}
iex> Zoi.parse(schema, :yellow)
{:error,
 [
   %Zoi.Error{
     code: :invalid_enum_value,
     message: "invalid enum value: expected one of red, green, blue",
     issue: {"invalid enum value: expected one of %{values}", [type: :enum, values: "red, green, blue"]},
     path: []
   }
 ]}

You can also specify enum as strings:

iex> schema = Zoi.enum(["red", "green", "blue"])
iex> Zoi.parse(schema, "red")
{:ok, "red"}
iex> Zoi.parse(schema, "yellow")
{:error,
 [
   %Zoi.Error{
     code: :invalid_enum_value,
     message: "invalid enum value: expected one of red, green, blue",
     issue: {"invalid enum value: expected one of %{values}", [type: :enum, values: "red, green, blue"]},
     path: []
   }
 ]}

or with key-value pairs:

iex> schema = Zoi.enum([red: "Red", green: "Green", blue: "Blue"])
iex> Zoi.parse(schema, "Red")
{:ok, :red}
iex> Zoi.parse(schema, "Yellow")
{:error,
 [
   %Zoi.Error{
     code: :invalid_enum_value,
     message: "invalid enum value: expected one of Red, Green, Blue",
     issue: {"invalid enum value: expected one of %{values}", [type: :enum, values: "Red, Green, Blue"]},
     path: []
   }
 ]}

Integer values can also be used:

iex> schema = Zoi.enum([1, 2, 3])
iex> Zoi.parse(schema, 1)
{:ok, 1}
iex> Zoi.parse(schema, 4)
{:error,
 [
   %Zoi.Error{
     code: :invalid_enum_value,
     message: "invalid enum value: expected one of 1, 2, 3",
     issue: {"invalid enum value: expected one of %{values}", [type: :enum, values: "1, 2, 3"]},
     path: []
   }
 ]}

And Integers with key-value pairs also is allowed:

iex> schema = Zoi.enum([one: 1, two: 2, three: 3])
iex> Zoi.parse(schema, 1)
{:ok, :one}
iex> Zoi.parse(schema, 4)
{:error,
 [
   %Zoi.Error{
     code: :invalid_enum_value,
     message: "invalid enum value: expected one of 1, 2, 3",
     issue: {"invalid enum value: expected one of %{values}", [type: :enum, values: "1, 2, 3"]},
     path: []
   }
 ]}

You can also specify the :coerce option to allow coercion for both key and value of the enum:

iex> schema = Zoi.enum([one: 1, two: 2, three: 3], coerce: true)
iex> Zoi.parse(schema, 1)
{:ok, :one}
iex> Zoi.parse(schema, :one)
{:ok, :one}
iex> Zoi.parse(schema, "1")
{:error,
 [
   %Zoi.Error{
     code: :invalid_enum_value,
     message: "invalid enum value: expected one of 1, 2, 3",
     issue: {"invalid enum value: expected one of %{values}", [type: :enum, values: "1, 2, 3"]},
     path: []
   }
 ]}
iex> Zoi.parse(schema, "one")
{:error,
 [
   %Zoi.Error{
     code: :invalid_enum_value,
     message: "invalid enum value: expected one of 1, 2, 3",
     issue: {"invalid enum value: expected one of %{values}", [type: :enum, values: "1, 2, 3"]},
     path: []
   }
 ]}

@spec extend(schema1 :: schema(), schema2 :: schema(), opts :: options()) :: schema()

Extends two object type schemas into one. This function merges the fields of two object schemas. If there are overlapping fields, the fields from the second schema will override those from the first.

Example

iex> user = Zoi.object(%{name: Zoi.string()})
iex> role = Zoi.object(%{role: Zoi.enum([:admin,:user])})
iex> user_with_role = Zoi.extend(user, role)
iex> Zoi.parse(user_with_role, %{name: "Alice", role: :admin})
{:ok, %{name: "Alice", role: :admin}}

@spec keyword(fields :: keyword(), opts :: options()) :: schema()

Defines a keyword list type schema.

iex> schema = Zoi.keyword(name: Zoi.string(), age: Zoi.integer())
iex> Zoi.parse(schema, [name: "Alice", age: 30])
{:ok, [name: "Alice", age: 30]}
iex> Zoi.parse(schema, %{name: "Alice", age: 30})
{:error,
 [
   %Zoi.Error{
     code: :invalid_type,
     message: "invalid type: expected keyword list",
     issue: {"invalid type: expected keyword list", [type: :keyword]},
     path: []
   }
 ]}

By default, unrecognized keys will be removed from the parsed data. If you want to not allow unrecognized keys, use the :strict option:

iex> schema = Zoi.keyword([name: Zoi.string()], strict: true)
iex> Zoi.parse(schema, [name: "Alice", age: 30])
{:error,
 [
   %Zoi.Error{
     code: :unrecognized_key,
     message: "unrecognized key: 'age'",
     issue: {"unrecognized key: '%{key}'", [key: :age]},
     path: []
   }
 ]}

All fields are optional by default in keyword lists, but you can make them required by using Zoi.required/1:

iex> schema = Zoi.keyword([name: Zoi.string() |> Zoi.required()])
iex> Zoi.parse(schema, [])
{:error,
 [
   %Zoi.Error{
     code: :required,
     message: "is required",
     issue: {"is required", [key: :name]},
     path: [:name]
   }
 ]}

Flexible keys and values

You can also define a keyword schema that accepts non structured keys, by just declaring the value type:

iex> schema = Zoi.keyword(Zoi.string())
iex> Zoi.parse(schema, [a: "hello", b: "world"])
{:ok, [a: "hello", b: "world"]}

@spec list(elements :: schema(), opts :: options()) :: schema()

alias for Zoi.array/2

@spec map(opts :: options()) :: schema()

Defines a map type schema with Zoi.any() type.

This type is the same as creating the following map:

Zoi.map(Zoi.any(), Zoi.any())

@spec map(key :: schema(), type :: schema(), opts :: options()) :: schema()

Defines a map type schema.

Example

iex> schema = Zoi.map(Zoi.string(), Zoi.integer())
iex> Zoi.parse(schema, %{"a" => 1, "b" => 2})
{:ok, %{"a" => 1, "b" => 2}}
iex> Zoi.parse(schema, %{"a" => "1", "b" => 2})
{:error,
 [
   %Zoi.Error{
     code: :invalid_type,
     message: "invalid type: expected integer",
     issue: {"invalid type: expected integer", [type: :integer]},
     path: ["a"]
   }
 ]}

@spec object(fields :: map(), opts :: options()) :: schema()

Defines a object type schema.

Use Zoi.object(fields) to define complex objects with nested schemas:

iex> user_schema = Zoi.object(%{
...> name: Zoi.string() |> Zoi.min(2) |> Zoi.max(100),
...> age: Zoi.integer() |> Zoi.min(18) |> Zoi.max(120),
...> email: Zoi.email()
...> })
iex> Zoi.parse(user_schema, %{name: "Alice", age: 30, email: "alice@email.com"})
{:ok, %{name: "Alice", age: 30, email: "alice@email.com"}}

By default all fields are required, but you can make them optional by using Zoi.optional/1:

iex> user_schema = Zoi.object(%{
...> name: Zoi.string() |> Zoi.optional(),
...> age: Zoi.integer() |> Zoi.optional(),
...> email: Zoi.email() |> Zoi.optional()
...> })
iex> Zoi.parse(user_schema, %{name: "Alice"})
{:ok, %{name: "Alice"}}

By default, unrecognized keys will be removed from the parsed data. If you want to not allow unrecognized keys, use the :strict option:

iex> schema = Zoi.object(%{name: Zoi.string()}, strict: true)
iex> Zoi.parse(schema, %{name: "Alice", age: 30})
{:error,
 [
   %Zoi.Error{
     code: :unrecognized_key,
     message: "unrecognized key: 'age'",
     issue: {"unrecognized key: '%{key}'", [key: :age]},
     path: []
   }
 ]}

String keys and Atom keys

Objects can be declared using string keys too, this would set the expectation that the param data is also using string keys:

iex> schema = Zoi.object(%{"name" => Zoi.string()})
iex> Zoi.parse(schema, %{"name" => "Alice"})
{:ok, %{"name" => "Alice"}}
iex> Zoi.parse(schema, %{name: "Alice"})
{:error,
 [
   %Zoi.Error{
     code: :required,
     message: "is required",
     issue: {"is required", [key: "name"]},
     path: ["name"]
   }
 ]}

It's possible coerce the keys to atoms using the :coerce option:

iex> schema = Zoi.object(%{name: Zoi.string()}, coerce: true)
iex> Zoi.parse(schema, %{"name" => "Alice"})
{:ok, %{name: "Alice"}}

Which will automatically convert string keys to atom keys.

Nullable vs Optional fields

The Zoi.optional/1 function makes a field optional, meaning it can be omitted from the input data. If the field is not present, it will not be included in the parsed result. The Zoi.nullable/1 function allows a field to be nil, meaning it can be explicitly set to nil in the input data. If the field is set to nil, it will be included in the parsed result as nil.

iex> schema = Zoi.object(%{name: Zoi.string() |> Zoi.optional(), age: Zoi.integer() |> Zoi.nullable()})
iex> Zoi.parse(schema, %{name: "Alice", age: nil})
{:ok, %{name: "Alice", age: nil}}
iex> Zoi.parse(schema, %{name: "Alice"})
{:error,
 [
   %Zoi.Error{
     code: :required,
     message: "is required",
     issue: {"is required", [key: :age]},
     path: [:age]
   }
 ]}

Optional vs Default fields

There are two options to define the behaviour of a field being optional and with a default value:

1. If the field is not present in the input data OR nil, it will be included in the parsed result with the default value.
2. If the field not present in the input data, it will not be included on the parsed result. If the value is nil, it will be included in the parsed result with the default value.

The order you encapsulate the type matters, to implement the first option, the encapsulation should be Zoi.default(Zoi.optional(type, default_value)):

iex> schema = Zoi.object(%{name: Zoi.default(Zoi.optional(Zoi.string()), "default value")})
iex> Zoi.parse(schema, %{})
{:ok, %{name: "default value"}}
iex> Zoi.parse(schema, %{name: nil})
{:ok, %{name: "default value"}}

The second option is implemented by encapsulating the type as Zoi.optional(Zoi.default(type, default_value)):

iex> schema = Zoi.object(%{name: Zoi.optional(Zoi.default(Zoi.string(), "default value"))})
iex> Zoi.parse(schema, %{})
{:ok, %{}}
iex> Zoi.parse(schema, %{name: nil})
{:ok, %{name: "default value"}}

Required definition

By default, all fields are required and if the field is absent in the input data, a validation error will be raised. You can customize absent values in your object definition, defining what values should be considered absent using the :empty_values option:

iex> schema = Zoi.object(%{name: Zoi.string()}, empty_values: [nil, ""])
iex> Zoi.parse(schema, %{name: ""})
{:error,
 [
   %Zoi.Error{
     code: :required,
     message: "is required",
     issue: {"is required", [key: :name]},
     path: [:name]
   }
 ]}

@spec struct(module :: module(), fields :: map(), opts :: options()) :: schema()

Defines a struct type schema. This type is similar to Zoi.object/2, but it is specifically designed to work with Elixir structs.

Example

defmodule MyApp.User do
  defstruct [:name, :age, :email]
end

schema = Zoi.struct(MyApp.User, %{
  name: Zoi.string() |> Zoi.min(2) |> Zoi.max(100),
  age: Zoi.integer() |> Zoi.min(18) |> Zoi.max(120),
  email: Zoi.email()
})
Zoi.parse(schema, %MyApp.User{name: "Alice", age: 30, email: "alice@email.com"})
#=> {:ok, %MyApp.User{name: "Alice", age: 30, email: "alice@email.com"}}
Zoi.parse(schema, %{})
#=> {:error, "invalid type: must be a struct"}

By default, all fields are required, but you can make them optional by using Zoi.optional/1:

schema = Zoi.struct(MyApp.User, %{
  name: Zoi.string() |> Zoi.optional(),
  age: Zoi.integer() |> Zoi.optional(),
  email: Zoi.email() |> Zoi.optional()
})
Zoi.parse(schema, %MyApp.User{name: "Alice"})
#=> {:ok, %MyApp.User{name: "Alice"}}

You can also parse maps into structs by enabling the :coerce option:

schema = Zoi.struct(MyApp.User, %{
  name: Zoi.string(),
  age: Zoi.integer(),
  email: Zoi.email()
}, coerce: true)
Zoi.parse(schema, %{name: "Alice", age: 30, email: "alice@email.com"})
#=> {:ok, %MyApp.User{name: "Alice", age: 30, email: "alice@email.com"}}
# Also with string keys
Zoi.parse(schema, %{"name" => "Alice", "age" => 30, "email" => "alice@email.com"})
#=> {:ok, %MyApp.User{name: "Alice", age: 30, email: "alice@email.com"}}

@spec tuple(fields :: tuple(), opts :: options()) :: schema()

Defines a tuple type schema.

Use Zoi.tuple(fields) to define a tuple with specific types for each element:

iex> schema = Zoi.tuple({Zoi.string(), Zoi.integer()})
iex> Zoi.parse(schema, {"hello", 42})
{:ok, {"hello", 42}}
iex> Zoi.parse(schema, {"hello", "world"})
{:error,
 [
   %Zoi.Error{
     code: :invalid_type,
     message: "invalid type: expected integer",
     issue: {"invalid type: expected integer", [type: :integer]},
     path: [1]
   }
 ]}