Zoi.ISO (Zoi v0.12.1)

This module defines schemas for ISO time, date, and datetime formats, along with transformations to convert them into Elixir's native types.

It includes built-in transformations to convert ISO time, date, and datetime strings into %Time{}, %Date{}, and %DateTime{} structs.

Zoi main API have Zoi.datetime/1, Zoi.date/1, Zoi.naive_datetime/1 and Zoi.time/1 functions. These functions validates if the input strings comply with the Elixir date formats. Use the Zoi.ISO module when you just want to validate ISO strings without the need to convert them to native types.

Summary

Functions

do_transform(arg1, input, arg3)

Basic Types

date(opts \\ [])

Defines a date type schema.

datetime(opts \\ [])

Defines a datetime type schema.

naive_datetime(opts \\ [])

Defines a naive datetime type schema.

time(opts \\ [])

Defines a time type schema.

Transforms

to_date_struct(schema)

Converts Zoi.ISO.date() to %Date{} struct.

to_datetime_struct(schema)

Converts Zoi.ISO.datetime() to %DateTime{} struct.

to_naive_datetime_struct(schema)

Converts Zoi.ISO.naive_datetime() to %NaiveDateTime{} struct.

to_time_struct(schema)

Converts Zoi.ISO.time() to %Time{} struct.

Functions

do_transform(arg1, input, arg3)

Basic Types

date(opts \\ [])

Defines a date type schema.

Example

iex> schema = Zoi.ISO.date()
iex> Zoi.parse(schema, "2025-08-07")
{:ok, "2025-08-07"}
iex> Zoi.parse(schema, "2025-02-30")
{:error,
 [
   %Zoi.Error{
     code: :invalid_type,
     message: "invalid type: expected ISO date",
     issue: {"invalid type: expected ISO date", [type: :iso_date]},
     path: []
   }
 ]}

Options

:description (String.t/0) - Description of the schema.
:example (term/0) - Example value for the schema.
:metadata (keyword/0) - Additional metadata for the schema.
:error (String.t/0) - Custom error message for validation.

datetime(opts \\ [])

Defines a datetime type schema.

Example

iex> schema = Zoi.ISO.datetime()
iex> Zoi.parse(schema, "2025-08-07T10:04:22+03:00")
{:ok, "2025-08-07T10:04:22+03:00"}

iex> schema = Zoi.ISO.datetime()
iex> Zoi.parse(schema, 1754646043)
{:error,
 [
   %Zoi.Error{
     code: :invalid_type,
     message: "invalid type: expected ISO datetime",
     issue: {"invalid type: expected ISO datetime", [type: :iso_datetime]},
     path: []
   }
 ]}

Options

:description (String.t/0) - Description of the schema.
:example (term/0) - Example value for the schema.
:metadata (keyword/0) - Additional metadata for the schema.
:error (String.t/0) - Custom error message for validation.

naive_datetime(opts \\ [])

Defines a naive datetime type schema.

Example

iex> schema = Zoi.ISO.naive_datetime()
iex> Zoi.parse(schema, "2025-08-07T10:04:22")
{:ok, "2025-08-07T10:04:22"}

iex> schema = Zoi.ISO.naive_datetime()
iex> Zoi.parse(schema, 1754646043)
{:error,
 [
   %Zoi.Error{
     code: :invalid_type,
     message: "invalid type: expected ISO naive datetime",
     issue: {"invalid type: expected ISO naive datetime", [type: :iso_naive_datetime]},
     path: []
   }
 ]}

Options

:description (String.t/0) - Description of the schema.
:example (term/0) - Example value for the schema.
:metadata (keyword/0) - Additional metadata for the schema.
:error (String.t/0) - Custom error message for validation.

time(opts \\ [])

Defines a time type schema.

Example

iex> schema = Zoi.ISO.time()
iex> Zoi.parse(schema, "12:34:56")
{:ok, "12:34:56"}
iex> Zoi.parse(schema, "25:00:00")
{:error,
 [
   %Zoi.Error{
     code: :invalid_type,
     message: "invalid type: expected ISO time",
     issue: {"invalid type: expected ISO time", [type: :iso_time]},
     path: []
   }
 ]}

Options

:description (String.t/0) - Description of the schema.
:example (term/0) - Example value for the schema.
:metadata (keyword/0) - Additional metadata for the schema.
:error (String.t/0) - Custom error message for validation.

Transforms

to_date_struct(schema)

Converts Zoi.ISO.date() to %Date{} struct.

Example

iex> schema = Zoi.ISO.date() |> Zoi.ISO.to_date_struct()
iex> Zoi.parse(schema, "2025-08-07")
{:ok, ~D[2025-08-07]}

to_datetime_struct(schema)

Converts Zoi.ISO.datetime() to %DateTime{} struct.

Example

iex> schema = Zoi.ISO.datetime() |> Zoi.ISO.to_datetime_struct()
iex> Zoi.parse(schema, "2025-08-07T10:04:22+03:00")
{:ok, ~U[2025-08-07 07:04:22Z]}

to_naive_datetime_struct(schema)

Converts Zoi.ISO.naive_datetime() to %NaiveDateTime{} struct.

Example

iex> schema = Zoi.ISO.naive_datetime() |> Zoi.ISO.to_naive_datetime_struct()
iex> Zoi.parse(schema, "2025-08-07T10:04:22")
{:ok, ~N[2025-08-07 10:04:22]}

to_time_struct(schema)

Converts Zoi.ISO.time() to %Time{} struct.

Example

iex> schema = Zoi.ISO.time() |> Zoi.ISO.to_time_struct()
iex> Zoi.parse(schema, "12:34:56")
{:ok, ~T[12:34:56]}