hanami-validations 1.3.7 → 2.0.0.beta1

data/README.md

@@ -1,15 +1,19 @@
 # Hanami::Validations
 
-Validations mixin for Ruby objects
+Data validation library for Ruby
 
 ## Status
 
 [![Gem Version](https://badge.fury.io/rb/hanami-validations.svg)](https://badge.fury.io/rb/hanami-validations)
-[![CI](https://github.com/hanami/validations/workflows/ci/badge.svg?branch=master)](https://github.com/hanami/validations/actions?query=workflow%3Aci+branch%3Amaster)
-[![Test Coverage](https://codecov.io/gh/hanami/validations/branch/master/graph/badge.svg)](https://codecov.io/gh/hanami/validations)
+[![CI](https://github.com/hanami/validations/workflows/ci/badge.svg?branch=main)](https://github.com/hanami/validations/actions?query=workflow%3Aci+branch%3Amain)
+[![Test Coverage](https://codecov.io/gh/hanami/validations/branch/main/graph/badge.svg)](https://codecov.io/gh/hanami/validations)
 [![Depfu](https://badges.depfu.com/badges/af6c6be539d9d587c7541ae7a013c9ff/overview.svg)](https://depfu.com/github/hanami/validations?project=Bundler)
 [![Inline Docs](http://inch-ci.org/github/hanami/validations.svg)](http://inch-ci.org/github/hanami/validations)
 
+## Version
+
+**This branch contains the code for `hanami-validations` 2.x.**
+
 ## Contact
 
 * Home page: http://hanamirb.org
@@ -23,14 +27,14 @@ Validations mixin for Ruby objects
 
 ## Rubies
 
-__Hanami::Validations__ supports Ruby (MRI) 2.3+ and JRuby 9.1.5.0+.
+__Hanami::Validations__ supports Ruby (MRI) 3.0+
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'hanami-validations'
+gem "hanami-validations"
 ```
 
 And then execute:
@@ -47,733 +51,426 @@ $ gem install hanami-validations
 
 ## Usage
 
-`Hanami::Validations` is a mixin that, once included by an object, adds lightweight set of validations to it.
-
-It works with input hashes and lets us to define a set of validation rules **for each** key/value pair. These rules are wrapped by lambdas (or special DSL) that check the input for a specific key to determine if it's valid or not. To do that, we translate business requirements into predicates that are chained together with Ruby _faux boolean logic_ operators (eg. `&` or `|`).
-
-Think of a signup form. We need to ensure data integrity for the  `name` field with the following rules. It is required, it has to be: filled **and** a string **and** its size must be greater than 3 chars, but lesser than 64. Here’s the code, **read it aloud** and notice how it perfectly expresses our needs for `name`.
-
-```ruby
-class Signup
-  include Hanami::Validations
-
-  validations do
-    required(:name) { filled? & str? & size?(3..64) }
-  end
-end
-
-result = Signup.new(name: "Luca").validate
-result.success? # => true
-```
-
-There is more that `Hanami::Validations` can do: **type safety**, **composition**, **complex data structures**, **built-in and custom predicates**.
-
-But before to dive into advanced topics, we need to understand the basics of _boolean logic_.
-
-### Boolean Logic
+[Hanami](http://hanamirb.org), [ROM](https://rom-rb.org), and [DRY](https://dry-rb.org) projects are working together to create a strong Ruby ecosystem.
+`hanami-validations` is based on [`dry-validation`](https://dry-rb.org/gems/dry-validation/master/), for this reason the documentation explains the basics of this gem, but for advanced topics, it links to `dry-validation` docs.
 
-When we check data, we expect only two outcomes: an input can be valid or not. No grey areas, nor fuzzy results. It’s white or black, 1 or 0, `true` or `false` and _boolean logic_ is the perfect tool to express these two states. Indeed, a Ruby _boolean expression_ can only return `true` or `false`.
+### Overview
 
-To better recognise the pattern, let’s get back to the example above. This time we will map the natural language rules with programming language rules.
+The main object provided by this gem is `Hanami::Validator`.
+It providers a powerful DSL to define a validation contract, which is made of a schema and optional rules.
 
-```
-        A name must be filled  and be a string and its size must be included between 3 and 64.
-           👇            👇    👇       👇    👇      👇                           👇    👇
-required(:name)      { filled?  &       str?   &      size?                         (3 ..  64) }
-
-```
-
-Now, I hope you’ll never format code like that, but in this case, that formatting serves well our purpose to show how Ruby’s  simplicity helps to define complex rules with no effort.
-
-From a high level perspective, we can tell that input data for `name` is _valid_ only if **all** the requirements are satisfied. That’s because we used `&`.
-
-#### Logic Operators
-
-We support four logic operators:
-
-  * `&` (aliased as `and`) for _conjunction_
-  * `|` (aliased as `or`) for _disjunction_
-  * `>` (aliased as `then`) for _implication_
-  * `^` (aliased as `xor`) for _exclusive disjunction_
-
-#### Context Of Execution
+A validation **schema** is a set of steps that filters, coerces, and checks the validity of incoming data.
+Validation **rules** are a set of directives, to check if business rules are respected.
 
-**Please notice that we used `&` over Ruby's `&&` keyword.**
-That's because the context of execution of these validations isn't a plain lambda, but something richer.
+Only when the input is formally valid (according to the **schema**), validation **rules** are checked.
 
-For real world projects, we want to support common scenarios without the need of reinventing the wheel ourselves. Scenarios like _password confirmation_, _size check_ are already prepackaged with `Hanami::Validations`.
-
-
-⚠ **For this reason, we don't allow any arbitrary Ruby code to be executed, but only well defined predicates.** ⚠
-
-### Predicates
+```ruby
+# frozen_string_literal: true
 
-To meet our needs, `Hanami::Validations` has an extensive collection of **built-in** predicates. **A predicate is the expression of a business requirement** (e.g. _size greater than_). The chain of several predicates determines if input data is valid or not.
+require "hanami/validations"
 
-We already met `filled?` and `size?`, now let’s introduce the rest of them. They capture **common use cases with web forms**.
+class SignupValidator < Hanami::Validator
+  schema do
+    required(:email).value(:string)
+    required(:age).value(:integer)
+  end
 
-### Array
+  rule(:age) do
+    key.failure("must be greater than 18") if value < 18
+  end
+end
 
-It checks if the the given value is an array, and iterates through its elements to perform checks on each of them.
+validator = SignupValidator.new
 
-```ruby
-required(:codes) { array? { each { int? } } }
-```
+result = validator.call(email: "user@hanamirb.test", age: 37)
+result.success? # => true
 
-This example checks if `codes` is an array and if all the elements are integers, whereas the following example checks there are a minimum of 2 elements and all elements are strings.
+result = validator.call(email: "user@hanamirb.test", age: "foo")
+result.success? # => false
+result.errors.to_h # => {:age=>["must be an integer"]}
 
-```ruby
-required(:codes) { array? { min_size?(2) & each { str? } } }
+result = validator.call(email: "user@hanamirb.test", age: 17)
+puts result.success? # => false
+puts result.errors.to_h # => {:age=>["must be greater than 18"]}
 ```
 
-#### Emptiness
+### Schemas
 
-It checks if the given value is empty or not. It is designed to works with strings and collections (array and hash).
+A basic schema doesn't apply data coercion, input must already have the right Ruby types.
 
 ```ruby
-required(:tags) { empty? }
-```
+# frozen_string_literal: true
 
-#### Equality
-
-This predicate tests if the input is equal to a given value.
-
-```ruby
-required(:magic_number) { eql?(23) }
-```
+require "hanami/validations"
 
-Ruby types are respected: `23` (an integer) is only equal to `23`, and not to `"23"` (a string). See _Type Safety_ section.
+class SignupValidator < Hanami::Validator
+  schema do
+    required(:email).value(:string)
+    required(:age).value(:integer)
+  end
+end
 
-#### Exclusion
+validator = SignupValidator.new
 
-It checks if the input is **not** included by a given collection. This collection can be an array, a set, a range or any object that responds to `#include?`.
+result = validator.call(email: "user@hanamirb.test", age: 37)
+puts result.success? # => true
 
-```ruby
-required(:genre) { excluded_from?(%w(pop dance)) }
+result = validator.call(email: "user@hanamirb.test", age: "37")
+puts result.success? # => false
+puts result.errors.to_h # => {:age=>["must be an integer"]}
 ```
 
-#### Format
-
-This is a predicate that works with a regular expression to match it against data input.
-
-```ruby
-require 'uri'
-HTTP_FORMAT = URI.regexp(%w(http https))
-
-required(:url) { format?(HTTP_FORMAT) }
-```
+### Params
 
-#### Greater Than
+When used in _params mode_, a schema applies data coercion, before to run validation checks.
 
-This predicate works with numbers to check if input is **greater than** a given threshold.
+This is designed for Web form/HTTP params.
 
 ```ruby
-required(:age) { gt?(18) }
-```
-
-#### Greater Than Equal
-
-This is an _open boundary_ variation of `gt?`. It checks if an input is **greater than or equal** of a given number.
+# frozen_string_literal: true
 
-```ruby
-required(:age) { gteq?(19) }
-```
+require "bundler/setup"
+require "hanami/validations"
 
-#### Inclusion
+class SignupValidator < Hanami::Validator
+  params do
+    required(:email).value(:string)
+    required(:age).value(:integer)
+  end
+end
 
-This predicate is the opposite of `#exclude?`: it verifies if the input is **included** in the given collection.
+validator = SignupValidator.new
 
-```ruby
-required(:genre) { included_in?(%w(rock folk)) }
+result = validator.call(email: "user@hanamirb.test", age: "37")
+puts result.success? # => true
+puts result.to_h # => {:email=>"user@hanamirb.test", :age=>37}
 ```
 
-#### Less Than
+### JSON
 
-This is the complement of `#gt?`: it checks for **less than** numbers.
+When used in _JSON mode_, data coercions are still applied, but they follow different policies.
+For instance, because JSON supports integers, strings won't be coerced into integers.
 
 ```ruby
-required(:age) { lt?(7) }
-```
+# frozen_string_literal: true
 
-#### Less Than Equal
+require "hanami/validations"
 
-Similarly to `#gteq?`, this is the _open bounded_ version of `#lt?`: an input is valid if it’s **less than or equal** to a number.
-
-```ruby
-required(:age) { lteq?(6) }
-```
+class SignupValidator < Hanami::Validator
+  json do
+    required(:email).value(:string)
+    required(:age).value(:integer)
+  end
+end
 
-#### Filled
+validator = SignupValidator.new
 
-It’s a predicate that ensures data input is filled, that means **not** `nil` or blank (`""`) or empty (in case we expect a collection).
+result = validator.call(email: "user@hanamirb.test", age: 37)
+puts result.success? # => true
+puts result.to_h # => {:email=>"user@hanamirb.test", :age=>37}
 
-```ruby
-required(:name) { filled? }      # string
-required(:languages) { filled? } # collection
+result = validator.call(email: "user@hanamirb.test", age: "37")
+puts result.success? # => false
 ```
 
-#### Minimum Size
+### Whitelisting
 
-This verifies that the size of the given input is at least of the specified value.
+Unknown keys from incoming data are filtered out:
 
 ```ruby
-required(:password) { min_size?(12) }
-```
+# frozen_string_literal: true
 
-#### Maximum Size
+require "hanami/validations"
 
-This verifies that the size of the given input is at max of the specified value.
-
-```ruby
-required(:name) { max_size?(128) }
-```
-
-#### None
+class SignupValidator < Hanami::Validator
+  schema do
+    required(:email).value(:string)
+  end
+end
 
-This verifies if the given input is `nil`. Blank strings (`""`) won’t pass this test and return `false`.
+validator = SignupValidator.new
 
-```ruby
-required(:location) { none? }
+result = validator.call(email: "user@hanamirb.test", foo: "bar")
+puts result.success? # => true
+puts result.to_h # => {:email=>"user@hanamirb.test"}
 ```
 
-#### Size
-
-It checks if the size of input data is: a) exactly the same of a given quantity or b) it falls into a range.
+### Custom Types
 
 ```ruby
-required(:two_factor_auth_code) { size?(6) }     # exact
-required(:password)             { size?(8..32) } # range
-```
+# frozen_string_literal: true
 
-The check works with strings and collections.
+require "hanami/validations"
 
-```ruby
-required(:answers) { size?(2) } # only 2 answers are allowed
-```
+module Types
+  include Dry::Types()
 
-This predicate works with objects that respond to `#size`. Until now we have seen strings and arrays being analysed by this validation, but there is another interesting usage: files.
+  StrippedString = Types::String.constructor(&:strip)
+end
 
-When a user uploads a file, the web server sets an instance of `Tempfile`, which responds to `#size`. That means we can validate the weight in bytes of file uploads.
+class SignupValidator < Hanami::Validator
+  params do
+    required(:email).value(Types::StrippedString)
+    required(:age).value(:integer)
+  end
+end
 
-```ruby
-MEGABYTE = 1024 ** 2
+validator = SignupValidator.new
 
-required(:avatar) { size?(1..(5 * MEGABYTE)) }
+result = validator.call(email: "     user@hanamirb.test     ", age: "37")
+puts result.success? # => true
+puts result.to_h # => {:email=>"user@hanamirb.test", :age=>37}
 ```
 
-### Custom Predicates
-
-We have seen that built-in predicates as an expressive tool to get our job done with common use cases.
-
-But what if our case is not common? We can define our own custom predicates.
-
-#### Inline Custom Predicates
+### Rules
 
-If we are facing a really unique validation that don't need to be reused across our code, we can opt for an inline custom predicate:
+Rules are performing a set of domain-specific validation checks.
+Rules are executed only after the validations from the schema are satisfied.
 
 ```ruby
-require 'hanami/validations'
+# frozen_string_literal: true
 
-class Signup
-  include Hanami::Validations
+require "hanami/validations"
 
-  predicate :url?, message: 'must be an URL' do |current|
-    # ...
+class EventValidator < Hanami::Validator
+  params do
+    required(:start_date).value(:date)
   end
 
-  validations do
-    required(:website) { url? }
+  rule(:start_date) do
+    key.failure("must be in the future") if value <= Date.today
   end
 end
-```
 
-#### Global Custom Predicates
+validator = EventValidator.new
 
-If our goal is to share common used custom predicates, we can include them in a module to use in all our validators:
+result = validator.call(start_date: "foo")
+puts result.success? # => false
+puts result.errors.to_h # => {:start_date=>["must be a date"]}
 
-```ruby
-require 'hanami/validations'
+result = validator.call(start_date: Date.today)
+puts result.success? # => false
+puts result.errors.to_h # => {:start_date=>["must be in the future"]}
 
-module MyPredicates
-  include Hanami::Validations::Predicates
+result = validator.call(start_date: Date.today + 1)
+puts result.success? # => true
+puts result.to_h # => {:start_date=>#<Date: 2019-07-03 ((2458668j,0s,0n),+0s,2299161j)>}
+```
 
-  self.messages_path = 'config/errors.yml'
+Learn more about rules: https://dry-rb.org/gems/dry-validation/master/rules/
 
-  predicate(:email?) do |current|
-    current.match(/.../)
-  end
-end
-```
+### Inheritance
 
-We have defined a module `MyPredicates` with the purpose to share its custom predicates with all the validators that need them.
+Schema and rules validations can be inherited and used by subclasses
 
 ```ruby
-require 'hanami/validations'
-require_relative 'my_predicates'
+# frozen_string_literal: true
 
-class Signup
-  include Hanami::Validations
-  predicates MyPredicates
+require "hanami/validations"
 
-  validations do
-    required(:email) { email? }
+class ApplicationValidator < Hanami::Validator
+  params do
+    optional(:_csrf_token).filled(:string)
   end
 end
-```
-
-### Required and Optional keys
-
-HTML forms can have required or optional fields. We can express this concept with two methods in our validations: `required` (which we already met in previous examples), and `optional`.
-
-```ruby
-require 'hanami/validations'
 
-class Signup
-  include Hanami::Validations
-
-  validations do
-    required(:email)    { ... }
-    optional(:referral) { ... }
+class SignupValidator < ApplicationValidator
+  params do
+    required(:user).hash do
+      required(:email).filled(:string)
+    end
   end
 end
-```
-
-### Type Safety
-
-At this point, we need to explicitly tell something really important about built-in predicates. Each of them have expectations about the methods that an input is able to respond to.
-
-Why this is so important? Because if we try to invoke a method on the input we’ll get a `NoMethodError` if the input doesn’t respond to it. Which isn’t nice, right?
-
-Before to use a predicate, we want to ensure that the input is an instance of the expected type. Let’s introduce another new predicate for our need: `#type?`.
-
-```ruby
-required(:age) { type?(Integer) & gteq?(18) }
-```
-
-It takes the input and tries to coerce it. If it fails, the execution stops. If it succeed, the subsequent predicates can trust `#type?` and be sure that the input is an integer.
-
-**We suggest to use `#type?` at the beginning of the validations block. This _type safety_ policy is crucial to prevent runtime errors.**
-
-`Hanami::Validations` supports the most common Ruby types:
-
-  * `Array` (aliased as `array?`)
-  * `BigDecimal` (aliased as `decimal?`)
-  * `Boolean` (aliased as `bool?`)
-  * `Date` (aliased as `date?`)
-  * `DateTime` (aliased as `date_time?`)
-  * `Float` (aliased as `float?`)
-  * `Hash` (aliased as `hash?`)
-  * `Integer` (aliased as `int?`)
-  * `String` (aliased as `str?`)
-  * `Time` (aliased as `time?`)
-
-For each supported type, there a convenient predicate that acts as an alias. For instance, the two lines of code below are **equivalent**.
 
-```ruby
-required(:age) { type?(Integer) }
-required(:age) { int? }
-```
-
-### Macros
-
-Rule composition with blocks is powerful, but it can become verbose.
-To reduce verbosity, `Hanami::Validations` offers convenient _macros_ that are internally _expanded_ (aka interpreted) to an equivalent _block expression_
-
-#### Filled
+validator = SignupValidator.new
 
-To use when we expect a value to be filled:
-
-```ruby
-# expands to
-# required(:age) { filled? }
-
-required(:age).filled
+result = validator.call(user: { email: "user@hanamirb.test" }, _csrf_token: "abc123")
+puts result.success? # => true
+puts result.to_h # => {:user=>{:email=>"user@hanamirb.test"}, :_csrf_token=>"abc123"}
 ```
 
-```ruby
-# expands to
-# required(:age) { filled? & type?(Integer) }
+### Messages
 
-required(:age).filled(:int?)
-```
-
-```ruby
-# expands to
-# required(:age) { filled? & type?(Integer) & gt?(18) }
-
-required(:age).filled(:int?, gt?: 18)
-```
-
-In the examples above `age` is **always required** as value.
+Failure messages can be hardcoded or refer to a message template system.
+`hanami-validations` supports natively a default YAML based message template system, or alternatively, `i18n` gem.
 
-#### Maybe
-
-To use when a value can be nil:
+We have already seen rule failures set with hardcoded messages, here's an example of how to use keys to refer to interpolated messages.
 
 ```ruby
-# expands to
-# required(:age) { none? | int? }
-
-required(:age).maybe(:int?)
-```
-
-In the example above `age` can be `nil`, but if we send the value, it **must** be an integer.
-
-#### Each
+# frozen_string_literal: true
 
-To use when we want to apply the same validation rules to all the elements of an array:
-
-```ruby
-# expands to
-# required(:tags) { array? { each { str? } } }
+require "hanami/validations"
 
-required(:tags).each(:str?)
+class ApplicationValidator < Hanami::Validator
+  config.messages.top_namespace = "bookshelf"
+  config.messages.load_paths << "config/errors.yml"
+end
 ```
 
-In the example above `tags` **must** be an array of strings.
+In the `ApplicationValidator` there is defined the application namespace (`"bookshelf"`), which is the root of the messages file.
+Below that top name, there is the key `errors`. Everything that is nested here is accessible by the validations.
 
+There are two ways to organize messages:
 
-#### Confirmation
+  1. Right below `errors`. This is for **general purposes** error messages (e.g. `bookshelf` => `errors` => `taken`)
+  2. Below `errors` => `rules` => name of the attribute => custom key (e.g. `bookshelf` => `errors` => `age` => `invalid`). This is for **specific** messages that affect only a specific attribute.
 
-This is designed to check if pairs of web form fields have the same value. One wildly popular example is _password confirmation_.
+Our **suggestion** is to start with **specific** messages and see if there is a need to generalize them.
 
-```ruby
-required(:password).filled.confirmation
+```yaml
+# config/errors.yml
+en:
+  bookshelf:
+    errors:
+      taken: "oh noes, it's already taken"
+      network: "there is a network error (%{code})"
+      rules:
+        age:
+          invalid: "must be greater than 18"
+        email:
+          invalid: "not a valid email"
 ```
 
-It is valid if the input has `password` and `password_confirmation` keys with the same exact value.
-
-⚠ **CONVENTION:** For a given key `password`, the _confirmation_ predicate expects another key `password_confirmation`. Easy to tell, it’s the concatenation of the original key with the `_confirmation` suffix. Their values must be equal. ⚠
-
-### Forms
-
-An important precondition to check before to implement a validator is about the expected input.
-When we use validators for already preprocessed data it's safe to use basic validations from `Hanami::Validations` mixin.
-
-If the data is coming directly from user input via a HTTP form, it's advisable to use `Hanami::Validations::Form` instead.
-**The two mixins have the same API, but the latter is able to do low level input preprocessing specific for forms**. For instance, blank inputs are casted to `nil` in order to avoid blank strings in the database.
-
-### Rules
-
-Predicates and macros are tools to code validations that concern a single key like `first_name` or `email`.
-If the outcome of a validation depends on two or more attributes we can use _rules_.
-
-Here's a practical example: a job board.
-We want to validate the form of the job creation with some mandatory fields: `type` (full time, part-time, contract), `title` (eg. Developer), `description`, `company` (just the name) and a `website` (which is optional).
-An user must specify the location: on-site or remote. If it's on site, they must specify the `location`, otherwise they have to tick the checkbox for `remote`.
-
-Here's the code:
+#### General purpose messages
 
 ```ruby
-class CreateJob
-  include Hanami::Validations::Form
-
-  validations do
-    required(:type).filled(:int?, included_in?: [1, 2, 3])
-
-    optional(:location).maybe(:str?)
-    optional(:remote).maybe(:bool?)
-
-    required(:title).filled(:str?)
-    required(:description).filled(:str?)
-    required(:company).filled(:str?)
-
-    optional(:website).filled(:str?, format?: URI.regexp(%w(http https)))
-
-    rule(location_presence: [:location, :remote]) do |location, remote|
-      (remote.none? | remote.false?).then(location.filled?) &
-        remote.true?.then(location.none?)
-    end
+class SignupValidator < ApplicationValidator
+  schema do
+    required(:username).filled(:string)
   end
-end
-```
-
-We specify a rule with `rule` method, which takes an arbitrary name and an array of preconditions.
-Only if `:location` and `:remote` are valid according to their validations described above, the `rule` block is evaluated.
-
-The block yields the same exact keys that we put in the precondintions.
-So for `[:location, :remote]` it will yield the corresponding values, bound to the `location` and `remote` variables.
-
-We can use these variables to define the rule. We covered a few cases:
-
-  * If `remote` is missing or false, then `location` must be filled
-  * If `remote` is true, then `location` must be omitted
-
-### Nested Input Data
-
-While we’re building complex web forms, we may find comfortable to organise data in a hierarchy of cohesive input fields. For instance, all the fields related to a customer, may have the `customer` prefix. To reflect this arrangement on the server side, we can group keys.
 
-```ruby
-validations do
-  required(:customer).schema do
-    required(:email) { … }
-    required(:name)  { … }
-    # other validations …
+  rule(:username) do
+    key.failure(:taken) if values[:username] == "jodosha"
   end
 end
-```
 
-Groups can be **deeply nested**, without any limitation.
+validator = SignupValidator.new
 
-```ruby
-validations do
-  required(:customer).schema do
-    # other validations …
+result = validator.call(username: "foo")
+puts result.success? # => true
 
-    required(:address).schema do
-      required(:street) { … }
-      # other address validations …
-    end
-  end
-end
+result = validator.call(username: "jodosha")
+puts result.success? # => false
+puts result.errors.to_h # => {:username=>["oh noes, it's already taken"]}
 ```
 
-### Composition
-
-Until now, we have seen only small snippets to show specific features. That really close view prevents us to see the big picture of complex real world projects.
+#### Specific messages
 
-As the code base grows, it’s a good practice to DRY validation rules.
+Please note that the failure key used it's the same for both the attributes (`:invalid`), but thanks to the nesting, the library is able to lookup the right message.
 
 ```ruby
-class AddressValidator
-  include Hanami::Validations
-
-  validations do
-    required(:street) { … }
+class SignupValidator < ApplicationValidator
+  schema do
+    required(:email).filled(:string)
+    required(:age).filled(:integer)
   end
-end
-```
-
-This validator can be reused by other validators.
-
-```ruby
-class CustomerValidator
-  include Hanami::Validations
 
-  validations do
-    required(:email) { … }
-    required(:address).schema(AddressValidator)
+  rule(:email) do
+    key.failure(:invalid) unless values[:email] =~ /@/
   end
-end
-```
 
-Again, there is no limit to the nesting levels.
-
-```ruby
-class OrderValidator
-  include Hanami::Validations
-
-  validations do
-    required(:number) { … }
-    required(:customer).schema(CustomerValidator)
+  rule(:age) do
+    key.failure(:invalid) if values[:age] < 18
   end
 end
-```
-
-In the end, `OrderValidator` is able to validate a complex data structure like this:
-
-```ruby
-{
-  number: "123",
-  customer: {
-    email: "user@example.com",
-    address: {
-      city: "Rome"
-    }
-  }
-}
-```
-
-### Whitelisting
-
-Another fundamental role that validators plays in the architecture of our projects is input whitelisting.
-For security reasons, we want to allow known keys to come in and reject everything else.
-
-This process happens when we invoke `#validate`.
-Allowed keys are the ones defined with `.required`.
 
-**Please note that whitelisting is only available for `Hanami::Validations::Form` mixin.**
+validator = SignupValidator.new
 
-### Result
-
-When we trigger the validation process with `#validate`, we get a result object in return. It’s able to tell if it’s successful, which rules the input data has violated and an output data bag.
-
-```ruby
-result = OrderValidator.new({}).validate
-result.success? # => false
-```
-
-#### Messages
-
-`result.messages` returns a nested set of validation error messages.
-
-Each error carries on informations about a single rule violation.
-
-```ruby
-result.messages.fetch(:number)   # => ["is missing"]
-result.messages.fetch(:customer) # => ["is missing"]
-```
-
-#### Output
-
-`result.output` is a `Hash` which is the result of whitelisting and coercions. It’s useful to pass it do other components that may want to persist that data.
-
-```ruby
-{
-  "number"  => "123",
-  "unknown" => "foo"
-}
-```
-
-If we receive the input above, `output` will look like this.
-
-```ruby
-result.output
-  # => { :number => 123 }
+result = validator.call(email: "foo", age: 17)
+puts result.success? # => false
+puts result.errors.to_h # => {:email=>["not a valid email"], :age=>["must be greater than 18"]}
 ```
 
-We can observe that:
-
-  * Keys are _symbolized_
-  * Only whitelisted keys are included
-  * Data is coerced
-
-### Error Messages
-
-To pick the right error message is crucial for user experience.
-As usual `Hanami::Validations` comes to the rescue for most common cases and it leaves space to customization of behaviors.
+#### Extra information
 
-We have seen that builtin predicates have default messages, while [inline predicates](#inline-custom-predicates) allow to specify a custom message via the `:message` option.
+The interpolation mechanism, accepts extra, arbitrary information expressed as a `Hash` (e.g. `code: "123"`)
 
 ```ruby
-class SignupValidator
-  include Hanami::Validations
-
-  predicate :email?, message: 'must be an email' do |current|
-    # ...
+class RefundValidator < ApplicationValidator
+  schema do
+    required(:refunded_code).filled(:string)
   end
 
-  validations do
-    required(:email).filled(:str?, :email?)
-    required(:age).filled(:int?, gt?: 18)
+  rule(:refunded_code) do
+    key.failure(:network, code: "123") if values[:refunded_code] == "error"
   end
 end
 
-result = SignupValidator.new(email: 'foo', age: 1).validate
+validator = RefundValidator.new
 
-result.success?               # => false
-result.messages.fetch(:email) # => ['must be an email']
-result.messages.fetch(:age)   # => ['must be greater than 18']
+result = validator.call(refunded_code: "error")
+puts result.success? # => false
+puts result.errors.to_h # => {:refunded_code=>["there is a network error (123)"]}
 ```
 
-#### Configurable Error Messages
+Learn more about messages: https://dry-rb.org/gems/dry-validation/master/messages/
 
-Inline error messages are ideal for quick and dirty development, but we suggest to use an external YAML file to configure these messages:
+### External dependencies
 
-```yaml
-# config/messages.yml
-en:
-  errors:
-    email?: "must be an email"
-```
-
-To be used like this:
+If the validator needs to plug one or more objects to run the validations, there is a DSL to do so: `:option`.
+When the validator is instantiated, the declared dependencies must be passed.
 
 ```ruby
-class SignupValidator
-  include Hanami::Validations
-  messages_path 'config/messages.yml'
+# frozen_string_literal: true
 
-  predicate :email? do |current|
-    # ...
-  end
+require "hanami/validations"
 
-  validations do
-    required(:email).filled(:str?, :email?)
-    required(:age).filled(:int?, gt?: 18)
+class AddressValidator
+  def valid?(value)
+    value.match(/Rome/)
   end
 end
 
-```
-
-
-#### Custom Error Messages
+class DeliveryValidator < Hanami::Validator
+  option :address_validator
 
-In the example above, the failure message for age is fine: `"must be greater than 18"`, but how to tweak it? What if we need to change into something diffent? Again, we can use the YAML configuration file for our purpose.
+  schema do
+    required(:address).filled(:string)
+  end
 
-```yaml
-# config/messages.yml
-en:
-  errors:
-    email?: "must be an email"
+  rule(:address) do
+    key.failure("not a valid address") unless address_validator.valid?(values[:address])
+  end
+end
 
-    rules:
-      signup:
-        age:
-          gt?: "must be an adult"
+validator = DeliveryValidator.new(address_validator: AddressValidator.new)
 
+result = validator.call(address: "foo")
+puts result.success? # => false
+puts result.errors.to_h # => {:address=>["not a valid address"]}
 ```
 
-Now our validator is able to look at the right error message.
+Read more about external dependencies: https://dry-rb.org/gems/dry-validation/master/external-dependencies/
 
-```ruby
-result = SignupValidator.new(email: 'foo', age: 1).validate
+### Mixin
 
-result.success?             # => false
-result.messages.fetch(:age) # => ['must be an adult']
-```
-
-##### Custom namespace
+`hanami-validations` 1.x used to ship a mixin `Hanami::Validations` to be included in classes to provide validation rules.
+The 2.x series, still ships this mixin, but it will be probably removed in 3.x.
 
-⚠ **CONVENTION:** For a given validator named `SignupValidator`, the framework will look for `signup` translation key. ⚠
+```ruby
+# frozen_string_literal: true
 
-If for some reason that doesn't work for us, we can customize the namespace:
+require "hanami/validations"
 
-```ruby
-class SignupValidator
+class UserValidator
   include Hanami::Validations
 
-  messages_path 'config/messages.yml'
-  namespace     :my_signup
-
-  # ...
+  validations do
+    required(:number).filled(:integer, eql?: 23)
+  end
 end
-```
 
-The new namespace should be used in the YAML file too.
+result = UserValidator.new(number: 23).validate
 
-```yaml
-# config/messages.yml
-en:
-  # ...
-    rules:
-      my_signup:
-        age:
-          gt?: "must be an adult"
-
-```
+puts result.success? # => true
+puts result.to_h # => {:number=>23}
+puts result.errors.to_h # => {}
 
-#### Internationalization (I18n)
+result = UserValidator.new(number: 11).validate
 
-If your project already depends on `i18n` gem, `Hanami::Validations` is able to look at the translations defined for that gem and to use them.
-
-
-```ruby
-class SignupValidator
-  include Hanami::Validations
-
-  messages :i18n
-
-  # ...
-end
-```
-
-```yaml
-# config/locales/en.yml
-en:
-  errors:
-    signup:
-      # ...
+puts result.success? # => true
+puts result.to_h # => {:number=>21}
+puts result.errors.to_h # => {:number=>["must be equal to 23"]}
 ```
 
 ## FAQs
@@ -784,10 +481,7 @@ Please remember that **uniqueness validation is a huge race condition between ap
 
 Please read more at: [The Perils of Uniqueness Validations](http://robots.thoughtbot.com/the-perils-of-uniqueness-validations).
 
-## Acknowledgements
-
-Thanks to [dry-rb](http://dry-rb.org) Community for their priceless support. ❤️
-`hanami-validations` uses [dry-validation](http://dry-rb.org/gems/dry-validation) as powerful low-level engine.
+If you need to implement it, please use the External dependencies feature (see above).
 
 ## Contributing