This is beautiful - can replace my hand-rolled version of this now. Thanks for contributing to the ecosystem 
cschmatzler
1
phcurado
v0.6.6 release 
Zoi now supports a metadata option, allowing you to add additional information to your schema, which can be useful for documentation purposes.
iex> schema = Zoi.string(metadata: [id: "1", description: "A simple string"])
iex> Zoi.metadata(schema)
[id: "1", description: "A simple string"]
You can use this feature to create self-documenting schemas, and also creating examples and testing them:
defmodule MyApp.UserSchema do
@schema Zoi.object(
%{
name: Zoi.string() |> Zoi.min(2) |> Zoi.max(100),
age: Zoi.integer() |> Zoi.optional()
},
metadata: [
example: %{name: "Alice", age: 30},
doc: "A user schema with name and optional age",
moduledoc: "Schema representing a user with name and optional age"
]
)
@moduledoc """
#{Zoi.metadata(@schema)[:moduledoc]}
"""
@doc """
#{Zoi.metadata(@schema)[:doc]}
"""
def schema, do: @schema
end
defmodule MyApp.UserSchemaTest do
use ExUnit.Case
alias MyApp.UserSchema
test "example matches schema" do
example = Zoi.metadata(UserSchema.schema())[:example]
assert {:ok, example} == Zoi.parse(UserSchema.schema(), example)
end
end
New refinements added
Zoi.downcase/1validate if a string is in lowercaseZoi.upcase/1validate if a string is in uppercaseZoi.hex/1validate if a string is a valid hexadecimal
1
phcurado
v0.7 release with OpenAPI support
This new version introduces the new Zoi.to_json_schema/1 function, which allows you to convert your Zoi schemas into JSON Schema format. This is useful for generating API documentation and other use cases where JSON Schema is required.
schema = Zoi.object(%{
name: Zoi.string(metadata: [description: "The name of the person"]),
})
Zoi.to_json_schema(schema)
# %{
# "$schema": "https://json-schema.org/draft/2020-12/schema",
# type: :object,
# required: [:name],
# properties: %{name: %{type: :string, description: "The name of the person"}},
# additionalProperties: false
# }
This feature allow us to generate OpenAPI documentation from Zoi schemas, since the 3.1 version is 100% compatible with JSON Schema.
Checkout the Zoi OpenAPI guide for more details, it shows how to use Zoi with the Oaskit library.
I also created a quickstart guide to help you get started with Zoi.
5
phcurado
hey, an easy way to achieve this is with the transform API.
For example, having a schema definition like this:
defmodule MyApp.User do
def schema() do
Zoi.object(%{
name: Zoi.nullable(Zoi.string()),
age: Zoi.integer()
})
|> Zoi.transform(&unset_nil_fields/1)
end
def unset_nil_fields(map) do
map
|> Enum.filter(fn {_k, v} -> v != nil end)
|> Enum.into(%{})
end
end
It will allow nil fields to be removed from the parsed data:
iex> Zoi.parse(MyApp.User.schema(), %{name: nil, age: 30})
{:ok, %{age: 30}}
1
phcurado
v0.8.2 released
Hey everyone, this release brings schema documentation introspection for Zoi.object/2 and Zoi.keyword/2 types.
Example
One common example is when passing maps or keyword lists as parameters in your function, it’s often hard to keep track of what keys are expected and their types.
@spec create_user(map(), keyword()) :: {:ok, User.t()} | {:error, Ecto.Changeset.t()}
def create_user(params, opts \\ []) do
## creating user
end
and overtime you may lose track of what params or opts are being passed. Zoi can help you to give more meaning to these arguments:
@create_user_params Zoi.object(%{
name: Zoi.string(description: "The user first name"),
age: Zoi.integer(description: "The user age") |> Zoi.min(0) |> Zoi.optional(),
email: Zoi.email(description: "The user email")
})
@create_user_opts Zoi.keyword([
skip_checks: Zoi.boolean(description: "Wether to skip validation checks")
])
@doc """
Creates a new user.
Params:
#{Zoi.describe(@create_user_params)}
Options:
#{Zoi.describe(@create_user_opts)}
"""
@spec create_user(
unquote(Zoi.type_spec(@create_user_params)),
unquote(Zoi.type_spec(@create_user_opts))
) :: {:ok, User.t()} | {:error, Ecto.Changeset.t()}
def create_user(params, opts \\ []) do
# parsing params and opts to ensure they conform to the schema
params = Zoi.parse!(@create_user_params, params)
opts = Zoi.parse!(@create_user_opts, opts)
## creating user
end
For library authors, this is a great way to document the expected input schemas for functions, the example above would generate the following documentation:
Creates a new user.
Params:
* `:name` (`t:String.t/0`) - Required. The user first name
* `:age` (`t:integer/0`) - The user
* `:email` (`t:String.t/0`) - Required. The user email
Opts:
* `:skip_checks` (`t:boolean/0`) - Wether to skip validation checks
The doc output was inspired by nimble_options, which offers a format compatible with HexDocs, and users will be able to check each argument and their types directly on the function documentation published in hexdocs.
More details in the oficial docs.
4
phcurado
v0.10 released with Phoenix form support
Hi everyone! I finally released the 0.10 version of Zoi, now you can use your Zoi schemas directly in Phoenix forms.
This release implements the Phoenix.HTML.FormData protocol, which allows you to use Zoi.Context structs as form data sources.
Quick example:
# Define schema inline
@user_schema Zoi.object(%{
name: Zoi.string() |> Zoi.min(3),
email: Zoi.email()
}) |> Zoi.Form.prepare()
# Parse and render (just like changesets!)
ctx = Zoi.Form.parse(@user_schema, params)
form = to_form(ctx, as: :user)
socket |> assign(:form, form)
# Use in your forms
~H"""
<.form for={@form} phx-submit="save">
<.input field={@form[:name]} label="Name" />
<.input field={@form[:email]} label="Email" />
<div>
<.button>Save</.button>
</div>
</.form>
"""
Guides
- Phoenix Forms Integration Guide - Detailed guide on integrating with phoenix
- Localizing Errors with Gettext Guide - For more information on how to localize error messages.
9
jam
Thanks for making this. Looks good. A few questions:
- Do you have any plans for Ecto support? I think it’d be nice to create one schema and then derive any others needed from it, e.g. boundary checks etc.
- Do you plan to support deep partials?
- Wouldn’t it be more Elixir native to only have
mapandlistin place ofobjectandarrayrespectively? I see you havelistas an alias forarray. IMO, seeingobjectandarrayfeels a bit off and maybe they should be deprecated. - Is there a way to globally alias
ZoiasZ?
2
phcurado
Hi @jam
- No plans for now, to be 100% compatible with ecto would be a huge effort, ecto is a different beast. Ecto also offers more specialized functions for your database operations, this would not be something I would add on Zoi. I assume you mean integrating Zoi schemas with Ecto schemas (not changesets), to have a unified definition across both, that is interesting, but not a current goal.
- I plan to add some helpers so you can customise nested schemas, the new Form does this already but I need to generalize the functions. Basically a function that can traverse the nested structure and apply a change to its types.
- In Zoi, the map type represents any key/value structure (like in Elixir), annd object defines a structured schema with specific keys. I dont think object should be deprecated, though I agree the naming feels less native to Elixir.
- No, you can only alias like that inside a module (alias Zoi, as: Z)
2
