Controls whether loopback addresses are allowed in URLs.

See url/1 for more details.

Constraint phone numbers to a limited set of country codes.

See phone/1 for more details.

Restricts which ports are allowed in a URL.

See url/1 for more details.

Enforces that the URL has one of the given allowed schemes.

See url/1 for more details.

Creates a type that accepts any value.

Examples

iex> Z.any()
iex> |> Z.parse("hello")
{:ok, "hello"}

iex> Z.any()
iex> |> Z.parse(42)
{:ok, 42}

iex> Z.any()
iex> |> Z.parse(%{foo: "bar"})
{:ok, %{foo: "bar"}}

iex> Z.any()
iex> |> Z.optional()
iex> |> Z.parse(nil)
{:ok, nil}

Useful in maps where a field can accept any value:

iex> Z.map(%{name: Z.string(), metadata: Z.any()})
iex> |> Z.parse(%{name: "Alice", metadata: %{role: "admin", tags: [1, 2, 3]}})
{:ok, %{name: "Alice", metadata: %{role: "admin", tags: [1, 2, 3]}}}

Supports transform and refine effects:

iex> Z.any()
iex> |> Z.transform(&inspect/1)
iex> |> Z.parse({:ok, 42})
{:ok, "{:ok, 42}"}

It can be converted into json schema:

iex> Z.any()
iex> |> Z.describe("Arbitrary metadata.")
iex> |> Z.json_schema()
%{
  "description" => "Arbitrary metadata."
}

Creates an atom type.

Examples

iex> Z.atom()
iex> |> Z.parse(:foo)
{:ok, :foo}

iex> Z.atom()
iex> |> Z.parse("bar")
iex> |> unwrap_issue_message()
"expected type atom, got string"

With coerce: true, it converts strings to existing atoms only:

iex> Z.atom()
iex> |> Z.parse("foo", coerce: true)
{:ok, :foo}

iex> Z.atom()
iex> |> Z.parse("this_atom_does_not_exist", coerce: true)
iex> |> unwrap_issue_message()
"atom 'this_atom_does_not_exist' does not exist"

With coerce: :unsafe, it converts any string to an atom:

iex> Z.atom()
iex> |> Z.parse("some_new_atom", coerce: :unsafe)
{:ok, :some_new_atom}

It can be converted into json schema:

iex> Z.atom()
iex> |> Z.describe("A status atom.")
iex> |> Z.example(:active)
iex> |> Z.json_schema()
%{
  "type" => "string",
  "description" => "A status atom.",
  "examples" => ["active"]
}

Alias to boolean/0.

Creates a boolean type.

Examples

iex> Z.boolean()
iex> |> Z.parse(true)
{:ok, true}

iex> Z.boolean()
iex> |> Z.parse("yes")
iex> |> unwrap_issue_message()
"expected type boolean, got string"

It can be coerced from boolean-like values:

iex> Z.boolean()
iex> |> Z.parse(1, coerce: true)
{:ok, true}

iex> Z.boolean()
iex> |> Z.parse(0, coerce: true)
{:ok, false}

iex> Z.boolean()
iex> |> Z.parse("true", coerce: true)
{:ok, true}

iex> Z.boolean()
iex> |> Z.parse("false", coerce: true)
{:ok, false}

iex> Z.boolean()
iex> |> Z.parse("on", coerce: true)
{:ok, true}

iex> Z.boolean()
iex> |> Z.parse("off", coerce: true)
{:ok, false}

iex> Z.boolean()
iex> |> Z.parse("enabled", coerce: true)
{:ok, true}

iex> Z.boolean()
iex> |> Z.parse("disabled", coerce: true)
{:ok, false}

iex> Z.boolean()
iex> |> Z.parse("yes", coerce: true)
{:ok, true}

iex> Z.boolean()
iex> |> Z.parse("no", coerce: true)
{:ok, false}

Coercion fails for non-boolean-like strings:

iex> Z.boolean()
iex> |> Z.parse("maybe", coerce: true)
iex> |> unwrap_issue_message()
"expected a boolean-like string ('true', 'enabled', 'on', 'yes', 'false', 'disabled', 'off' or 'no'), got 'maybe'"

It can be converted into json schema:

iex> Z.boolean()
iex> |> Z.describe("A boolean flag.")
iex> |> Z.example(true)
iex> |> Z.json_schema()
%{
  "type" => "boolean",
  "description" => "A boolean flag.",
  "examples" => [true]
}

Wraps the parsed value in a branded tuple.

Examples

iex> Z.string()
iex> |> Z.branded(:name)
iex> |> Z.parse("Rafael")
{:ok, {:name, "Rafael"}}

Enables automatic canonicalization for CIDR notation.

When enabled, non-canonical CIDR notation (where the IP is not the network address) is automatically converted to canonical form.

See cidr/1 for more details.

Creates a CIDR notation type for IPv4 or IPv6 network addresses.

Examples

iex> Z.cidr()
iex> |> Z.parse("192.168.0.0/24")
{:ok, "192.168.0.0/24"}

iex> Z.cidr()
iex> |> Z.parse("2001:db8::/32")
{:ok, "2001:db8::/32"}

iex> Z.cidr()
iex> |> Z.parse("not-a-cidr")
iex> |> unwrap_issue_message()
"is invalid"

You can restrict to a specific IP version:

iex> Z.cidr(version: :v4)
iex> |> Z.parse("192.168.0.0/24")
{:ok, "192.168.0.0/24"}

iex> Z.cidr(version: :v4)
iex> |> Z.parse("2001:db8::/32")
iex> |> unwrap_issue_message()
"must be a valid IPv4 CIDR"

iex> Z.cidr(version: :v6)
iex> |> Z.parse("2001:db8::/32")
{:ok, "2001:db8::/32"}

iex> Z.cidr(version: :v6)
iex> |> Z.parse("192.168.0.0/24")
iex> |> unwrap_issue_message()
"must be a valid IPv6 CIDR"

You can change the output format:

iex> Z.cidr(output: :tuple)
iex> |> Z.parse("192.168.1.0/24")
{:ok, {{192, 168, 1, 0}, {192, 168, 1, 255}, 24}}

iex> Z.cidr(output: :map)
iex> |> Z.parse("192.168.1.0/24")
{:ok, %{start: {192, 168, 1, 0}, end: {192, 168, 1, 255}, prefix: 24}}

Non-canonical CIDR notation (where the IP is not the network address) is rejected by default:

iex> Z.cidr()
iex> |> Z.parse("192.168.1.100/24")
iex> |> unwrap_issue_message()
"must be in canonical form (network address), got '192.168.1.100/24'"

You can enable automatic canonicalization:

iex> Z.cidr(canonicalize: true)
iex> |> Z.parse("192.168.1.100/24")
{:ok, "192.168.1.0/24"}

You can enforce minimum and maximum prefix lengths:

iex> Z.cidr(min_prefix: 16)
iex> |> Z.parse("10.0.0.0/8")
iex> |> unwrap_issue_message()
"prefix length must be at least 16, got 8"

iex> Z.cidr(max_prefix: 24)
iex> |> Z.parse("10.0.0.0/28")
iex> |> unwrap_issue_message()
"prefix length must be at most 24, got 28"

It supports coercion from tuples and maps:

iex> Z.cidr()
iex> |> Z.parse({{192, 168, 0, 0}, 24}, coerce: true)
{:ok, "192.168.0.0/24"}

iex> Z.cidr()
iex> |> Z.parse(%{ip: {192, 168, 0, 0}, prefix: 24}, coerce: true)
{:ok, "192.168.0.0/24"}

It can be converted into json schema:

iex> Z.cidr(version: :v4)
iex> |> Z.describe("An IPv4 network.")
iex> |> Z.example("192.168.0.0/24")
iex> |> Z.json_schema()
%{
  "type" => "string",
  "pattern" => "^(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)/(?:3[0-2]|[12]?[0-9])$",
  "description" => "An IPv4 network.",
  "examples" => ["192.168.0.0/24"]
}

Validates that the IP address falls within the given CIDR range(s).

See ip/1 for more details.

Enforces that the string contains the given substring.

Creates a date type.

Examples

iex> Z.date()
iex> |> Z.parse(~D[2024-01-15])
{:ok, ~D[2024-01-15]}

iex> Z.date()
iex> |> Z.parse("foo")
iex> |> unwrap_issue_message()
"expected type Date, got string"

You can enforce that the date is after a given date:

iex> Z.date(min: ~D[2024-01-01])
iex> |> Z.parse(~D[2023-12-31])
iex> |> unwrap_issue_message()
"must be after 2024-01-01"

You can enforce that the date is before a given date:

iex> Z.date(max: ~D[2023-12-31])
iex> |> Z.parse(~D[2024-01-01])
iex> |> unwrap_issue_message()
"must be before 2023-12-31"

It supports coercion from ISO8601 strings:

iex> Z.date()
iex> |> Z.parse("2024-01-15", coerce: true)
{:ok, ~D[2024-01-15]}

iex> Z.date()
iex> |> Z.parse("Jan 15, 2024", coerce: true)
iex> |> unwrap_issue_message()
"must be a valid ISO8601 date string"

It can be converted into json schema:

iex> Z.date()
iex> |> Z.describe("A birth date.")
iex> |> Z.example(~D[2024-01-15])
iex> |> Z.json_schema()
%{
  "type" => "string",
  "format" => "date",
  "description" => "A birth date.",
  "examples" => ["2024-01-15"]
}

Creates a date-time type.

Examples

iex> Z.date_time()
iex> |> Z.parse(~U[2024-01-01T12:34:56Z])
{:ok, ~U[2024-01-01T12:34:56Z]}

iex> Z.date_time()
iex> |> Z.parse("foo")
iex> |> unwrap_issue_message()
"expected type DateTime, got string"

You can enforce that the date-time is after a given date-time:

iex> Z.date_time(min: ~U[2024-01-01 00:00:00Z])
iex> |> Z.parse(~U[2023-12-31 23:59:59Z])
iex> |> unwrap_issue_message()
"must be after 2024-01-01T00:00:00Z"

You can enforce that the date-time is before a given date-time:

iex> Z.date_time(max: ~U[2023-12-31 23:59:59Z])
iex> |> Z.parse(~U[2024-01-01 00:00:00Z])
iex> |> unwrap_issue_message()
"must be before 2023-12-31T23:59:59Z"

It supports coercion from ISO8601 strings:

iex> Z.date_time()
iex> |> Z.parse("2024-01-01T12:34:56Z", coerce: true)
{:ok, ~U[2024-01-01T12:34:56Z]}

iex> Z.date_time()
iex> |> Z.parse("Mon Jan 12 2026 11:16:30 GMT-0300 (Brasilia Standard Time)", coerce: true)
iex> |> unwrap_issue_message()
"must be a valid ISO8601 date-time string"

It can be converted into json schema:

iex> Z.date_time()
iex> |> Z.describe("A timestamp.")
iex> |> Z.example(~U[2026-01-10T10:23:45.123Z])
iex> |> Z.json_schema()
%{
  "type" => "string",
  "format" => "date-time",
  "description" => "A timestamp.",
  "examples" => ["2026-01-10T10:23:45.123Z"]
}

Alias to date_time/1.

Creates a decimal type.

Examples

iex> Z.decimal()
iex> |> Z.parse(Decimal.new("123.45"))
{:ok, Decimal.new("123.45")}

You can enforce a minimum value:

iex> Z.decimal(min: 10)
iex> |> Z.parse(Decimal.new("9.99"))
iex> |> unwrap_issue_message()
"must be at least 10, got 9.99"

You can enforce a maximum value:

iex> Z.decimal(max: 9.99)
iex> |> Z.parse(Decimal.new("10.00"))
iex> |> unwrap_issue_message()
"must be at most 9.99, got 10.0"

You can round to a given number of decimal places:

iex> Z.decimal(precision: 2)
iex> |> Z.parse(Decimal.new("3.14159"))
{:ok, Decimal.new("3.14")}

It can be coerced from an int:

iex> Z.decimal()
iex> |> Z.parse(42, coerce: true)
{:ok, Decimal.new("42")}

It can be coerced from a float:

iex> Z.decimal()
iex> |> Z.parse(3.14, coerce: true)
{:ok, Decimal.new("3.14")}

It can be coerced from a string:

iex> Z.decimal()
iex> |> Z.parse("3.14", coerce: true)
{:ok, Decimal.new("3.14")}

It can be converted into json schema:

iex> Z.decimal(min: 1.00, max: 100.00)
iex> |> Z.describe("A monetary amount.")
iex> |> Z.example(Decimal.new("19.99"))
iex> |> Z.json_schema()
%{
  "type" => "number",
  "description" => "A monetary amount.",
  "examples" => [19.99],
  "minimum" => 1.0,
  "maximum" => 100.0
}

Sets the field as not-required and provides a default value.

Attaches a description to the type, for use in JSON Schema.

Creates a discriminated union of two or more map types.

Unlike union/1, this provides more precise error reporting by using a discriminator field to determine which variant to parse.

Examples

Successful parsing with different variants:

iex> Z.discriminated_union(:type, [
iex>   Z.map(%{type: Z.literal("dog"), barks: Z.boolean()}),
iex>   Z.map(%{type: Z.literal("cat"), meows: Z.boolean()})
iex> ])
iex> |> Z.parse(%{type: "dog", barks: true})
{:ok, %{type: "dog", barks: true}}

iex> Z.discriminated_union(:type, [
iex>   Z.map(%{type: Z.literal("dog"), barks: Z.boolean()}),
iex>   Z.map(%{type: Z.literal("cat"), meows: Z.boolean()})
iex> ])
iex> |> Z.parse(%{type: "cat", meows: true})
{:ok, %{type: "cat", meows: true}}

Works with string keys in the input:

iex> Z.discriminated_union(:type, [
iex>   Z.map(%{type: Z.literal("dog"), barks: Z.boolean()}),
iex>   Z.map(%{type: Z.literal("cat"), meows: Z.boolean()})
iex> ])
iex> |> Z.parse(%{"type" => "dog", "barks" => true})
{:ok, %{type: "dog", barks: true}}

Error when discriminator value doesn't match any variant:

iex> Z.discriminated_union(:type, [
iex>   Z.map(%{type: Z.literal("dog"), barks: Z.boolean()}),
iex>   Z.map(%{type: Z.literal("cat"), meows: Z.boolean()})
iex> ])
iex> |> Z.parse(%{type: "bird", flies: true})
iex> |> unwrap_issue_message()
"expected field type to be one of 'dog' or 'cat', got 'bird'"

Error when input is not a map:

iex> Z.discriminated_union(:type, [
iex>   Z.map(%{type: Z.literal("dog"), barks: Z.boolean()}),
iex>   Z.map(%{type: Z.literal("cat"), meows: Z.boolean()})
iex> ])
iex> |> Z.parse("not a map")
iex> |> unwrap_issue_message()
"expected type map, got string"

ArgumentError when discriminator field is missing from a map type:

iex> try do
iex>   Z.discriminated_union(:kind, [
iex>     Z.map(%{type: Z.literal("dog")}),
iex>     Z.map(%{type: Z.literal("cat")})
iex>   ])
iex> rescue
iex>   e in ArgumentError -> e.message
iex> end
"the discriminator field :kind must exist in all map types"

ArgumentError when inner types are not map types:

iex> try do
iex>   Z.discriminated_union(:type, [Z.string(), Z.integer()])
iex> rescue
iex>   e in ArgumentError -> e.message
iex> end
"discriminated union only accepts map types, got Zot.Type.String"

ArgumentError when discriminator field is not a literal type:

iex> try do
iex>   Z.discriminated_union(:type, [
iex>     Z.map(%{type: Z.string(), name: Z.string()}),
iex>     Z.map(%{type: Z.string(), age: Z.integer()})
iex>   ])
iex> rescue
iex>   e in ArgumentError -> e.message
iex> end
"the discriminator field :type must be a literal type, got Zot.Type.String"

It can be converted into json schema:

iex> Z.discriminated_union(:type, [
iex>   Z.map(%{type: Z.literal("dog"), barks: Z.boolean()}),
iex>   Z.map(%{type: Z.literal("cat"), meows: Z.boolean()})
iex> ])
iex> |> Z.json_schema()
%{
  "oneOf" => [
    %{
      "type" => "object",
      "additionalProperties" => true,
      "properties" => %{
        "type" => %{"const" => "dog"},
        "barks" => %{"type" => "boolean"}
      },
      "required" => ["type", "barks"]
    },
    %{
      "type" => "object",
      "additionalProperties" => true,
      "properties" => %{
        "type" => %{"const" => "cat"},
        "meows" => %{"type" => "boolean"}
      },
      "required" => ["type", "meows"]
    }
  ],
  "discriminator" => %{
    "propertyName" => "type"
  }
}

Alias to date_time/1.

Creates an email type.

Examples

iex> Z.email()
iex> |> Z.parse("foo@zot.dev")
{:ok, "foo@zot.dev"}

You can optionally specify a ruleset for validation:

iex> Z.email(ruleset: :html5)
iex> |> Z.parse("invalid-email")
iex> |> unwrap_issue_message()
"is invalid"

iex> Z.email(ruleset: :ref5322)
iex> |> Z.parse("invalid-email")
iex> |> unwrap_issue_message()
"is invalid"

iex> Z.email(ruleset: :unicode)
iex> |> Z.parse("invalid-email")
iex> |> unwrap_issue_message()
"is invalid"

It can be converted into json schema:

iex> Z.email()
iex> |> Z.describe("A user's email address.")
iex> |> Z.example("foo@zot.dev")
iex> |> Z.json_schema()
%{
  "type" => "string",
  "format" => "email",
  "description" => "A user's email address.",
  "examples" => ["foo@zot.dev"]
}

Enforces that the string ends with the given substring.

Creates an enum type.

Examples

Values can be all atoms:

iex> Z.enum([:red, :green, :blue])
iex> |> Z.parse(:green)
{:ok, :green}

iex> Z.enum([:red, :green, :blue])
iex> |> Z.parse(:yellow)
iex> |> unwrap_issue_message()
"must be :red, :green or :blue, got :yellow"

Or they can be all strings:

iex> Z.enum(["small", "medium", "large"])
iex> |> Z.parse("medium")
{:ok, "medium"}

iex> Z.enum(["small", "medium", "large"])
iex> |> Z.parse("extra large")
iex> |> unwrap_issue_message()
"must be 'small', 'medium' or 'large', got 'extra large'"

It can be converted to json schema:

iex> Z.enum([:red, :green, :blue])
iex> |> Z.describe("A color.")
iex> |> Z.example(:green)
iex> |> Z.json_schema()
%{
  "type" => "string",
  "enum" => ["red", "green", "blue"],
  "description" => "A color.",
  "examples" => ["green"]
}

Attaches an example value to the type, for use in JSON Schema.

Creates a float type.

Examples

iex> Z.float()
iex> |> Z.parse(3.14)
{:ok, 3.14}

You can enforce a minimum value:

iex> Z.float(min: 1.0)
iex> |> Z.parse(0.99)
iex> |> unwrap_issue_message()
"must be at least 1.0, got 0.99"

You can enforce a maximum value:

iex> Z.float(max: 10.0)
iex> |> Z.parse(10.01)
iex> |> unwrap_issue_message()
"must be at most 10.0, got 10.01"

You can round to a given number of decimal places:

iex> Z.float(precision: 2)
iex> |> Z.parse(3.14159)
{:ok, 3.14}

It can be coerced from an int:

iex> Z.float()
iex> |> Z.parse(42, coerce: true)
{:ok, 42.0}

It can be coerced from Decimal:

iex> Z.float()
iex> |> Z.parse(Decimal.new("3.14"), coerce: true)
{:ok, 3.14}

It can be coerced from a string:

iex> Z.float()
iex> |> Z.parse("3.14", coerce: true)
{:ok, 3.14}

It can be converted into json schema:

iex> Z.float(min: 0.0, max: 1.0)
iex> |> Z.describe("A percentage.")
iex> |> Z.example(0.425)
iex> |> Z.json_schema()
%{
  "type" => "number",
  "description" => "A percentage.",
  "examples" => [0.425],
  "minimum" => 0.0,
  "maximum" => 1.0
}

Restricts which ports are forbidden in a URL.

See url/1 for more details.

Alias to integer/1.

Creates a integer type.

Examples

iex> Z.integer()
iex> |> Z.parse(42)
{:ok, 42}

You can enforce a minimum value:

iex> Z.integer(min: 18)
iex> |> Z.parse(16)
iex> |> unwrap_issue_message()
"must be at least 18, got 16"

You can enforce a maximum value:

iex> Z.integer(max: 18)
iex> |> Z.parse(33)
iex> |> unwrap_issue_message()
"must be at most 18, got 33"

It can be coerced from an float (rounded):

iex> Z.integer()
iex> |> Z.parse(3.14, coerce: true)
{:ok, 3}

It can be coerced from Decimal (rounded):

iex> Z.integer()
iex> |> Z.parse(Decimal.new("3.14"), coerce: true)
{:ok, 3}

It can be coerced from a string:

iex> Z.integer()
iex> |> Z.parse("42", coerce: true)
{:ok, 42}

It can be converted into json schema:

iex> Z.integer(min: 0, max: 100)
iex> |> Z.describe("A percentage.")
iex> |> Z.example(42)
iex> |> Z.json_schema()
%{
  "type" => "integer",
  "description" => "A percentage.",
  "examples" => [42],
  "minimum" => 0,
  "maximum" => 100
}

Creates an IP address type.

Examples

iex> Z.ip()
iex> |> Z.parse("192.168.1.1")
{:ok, "192.168.1.1"}

iex> Z.ip()
iex> |> Z.parse("::1")
{:ok, "::1"}

iex> Z.ip()
iex> |> Z.parse("not-an-ip")
iex> |> unwrap_issue_message()
"is invalid"

You can restrict to a specific IP version:

iex> Z.ip(version: :v4)
iex> |> Z.parse("192.168.1.1")
{:ok, "192.168.1.1"}

iex> Z.ip(version: :v4)
iex> |> Z.parse("::1")
iex> |> unwrap_issue_message()
"must be a valid IPv4 address"

iex> Z.ip(version: :v6)
iex> |> Z.parse("::1")
{:ok, "::1"}

iex> Z.ip(version: :v6)
iex> |> Z.parse("192.168.1.1")
iex> |> unwrap_issue_message()
"must be a valid IPv6 address"

You can change the output format to a tuple:

iex> Z.ip(output: :tuple)
iex> |> Z.parse("192.168.1.1")
{:ok, {192, 168, 1, 1}}

iex> Z.ip(output: :tuple)
iex> |> Z.parse("::1")
{:ok, {0, 0, 0, 0, 0, 0, 0, 1}}

It supports coercion from tuples:

iex> Z.ip()
iex> |> Z.parse({192, 168, 1, 1}, coerce: true)
{:ok, "192.168.1.1"}

iex> Z.ip()
iex> |> Z.parse({0, 0, 0, 0, 0, 0, 0, 1}, coerce: true)
{:ok, "::1"}

You can validate against CIDR ranges:

iex> Z.ip()
iex> |> Z.cidr("192.168.0.0/16")
iex> |> Z.parse("192.168.1.1")
{:ok, "192.168.1.1"}

iex> Z.ip()
iex> |> Z.cidr("192.168.0.0/16")
iex> |> Z.parse("10.0.0.1")
iex> |> unwrap_issue_message()
"must be within CIDR range 192.168.0.0/16"

You can use predefined CIDR sets:

iex> Z.ip()
iex> |> Z.cidr(:private)
iex> |> Z.parse("192.168.1.1")
{:ok, "192.168.1.1"}

iex> Z.ip()
iex> |> Z.cidr(:private)
iex> |> Z.parse("8.8.8.8")
iex> |> unwrap_issue_message()
"must be a private IP address"

iex> Z.ip()
iex> |> Z.cidr(:loopback)
iex> |> Z.parse("127.0.0.1")
{:ok, "127.0.0.1"}

iex> Z.ip()
iex> |> Z.cidr(:link_local)
iex> |> Z.parse("169.254.1.1")
{:ok, "169.254.1.1"}

It can be converted into json schema:

iex> Z.ip(version: :v4)
iex> |> Z.describe("An IPv4 address.")
iex> |> Z.example("192.168.1.1")
iex> |> Z.json_schema()
%{
  "type" => "string",
  "format" => "ipv4",
  "description" => "An IPv4 address.",
  "examples" => ["192.168.1.1"]
}

iex> Z.ip(version: :v6)
iex> |> Z.describe("An IPv6 address.")
iex> |> Z.example("::1")
iex> |> Z.json_schema()
%{
  "type" => "string",
  "format" => "ipv6",
  "description" => "An IPv6 address.",
  "examples" => ["::1"]
}

iex> Z.ip()
iex> |> Z.describe("An IP address.")
iex> |> Z.json_schema()
%{
  "description" => "An IP address.",
  "oneOf" => [
    %{"format" => "ipv4", "type" => "string"},
    %{"format" => "ipv6", "type" => "string"}
  ]
}

@spec json_schema(type) :: map() when type: Zot.Type.t()

Converts the given type into a JSON Schema.

Defines the behavior for leading plus signs in phone numbers.

See phone/1 for more details.

Enforces that the string or list has the given length.

Creates a list type.

Examples

iex> Z.string()
iex> |> Z.list()
iex> |> Z.parse(["hello", "world"])
{:ok, ["hello", "world"]}

You can enforce a minimum length:

iex> Z.string()
iex> |> Z.list(min: 3)
iex> |> Z.parse(["one", "two"])
iex> |> unwrap_issue_message()
"must have at least 3 items, got 2"

You can enforce a maximum length:

iex> Z.string()
iex> |> Z.list(max: 2)
iex> |> Z.parse(["one", "two", "three"])
iex> |> unwrap_issue_message()
"must have at most 2 items, got 3"

You can enforce an exact length:

iex> Z.string()
iex> |> Z.list(length: 2)
iex> |> Z.parse(["one", "two", "three"])
iex> |> unwrap_issue_message()
"must have 2 items, got 3"

It can be converted into json schema:

iex> Z.string()
iex> |> Z.list(min: 1, max: 5)
iex> |> Z.describe("A list of tags.")
iex> |> Z.example(["elixir", "zot"])
iex> |> Z.json_schema()
%{
  "type" => "array",
  "items" => %{
    "type" => "string"
  },
  "description" => "A list of tags.",
  "minItems" => 1,
  "maxItems" => 5
}

Creates a literal type.

Examples

It can be a boolean:

iex> Z.literal(true)
iex> |> Z.parse(true)
{:ok, true}

iex> Z.literal(true)
iex> |> Z.parse(false)
iex> |> unwrap_issue_message()
"must be true, got false"

iex> Z.literal(true)
iex> |> Z.parse("enabled", coerce: true)
{:ok, true}

It can be an integer:

iex> Z.literal(42)
iex> |> Z.parse(42)
{:ok, 42}

iex> Z.literal(42)
iex> |> Z.parse(43)
iex> |> unwrap_issue_message()
"must be 42, got 43"

iex> Z.literal(42)
iex> |> Z.parse("42", coerce: true)
{:ok, 42}

It can be a float:

iex> Z.literal(3.14)
iex> |> Z.parse(3.14)
{:ok, 3.14}

iex> Z.literal(3.14)
iex> |> Z.parse(3.13)
iex> |> unwrap_issue_message()
"must be 3.14, got 3.13"

iex> Z.literal(3.14)
iex> |> Z.parse("3.14", coerce: true)
{:ok, 3.14}

It can be a string:

iex> Z.literal("foo")
iex> |> Z.parse("foo")
{:ok, "foo"}

iex> Z.literal("foo")
iex> |> Z.parse("bar")
iex> |> unwrap_issue_message()
"must be 'foo', got 'bar'"

It can be an atom:

iex> Z.literal(:admin)
iex> |> Z.parse(:admin)
{:ok, :admin}

iex> Z.literal(:admin)
iex> |> Z.parse(:user)
iex> |> unwrap_issue_message()
"must be :admin, got :user"

iex> Z.literal(:admin)
iex> |> Z.parse("admin", coerce: true)
{:ok, :admin}

iex> Z.literal(:admin)
iex> |> Z.parse("user", coerce: true)
iex> |> unwrap_issue_message()
"must be :admin, got 'user'"

It can be converted into json schema:

iex> Z.literal("active")
iex> |> Z.describe("Lorem ipsum.")
iex> |> Z.json_schema()
%{
  "const" => "active",
  "description" => "Lorem ipsum.",
}

Creates a map type where unknown fields are stripped out.

Examples

iex> Z.map(%{name: Z.string(), age: Z.integer(min: 18)})
iex> |> Z.parse(%{name: "Alice", age: 18, email: "alice@wonder.land"})
{:ok, %{name: "Alice", age: 18}}

iex> {:error, [issue]} =
iex>   Z.map(%{name: Z.string(), age: Z.integer(min: 18)})
iex>   |> Z.parse(%{name: "Alice", age: 16, email: "alice@wonder.land"})
iex>
iex> assert issue.path == [:age]
iex> assert Exception.message(issue) == "must be at least 18, got 16"

It can be converted into json schema:

iex> Z.map(%{name: Z.string(), age: Z.integer(min: 0)})
iex> |> Z.describe("A person's profile.")
iex> |> Z.example(%{name: "Bob", age: 30})
iex> |> Z.json_schema()
%{
  "type" => "object",
  "description" => "A person's profile.",
  "examples" => [%{"name" => "Bob", "age" => 30}],
  "properties" => %{
    "name" => %{
      "type" => "string"
    },
    "age" => %{
      "type" => "integer",
      "minimum" => 0
    }
  },
  "required" => ["name", "age"],
  "additionalProperties" => true
}

Enforces a maximum value for the given type.

Enforces a maximum prefix length for CIDR notation.

See cidr/1 for more details.

Merges two map types into a new map type.

The second map's fields override the first on conflicts. The resulting map is strict if either input map is strict.

Note that required, default, description, example, and effects are lost when merging two maps. Use the appropriate modifiers after merging to set these fields.

Examples

iex> map1 = Z.map(%{name: Z.string()})
iex> map2 = Z.map(%{age: Z.integer()})
iex> Z.merge(map1, map2)
iex> |> Z.parse(%{name: "Alice", age: 30})
{:ok, %{name: "Alice", age: 30}}

iex> map1 = Z.map(%{name: Z.string()})
iex> map2 = Z.map(%{name: Z.integer()})
iex> Z.merge(map1, map2)
iex> |> Z.parse(%{name: 42})
{:ok, %{name: 42}}

iex> map1 = Z.strict_map(%{name: Z.string()})
iex> map2 = Z.map(%{age: Z.integer()})
iex> Z.merge(map1, map2)
iex> |> Z.parse(%{name: "Alice", age: 30, extra: "field"})
iex> |> unwrap_issue_message()
"unknown field"

Enforces a minimum value for the given type.

Enforces a minimum prefix length for CIDR notation.

See cidr/1 for more details.

Creates a non-empty string type that trims whitespace.

This is an alias for string(trim: true, min: 1).

Examples

iex> Z.non_empty_string()
iex> |> Z.parse("hello")
{:ok, "hello"}

iex> Z.non_empty_string()
iex> |> Z.parse("   ")
iex> |> unwrap_issue_message()
"must be at least 1 characters long, got 0"

iex> Z.non_empty_string()
iex> |> Z.parse("")
iex> |> unwrap_issue_message()
"must be at least 1 characters long, got 0"

Whitespace is trimmed before validation:

iex> Z.non_empty_string()
iex> |> Z.parse("  hello  ")
{:ok, "hello"}

Creates a number type (union of integer and float types).

Examples

iex> Z.number()
iex> |> Z.parse(3.14)
{:ok, 3.14}

iex> Z.number()
iex> |> Z.parse(42)
{:ok, 42}

It can be converted into json schema:

iex> Z.number(min: 0.5, max: 100)
iex> |> Z.describe("A percentage.")
iex> |> Z.example(42)
iex> |> Z.json_schema()
%{
  "type" => "number",
  "description" => "A percentage.",
  "examples" => [42],
  "minimum" => 0.5,
  "maximum" => 100
}

See float/1 and int/1 for more examples.