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{message: "invalid type: must be a 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)

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{message: "invalid option, must be one of: red, green, blue"}]}

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{message: "invalid option, must be one of: red, green, blue"}]}

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{message: "invalid option, must be one of: Red, Green, Blue"}]}

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{message: "invalid option, must be one of: 1, 2, 3"}]}

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{message: "invalid value for enum"}]}
{:error, [%Zoi.Error{message: "invalid option, must be one of: 1, 2, 3"}]}

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

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{message: "invalid type: must be a keyword list"}]}

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{message: "unrecognized key: 'age'"}]}

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())

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{message: "invalid type: must be an integer", path: ["a"]}]}

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{message: "unrecognized key: 'age'"}]}

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{message: "is required", 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{message: "is required", 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"}}

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{message: "invalid type: must be an integer", path: [1]}]}