Joi

This project is inspired by sideway/joi and lob/litmus.

And the code of this repository is based on lob/litmus, but the API of this repository is completely different from litmus.

Background

The community already has a lot of verification-related libraries, such as skooma, vex, but why write a new one?

The api of vex is very much like Rails ActiveModel Validations, and it feels too complex for me, especially when it comes to customizing some validation modules, which is not convenient and flexible enough. Skooma, on the other hand, is very flexible and I find it particularly useful when validating non-map data structures.

So the goal of this repository is:

Support most of the types supported by the native sideway/joi
Nested validation support.
Easy internationalization
Easy to extend

Installation

def deps do
  [
    {:joi, "~> 0.2.0"},
  ]
end

Usage

Joi validates data against a predefined schema with the Joi.validate/2 function.

If the data is valid, the function returns {:ok, data}. The returned data will perform the transformation according to the provided schema.

if the passed data does not match the type defined in the schema, the function returns {:error, errors}, the errors is a list of Joi.Error, that a struct contains four fields:

context: map providing context of the error containing:
- key: key of the value that erred, equivalent to the last element of path.
- value: the value that failed validation.
- other error specific properties as described for each error code.
message: string with a description of the error.
path: list where each element is the accessor to the value where the error happened.
type: type of the error.

, When a field is received that is not specified in the provided schema, it does nothing and returns {:ok, data}.


  iex> schema = %{a: [:integer]}
  %{a: [:integer]}
  iex> data1 = %{a: 1}
  %{a: 1}
  iex> Joi.validate(data1, schema)
  {:ok, %{a: 1}}
  iex> data2 = %{a: <<123>>}
  iex> Joi.validate(data2, schema)
  {:error,
  [
    %Joi.Error{
      context: %{key: :a, value: "{"},
      message: "a must be a integer",
      path: [:a],
      type: "integer.base"
    }
  ]}

Atom

error types

atom.base
atom.inclusion
Additional local context properties:
```
%{inclusion: list()}
```
atom.required

Boolean

error types

boolean.base
boolean.required

Date

error types

date.base

Examples:

iex> schema = %{day: [:date]}
%{day: [:date]}
iex> Joi.validate(%{day: "2021-07-20"}, schema)
{:ok, %{day: ~D[2021-07-20]}}
iex> Joi.validate(%{day: "20210720"}, schema)
{:error,
[
  %Joi.Error{
    context: %{key: :day, value: "20210720"},
    message: "day must be a valid ISO-8601 date",
    path: [:day],
    type: "date.base"
  }
]}

date.required

Datetime

error types

datetime.baseExamples:

iex> schema = %{t: [:datetime]}
%{t: [:datetime]}
iex> d = %{t: ~U[2021-08-27 00:30:59.783833Z]}
%{t: ~U[2021-08-27 00:30:59.783833Z]}
iex> Joi.validate(d, schema)
{:ok, %{t: ~U[2021-08-27 00:30:59.783833Z]}}
iex> d2 = %{t: "2021-08-27 00:30:59.783833Z"}
%{t: "2021-08-27 00:30:59.783833Z"}
iex> Joi.validate(d2, schema)
{:ok, %{t: ~U[2021-08-27 00:30:59.783833Z]}}
iex> d3 = %{t: "2021-08-27 00:30:59"}
%{t: "2021-08-27 00:30:59"}
iex> Joi.validate(d3, schema)
{:error,
 [
   %Joi.Error{
     context: %{key: :t, value: "2021-08-27 00:30:59"},
     message: "t must be a valid ISO-8601 datetime",
     path: [:t],
     type: "datetime.base"
   }
 ]}

datetime.required

Decimal

error types

decimal.base

decimal.inclusion

Additional local context properties:

%{inclusion: list()}

Examples:

iex> schema = %{d: [:decimal, inclusion: [Decimal.new(1)]]}
%{d: [:decimal, {:inclusion, [Decimal.new(1)]}]}
iex> Joi.validate(%{d: Decimal.new(2)}, schema)
{:error,
[
  %Joi.Error{
    context: %{inclusion: [Decimal.new(1)], key: :d, value: Decimal.new(2)},
    message: "d must be one of #{inspect [Decimal.new(1)]}",
    path: [:d],
    type: "decimal.inclusion"
  }
]}

decimal.max

Additional local context properties:

%{limit: Decimal.t()}

Examples:

  iex> schema = %{n: [:decimal, max: 1]}
  %{n: [:decimal, {:max, 1}]}
  iex> Joi.validate(%{n: 0}, schema)
  {:ok, %{n: Decimal.new(0)}}
  iex> Joi.validate(%{n: "2"}, schema)
  {:error,
  [
    %Joi.Error{
      # string value will be converted to a float
      context: %{key: :n, limit: Decimal.new(1), value: Decimal.from_float(2.0)}, 
      message: "n must be less than or equal to 1",
      path: [:n],
      type: "decimal.max"
    }
  ]}
  iex> # max also support Decimal.t()
  iex> schema = %{n: [:decimal, max: Decimal.new(1)]}
  %{n: [:decimal, {:max, Decimal.new(1)}]}
  iex> Joi.validate(%{n: 2}, schema)
  {:error,
  [
    %Joi.Error{
      context: %{key: :n, limit: Decimal.new(1), value: Decimal.new(2)},
      message: "n must be less than or equal to 1",
      path: [:n],
      type: "decimal.max"
    }
  ]}
  iex> # max also support float
  iex> schema = %{n: [:decimal, max: 1.1]}
  %{n: [:decimal, {:max, 1.1}]}
  iex> Joi.validate(%{n: 2}, schema)
  {:error,
  [
    %Joi.Error{
      context: %{key: :n, limit: Decimal.from_float(1.1), value: Decimal.new(2)},
      message: "n must be less than or equal to 1.1",
      path: [:n],
      type: "decimal.max"
    }
  ]}

decimal.min
Additional local context properties:
```
%{limit: Decimal.t()}
```

decimal.greater

Additional local context properties:

%{limit: Decimal.t()}

Examples:

  iex> schema = %{n: [:decimal, greater: 0]}
  %{n: [:decimal, {:greater, 0}]}
  iex> Joi.validate(%{n: 2}, schema)
  {:ok, %{n: Decimal.new(2)}}
  iex> Joi.validate(%{n: 0}, schema)
  {:error,
    [
      %Joi.Error{
        context: %{key: :n, limit: Decimal.new(0), value: Decimal.new(0)},
        message: "n must be greater than 0",
        path: [:n],
        type: "decimal.greater"
      }
  ]}

decimal.less

Additional local context properties:

%{limit: Decimal.t()}

Examples:

  iex> schema = %{n: [:decimal, less: 0]}
  %{n: [:decimal, {:less, 0}]}
  iex> Joi.validate(%{n: -1}, schema)
  {:ok, %{n: Decimal.new(-1)}}
  iex> Joi.validate(%{n: 0}, schema)
  {:error,
    [
      %Joi.Error{
        context: %{key: :n, limit: Decimal.new(0), value: Decimal.new(0)},
        message: "n must be less than 0",
        path: [:n],
        type: "decimal.less"
      }
  ]}

decimal.required

Float

error types

float.base
float.inclusion
Additional local context properties:
```
%{inclusion: list()}
```
float.max
Additional local context properties:
```
%{limit: float() | integer()}
```
float.min
Additional local context properties:
```
%{limit: float() | integer()}
```
float.greater
Additional local context properties:
```
%{limit: float() | integer()}
```
float.less
Additional local context properties:
```
%{limit: float() | integer()}
```
float.required

Integer

error types

integer.base
integer.inclusion
Additional local context properties:
```
%{inclusion: list()}
```
integer.max Additional local context properties:
```
%{limit: integer()}
```
integer.min Additional local context properties:
```
%{limit: integer()}
```
integer.greater
Additional local context properties:
```
%{limit: integer()}
```
integer.less
Additional local context properties:
```
%{limit: integer()}
```
integer.required

List

list supports some special features, such as validation for each element:

iex> schema = %{l: [:list, type: :integer]}
%{l: [:list, {:type, :integer}]}
iex> Joi.validate(%{l: [<<123>>]}, schema)
{:error,
 [
   %Joi.Error{
     context: %{key: :l, value: ["{"]},
     message: "l must be a list of integer",
     path: [:l],
     type: "list.integer"
   }
 ]}

or a sub schema:

iex> sub_schema = %{key: [:integer]}
%{key: [:integer]}
iex> schema = %{l: [:list, schema: sub_schema]}
%{l: [:list, {:schema, %{key: [:integer]}}]}
iex> Joi.validate(%{l: [%{key: 1}, %{key: <<123>>}]}, schema)
{:error,
 [
   %Joi.Error{
     context: %{key: :key, value: "{"},
     message: "key must be a integer",
     path: [:l, 1, :key],
     type: "integer.base"
   }
 ]}

error types

list.base
list.length Additional local context properties:
```
%{limit: integer()}
```
list.max_length

Additional local context properties:

%{limit: integer()}

list.min_length

Additional local context properties:

%{limit: integer()}

list.required
list.schema
list.type

Map

:map also supports validation with sub schema:

iex> sub_schema = %{sub_key: [:integer]}
%{sub_key: [:integer]}
iex> schema = %{m: [:map, schema: sub_schema]}
%{m: [:map, {:schema, %{sub_key: [:integer]}}]}
iex> Joi.validate(%{m: %{sub_key: <<123>>}}, schema)
{:error,
 [
   %Joi.Error{
     context: %{key: :sub_key, value: "{"},
     message: "sub_key must be a integer",
     path: [:m, :sub_key],
     type: "integer.base"
   }
 ]}

error types

map.base
map.required

String

error types

string.base
string.format
string.inclusion Additional local context properties:
```
%{inclusion: list()}
```
string.length
Additional local context properties:
```
%{limit: integer()}
```
string.max_length
Additional local context properties:
```
%{limit: integer()}
```
string.min_length
Additional local context properties:
```
%{limit: integer()}
```
string.required
string.uuid

Custom functions

There is nothing magical about custom functions, you just need to return the same format as Joi's type, and then use :f as the key for the custom function in the schema, so you can use one or more custom functions inside a type.

iex> import Joi.Util
iex> func = fn field, data -> 
...>   case data[field] == 1 do
...>     true -> {:ok, data}
...>     false -> error("custom", path: [field], value: data[field], message: "does not match the custom function")
...>   end
...> end
iex> schema = %{id: [:integer, f: func]}
iex> data = %{id: 2}
iex> Joi.validate(data, schema)
{:error, [
  %Joi.Error{
    context: %{key: :id, message: "does not match the custom function", value: 2},
    message: "does not match the custom function",
    path: [:id],
    type: "custom"
  }
]}

Contributing

Feel free to dive in! Open an issue or submit PRS.

Joi follows the Contributor Covenant Code of Conduct.

← Previous Page API Reference