datacaster 2.0.2 → 3.1.0

data/README.md

@@ -1,9 +1,10 @@
 # Datacaster
 
-This gem provides run-time type checking and mapping of composite data structures (i.e. hashes/arrays of hashes/arrays of ... of literals).
+This gem provides DSL for describing in a composable manner and performing run-time type checks and transformations of composite data structures (i.e. hashes/arrays of literals). Inspired by several concepts of functional programming such as monads.
 
-Its main use is in the validation and preliminary transformation of API params requests.
+Detailed error-reporting (with full i18n support) is one of a distinct features. Let your API consumer know precisely which fields and in a what manner are wrong in a deeply nested structure!
 
+It is currently used in production in several projects (mainly as request parameter validator).
 
 # Table of contents
 
@@ -14,55 +15,62 @@ Its main use is in the validation and preliminary transformation of API params r
   - [Result value](#result-value)
   - [Hash schema](#hash-schema)
   - [Logical operators](#logical-operators)
-    - [*AND operator*:](#and-operator)
-    - [*OR operator*:](#or-operator)
-    - [*IF... THEN... ELSE operator*:](#if-then-else-operator)
+    - [*AND operator*](#and-operator)
+    - [*OR operator*](#or-operator)
+    - [*IF... THEN... ELSE operator*](#if-then-else-operator)
+    - [*SWITCH... ON... ELSE operator*](#switch-on-else-operator)
 - [Built-in types](#built-in-types)
   - [Basic types](#basic-types)
-    - [`string`](#string)
-    - [`integer`](#integer)
-    - [`float`](#float)
-    - [`decimal([digits = 8])`](#decimaldigits--8)
-    - [`array`](#array)
-    - [`hash_value`](#hash_value)
+    - [`array(error_key = nil)`](#arrayerror_key--nil)
+    - [`decimal(digits = 8, error_key = nil)`](#decimaldigits--8-error_key--nil)
+    - [`float(error_key = nil)`](#floaterror_key--nil)
+    - [`hash_value(error_key = nil)`](#hash_valueerror_key--nil)
+    - [`integer(error_key = nil)`](#integererror_key--nil)
+    - [`string(error_key = nil)`](#stringerror_key--nil)
   - [Convenience types](#convenience-types)
-    - [`non_empty_string`](#non_empty_string)
-    - [`hash_with_symbolized_keys`](#hash_with_symbolized_keys)
-    - [`integer32`](#integer32)
+    - [`hash_with_symbolized_keys(error_key = nil)`](#hash_with_symbolized_keyserror_key--nil)
+    - [`integer32(error_key = nil)`](#integer32error_key--nil)
+    - [`non_empty_string(error_key = nil)`](#non_empty_stringerror_key--nil)
   - [Special types](#special-types)
-    - [`absent`](#absent)
-    - [`any`](#any)
-    - [`transform_to_value(value)`](#transform_to_valuevalue)
-    - [`remove`](#remove)
-    - [`pass`](#pass)
-    - [`responds_to(method)`](#responds_tomethod)
-    - [`must_be(klass)`](#must_beklass)
+    - [`absent(error_key = nil)`](#absenterror_key--nil)
+    - [`any(error_key = nil)`](#anyerror_key--nil)
+    - [`default(default_value, on: nil)`](#defaultdefault_value-on-nil)
+    - [`merge_message_keys(*keys)`](#merge_message_keyskeys)
+    - [`must_be(klass, error_key = nil)`](#must_beklass-error_key--nil)
     - [`optional(base)`](#optionalbase)
+    - [`pass`](#pass)
+    - [`pass_if(base)`](#pass_ifbase)
     - [`pick(key)`](#pickkey)
-    - [`merge_message_keys(*keys)`](#merge_message_keyskeys)
+    - [`remove`](#remove)
+    - [`responds_to(method, error_key = nil)`](#responds_tomethod-error_key--nil)
+    - [`transform_to_value(value)`](#transform_to_valuevalue)
   - ["Web-form" types](#web-form-types)
-    - [`to_integer`](#to_integer)
-    - [`to_float`](#to_float)
-    - [`to_boolean`](#to_boolean)
-    - [`iso8601`](#iso8601)
+    - [`iso8601(error_key = nil)`](#iso8601error_key--nil)
     - [`optional_param(base)`](#optional_parambase)
+    - [`to_boolean(error_key = nil)`](#to_booleanerror_key--nil)
+    - [`to_float(error_key = nil)`](#to_floaterror_key--nil)
+    - [`to_integer(error_key = nil)`](#to_integererror_key--nil)
   - [Custom and fundamental types](#custom-and-fundamental-types)
-    - [`cast(name = 'Anonymous') { |value| ... }`](#castname--anonymous--value--)
-    - [`check(name = 'Anonymous', error = 'is invalid') { |value| ... }`](#checkname--anonymous-error--is-invalid--value--)
-    - [`try(name = 'Anonymous', error = 'is invalid', catched_exception:) { |value| ... }`](#tryname--anonymous-error--is-invalid-catched_exception--value--)
+    - [`cast { |value| ... }`](#cast--value--)
+    - [`check(error_key = nil) { |value| ... }`](#checkerror_key--nil--value--)
+    - [`try(error_key = nil, catched_exception:) { |value| ... }`](#tryerror_key--nil-catched_exception--value--)
     - [`validate(active_model_validations, name = 'Anonymous')`](#validateactive_model_validations-name--anonymous)
-    - [`compare(reference_value, name = 'Anonymous', error = nil)`](#comparereference_value-name--anonymous-error--nil)
-    - [`transform(name = 'Anonymous') { |value| ... }`](#transformname--anonymous--value--)
-    - [`transform_if_present(name = 'Anonymous') { |value| ... }`](#transform_if_presentname--anonymous--value--)
-  - [Passing additional context to schemas](#passing-additional-context-to-schemas)
+    - [`compare(reference_value, error_key = nil)`](#comparereference_value-error_key--nil)
+    - [`transform { |value| ... }`](#transform--value--)
+    - [`transform_if_present { |value| ... }`](#transform_if_present--value--)
   - [Array schemas](#array-schemas)
   - [Hash schemas](#hash-schemas)
     - [Absent is not nil](#absent-is-not-nil)
-    - [Schema vs Partial schema](#schema-vs-partial-schema)
+    - [Schema vs Partial schema vs Choosy schema](#schema-vs-partial-schema-vs-choosy-schema)
     - [AND with error aggregation (`*`)](#and-with-error-aggregation-)
   - [Shortcut nested definitions](#shortcut-nested-definitions)
   - [Mapping hashes: `transform_to_hash`](#mapping-hashes-transform_to_hash)
-- [Error remapping](#error-remapping)
+- [Passing additional context to schemas](#passing-additional-context-to-schemas)
+- [Error remapping: `cast_errors`](#error-remapping-cast_errors)
+- [Internationalization (i18n)](#internationalization-i18n)
+  - [Custom absolute keys](#custom-absolute-keys)
+  - [Custom relative keys and scopes](#custom-relative-keys-and-scopes)
+  - [Providing interpolation variables](#providing-interpolation-variables)
 - [Registering custom 'predefined' types](#registering-custom-predefined-types)
 - [Contributing](#contributing)
 - [Ideas/TODO](#ideastodo)
@@ -108,13 +116,13 @@ validator.("test").valid? # true
 validator.("test").value  # "test"
 validator.("test").errors # nil
 
-validator.(1)             # Datacaster::ErrorResult(["must be string"])
+validator.(1)             # Datacaster::ErrorResult(["is not a string"])
 validator.(1).valid?      # false
 validator.(1).value       # nil
-validator.(1).errors      # ["must be string"]
+validator.(1).errors      # ["is not a string"]
 ```
 
-Datacaster instances are created with a call to `Datacaster.schema { ... }`, `Datacaster.partial_schema { ... }` or `Datacaster.choosy_schema { ... }` (described later in this file).
+Datacaster instances are created with a call to `Datacaster.schema { ... }`, `Datacaster.partial_schema { ... }` or `Datacaster.choosy_schema { ... }`.
 
 Datacaster validators' results could be converted to [dry result monad](https://dry-rb.org/gems/dry-monads/1.0/result/):
 
@@ -124,7 +132,7 @@ require 'datacaster'
 validator = Datacaster.schema { string }
 
 validator.("test").to_dry_result # Success("test")
-validator.(1).to_dry_result      # Failure(["must be string"])
+validator.(1).to_dry_result      # Failure(["is not a string"])
 ```
 
 `string` method call inside of the block in the examples above returns (with the help of some basic meta-programming magic) 'chainable' datacaster instance. To 'chain' datacaster instances 'logical AND' (`&`) operator is used:
@@ -135,7 +143,7 @@ require 'datacaster'
 validator = Datacaster.schema { string & check { |x| x.length > 5 } }
 
 validator.("test1") # Datacaster::ValidResult("test12")
-validator.(1)       # Datacaster::ErrorResult(["must be string"])
+validator.(1)       # Datacaster::ErrorResult(["is not a string"])
 validator.("test")  # Datacaster::ErrorResult(["is invalid"])
 ```
 
@@ -158,7 +166,22 @@ You can call `#valid?`, `#value`, `#errors` methods directly, or, if preferred,
 
 `#value` and `#errors` would return `#nil` if the result is, correspondingly, `ErrorResult` and `ValidResult`. No methods would raise an error.
 
-Errors are returned as array or hash (or hash of arrays, or array of hashes, etc., for complex data structures). Each element of the returned array shows a separate error (as a string), and each key of the returned hash corresponds to the key of the validated hash. More or less errors are similar to what you expect from `ActiveModel::Errors#to_hash`.
+Errors are returned as array or hash (or hash of arrays, or array of hashes, etc., for complex data structures). Errors support internationalization (i18n) natively. Each element of the returned array shows a separate error as a special i18n value object, and each key of the returned hash corresponds to the key of the validated hash.
+
+In this README, instead of i18n values English strings are provided for brevity:
+
+```ruby
+array = Datacaster.schema { array }
+array.(nil)
+
+# In this README
+#=> Datacaster::ErrorResult(['should be an array'])
+
+# In reality
+#=> <Datacaster::ErrorResult([#<Datacaster::I18nValues::Key(.array, datacaster.errors.array) {:value=>nil}>])>
+```
+
+See [section on i18n](#internationalization-i18n) for details.
 
 ### Hash schema
 
@@ -184,22 +207,22 @@ person_validator.(name: "Jack Simon", salary: 50_000)
 # => Datacaster::ValidResult({:name=>"Jack Simon", :salary=>50000})
 
 person_validator.(name: "Jack Simon")
-# => Datacaster::ErrorResult({:salary=>["must be integer"]})
+# => Datacaster::ErrorResult({:salary=>["is not an integer"]})
 
 person_validator.("test")
-# => Datacaster::ErrorResult(["must be hash"])
+# => Datacaster::ErrorResult(["is not a hash"])
 
 person_validator.(name: "John Smith", salary: "1000")
-# => Datacaster::ErrorResult({:salary=>["must be integer"]})
+# => Datacaster::ErrorResult({:salary=>["is not an integer"]})
 
 person_validator.(name: :john, salary: "1000")
-# => Datacaster::ErrorResult({:name=>["must be string"], :salary=>["must be integer"]})
+# => Datacaster::ErrorResult({:name=>["is not a string"], :salary=>["is not an integer"]})
 
 person_validator.(name: "John Smith", salary: 100_000, title: "developer")
-# => Datacaster::ErrorResult({:title=>["must be absent"]})
+# => Datacaster::ErrorResult({:title=>["should be absent"]})
 ```
 
-`Datacaster.schema` definitions don't permit, as you likely noticed from the example above, extra fields in the hash. In fact, `Datacaster.schema` automatically adds special built-in validator, called `Datacaster::Terminator::Raising`, at the end of your validation chain, which function is to ensure that all hash keys had been validated.
+`Datacaster.schema` definitions don't permit, as you have likely noticed from the example above, extra fields in the hash.
 
 If you want to permit your hashes to contain extra fields, use `Datacaster.partial_schema` (it's the only difference between `.schema` and `.partial_schema`):
 
@@ -245,7 +268,7 @@ And one special: AND with error aggregation (`*`).
 
 The former 3 is described immediately below, and the latter is described in the section on hash schemas further in this file.
 
-#### *AND operator*:
+#### *AND operator*
 
 ```ruby
 even_number = Datacaster.schema { integer & check { |x| x.even? } }
@@ -256,12 +279,12 @@ even_number.(2)
 even_number.(3)
 # => Datacaster::ErrorResult(["is invalid"])
 even_number.("test")
-# => Datacaster::ErrorResult(["must be integer"])
+# => Datacaster::ErrorResult(["is not an integer"])
 ```
 
 If left-hand validation of AND operator passes, *its result* (not the original value) is passed to the right-hand validation. See below in this file section on transformations where this might be relevant.
 
-#### *OR operator*:
+#### *OR operator*
 
 ```ruby
 # 'compare' custom type returns ValidResult if and only if validated value == compare's argument
@@ -270,17 +293,62 @@ person_or_entity = Datacaster.schema { compare(:person) | compare(:entity) }
 person_or_entity.(:person) # => Datacaster::ValidResult(:person)
 person_or_entity.(:entity) # => Datacaster::ValidResult(:entity)
 
-person_or_entity.(:ngo)    # => Datacaster::ErrorResult(["must be equal to :entity"])
+person_or_entity.(:ngo)    # => Datacaster::ErrorResult(["does not equal :entity"])
 ```
 
 Notice that OR operator, if left-hand validation fails, passes the original value to the right-hand validation. As you see in the example above resultant error messages are not always convenient (i.e. to show something like "value must be :person or :entity" is preferable to showing somewhat misleading "must be equal to :entity"). See the next section on "IF... THEN... ELSE" for closer to the real world example.
 
-#### *IF... THEN... ELSE operator*:
+#### *IF... THEN... ELSE operator*
 
-Let's suppose we want to validate that incoming hash is either 'person' or 'entity', where
+Let's support we want to run different validations depending on some value, e.g.:
 
-- 'person' is a hash with 3 keys (kind: `:person`, name: string, salary: integer),
-- 'entity' is a hash with 4 keys (kind: `:entity`, title: string, form: string, revenue: integer).
+* if 'salary' is more than 100_000, check for the additional key, 'passport'
+* otherwise, ensure 'passport' key is absent
+* in any case, check that 'name' key is present and is a string
+
+```ruby
+applicant =
+  Datacaster.schema do
+    base = hash_schema(
+      name: string,
+      salary: integer
+    )
+
+    large_salary = check { |x| x[:salary] > 100_000 }
+
+    base &
+      large_salary.
+        then(passport: string).
+        else(passport: absent)
+  end
+
+applicant.(name: 'John', salary: 50_000)
+# => Datacaster::ValidResult({:name=>"John", :salary=>50000})
+
+applicant.(name: 'Jane', salary: 101_000, passport: 'AB123CD')
+# => Datacaster::ValidResult({:name=>"Jane", :salary=>101000, :passport=>"AB123CD"})
+
+applicant.(name: 'George', salary: 101_000)
+# => Datacaster::ErrorResult({:passport=>["is not a string"])
+```
+
+Formally, with `a.then(b).else(c)`:
+
+* if `a` returns `ValidResult`, then `b` is called *with the result of `a`* (not the original value) and whatever `b` returns is returned;
+* otherwise, `c` is called with the original value, and whatever `c` returns is returned.
+
+`else`-part is required and could not be omitted.
+
+Note: this construct is *not* an equivalent of `a & b | c`.
+
+With `a.then(b).else(c)` if `a` and `b` fails, then `b`'s error is returned. With `a & b | c`, instead, `c`'s result would be returned.
+
+#### *SWITCH... ON... ELSE operator*
+
+Let's suppose we want to validate that incoming hash is either 'person' or 'entity', where:
+
+* 'person' is a hash with 3 keys (kind: `:person`, name: string, salary: integer),
+* 'entity' is a hash with 4 keys (kind: `:entity`, title: string, form: string, revenue: integer).
 
 ```ruby
 person_or_entity =
@@ -296,7 +364,25 @@ person_or_entity =
     # separate entity validator (excluding validation of 'kind' field)
     entity = hash_schema(title: string, form: string, revenue: integer)
 
-    kind_is_valid & hash_schema(kind: compare(:person)).then(person).else(entity)
+
+    # 1. First option, explicit definition
+
+    kind_is_valid &
+      switch(pick(:kind)).
+        on(compare(:person), person).
+        on(compare(:entity), entity)
+
+    # 2. Second option, shortcut definiton
+
+    kind_is_valid &
+      switch(:kind).
+        on(:person, person).
+        on(:entity, entity)
+
+    # 3. Third option, using keywords args and Ruby 3.1 value omission in hash literals
+
+    kind_is_valid &
+      switch(:kind, person:, entity:)
   end
 
 person_or_entity.(
@@ -320,168 +406,132 @@ person_or_entity.(
 # => Datacaster::ErrorResult({:kind=>["is invalid"]})
 ```
 
-See below documentation on 'check' custom type to know how to provide custom error message instead of 'is invalid'.
+In our opinion the above example shows most laconic way to express underlying 'business-logic' (including elaborate error reporting on all kinds of failures) among all available competitor approaches/gems.
 
-Schema, defined above, behaves in all aspects (shown in the example and in other practical applications which might come to your mind) just as you might expect it to, after reading previous examples and the code above.
+Notice that shortcut definitions are available (illustrated in the example above) for the switch caster:
 
-In our opinion the above example shows most laconic way to express underlying 'business-logic' (including elaborate error reporting on all kinds of failures) among all available competitor approaches/gems.
+* `switch(:key)` is exactly the same as `switch(pick(:key))` (works for a string, a symbol, or an array thereof)
+* `on(:key, ...)` is exactly the same as `on(compare(:key), ...)` (works for a string or a symbol)
+* `switch([caster], on_check => on_caster, ...)` is exactly the same as `switch([caster]).on(on_check, on_caster).on(...)`
 
-Formally, with `a.then(b).else(c)`:
+`switch()` without a `base` argument will pass the incoming value to the `.on(...)` casters.
 
-* if `a` returns `ValidResult`, then `b` is called *with the result of `a`* (not the original value) and whatever `b` returns is returned;
-* otherwise, `c` is called with the original value, and whatever `c` returns is returned.
+Formally, with `switch(a).on(on_check, on_caster).else(c)`:
 
-`else`-part is required and could not be omitted.
+* if `a` returns ErrorResult, it is the result of the switch
+* otherwise, all `on_check` casters from the `.on` blocks are called with the result of `a`, until the first one which returns ValidResult is found – corresponding `on_caster` is called with the original value and its result is the result of the switch
+* if all `on_check`-s returned ErrorResult
+  * and there is an `.else` block, `c` is called with the original value and its result is the result of the switch
+  * if there is no `.else` block, `ErrorResult(['is invalid'])` is returned from the switch
 
-Note: this construct is *not* an equivalent of `a & b | c`.
+I18n keys:
 
-With `a.then(b).else(c)` if `a` and `b` fails, then `b`'s error is returned. With `a & b | c`, instead, `c`'s result would be returned.
+* all `.on` checks resulted in an error and there is no `.else`: `'.switch'`, `'datacaster.errors.switch'`
 
 ## Built-in types
 
 Full description of all built-in types follows.
 
-### Basic types
-
-#### `string`
+Under "I18n keys" error keys (in the order of priority) which caster will use for translation of error messages are provided. Each caster provides `value` variable for i18n interpolation, setting it to `#to_s` of incoming value. Some casters provide additional variables, which is mentioned in the same section. See [Internationalization (i18n)](#internationalization-i18n) for the details.
 
-Returns ValidResult if and only if provided value is a string. Doesn't transform the value.
-
-#### `integer`
-
-Returns ValidResult if and only if provided value is an integer. Doesn't transform the value.
-
-#### `float`
-
-Returns ValidResult if and only if provided value is a float (checked with Ruby's `#is_a?(Float)`, i.e. integers are not considered valid floats). Doesn't transform the value.
-
-#### `decimal([digits = 8])`
-
-Returns ValidResult if and only if provided value is either a float, integer or string representing float/integer.
-
-Transforms the value to `BigDecimal` instance.
+### Basic types
 
-#### `array`
+#### `array(error_key = nil)`
 
 Returns ValidResult if and only if provided value is an `Array`. Doesn't transform the value.
 
-#### `hash_value`
+I18n keys: `error_key`, `'.array'`, `'datacaster.errors.array'`.
 
-Returns ValidResult if and only if provided value is a `Hash`. Doesn't transform the value.
-
-Note: this type is called `hash_value` instead of `hash`, because `hash` is reserved method name in Ruby.
+#### `decimal(digits = 8, error_key = nil)`
 
-### Convenience types
+Returns ValidResult if and only if provided value is either a float, integer or string representing float/integer.
 
-#### `non_empty_string`
+Transforms the value to the `BigDecimal` instance.
 
-Returns ValidResult if and only if provided value is a string and is not empty. Doesn't transform the value.
+I18n keys: `error_key`, `'.decimal'`, `'datacaster.errors.decimal'`.
 
-#### `hash_with_symbolized_keys`
+#### `float(error_key = nil)`
 
-Returns ValidResult if and only if provided value is an instance of `Hash`. Transforms the value to `#hash_with_symbolized_keys` (requires `ActiveSupport`).
+Returns ValidResult if and only if provided value is a float (checked with Ruby's `#is_a?(Float)`, i.e. integers are not considered valid floats). Doesn't transform the value.
 
-#### `integer32`
+I18n keys: `error_key`, `'.float'`, `'datacaster.errors.float'`.
 
-Returns ValidResult if and only if provided value is an integer and it's absolute value is <= 2_147_483_647. Doesn't transform the value.
+#### `hash_value(error_key = nil)`
 
-### Special types
+Returns ValidResult if and only if provided value is a `Hash`. Doesn't transform the value.
 
-#### `absent`
+Note: this type is called `hash_value` instead of `hash`, because `hash` is a reserved method name in Ruby.
 
-Returns ValidResult if and only if provided value is `Datacaster.absent` (this is singleton instance). Relevant only for hash schemas (see below). Doesn't transform the value.
+I18n keys: `error_key`, `'.hash_value'`, `'datacaster.errors.hash_value'`.
 
-#### `any`
+#### `integer(error_key = nil)`
 
-Returns ValidResult if and only if provided value is not `Datacaster.absent` (this is singleton instance). Relevant only for hash schemas (see below). Doesn't transform the value.
+Returns ValidResult if and only if provided value is an integer. Doesn't transform the value.
 
-#### `transform_to_value(value)`
+I18n keys: `error_key`, `'.integer'`, `'datacaster.errors.integer'`.
 
-Always returns ValidResult. The value is transformed to provided argument. Is used to provide default values, e.g.:
+#### `string(error_key = nil)`
 
-```ruby
-max_concurrent_connections = Datacaster.schema { compare(nil).then(transform_to_value(5)).else(integer) }
+Returns ValidResult if and only if provided value is a string. Doesn't transform the value.
 
-max_concurrent_connections.(9)   # => Datacaster::ValidResult(9)
-max_concurrent_connections.("9") # => Datacaster::ErrorResult(["must be integer"])
-max_concurrent_connections.(nil) # => Datacaster::ValidResult(5)
-```
+I18n keys: `error_key`, `'.string'`, `'datacaster.errors.string'`.
 
-#### `remove`
-
-Equivalent to `transform_to_value(Datacaster.absent)`. Always returns ValidResult. The value is transformed to `Datacaster.absent` (see section below on hash schemas, where this is useful).
+### Convenience types
 
-#### `pass`
+#### `hash_with_symbolized_keys(error_key = nil)`
 
-Equivalent to `transform_to_value { |x| x }`. Always returns ValidResult. Doesn't transform the value. Useful to "mark" the value as validated (see section below on hash schemas, where this could be applied).
+Returns ValidResult if and only if provided value is an instance of `Hash`. Transforms the value to `#hash_with_symbolized_keys` (requires `ActiveSupport`).
 
-#### `responds_to(method)`
+I18n keys: `error_key`, `'.hash_value'`, `'datacaster.errors.hash_value'`.
 
-Returns ValidResult if and only if value `#responds_to?(method)`. Doesn't transform the value.
+#### `integer32(error_key = nil)`
 
-#### `must_be(klass)`
+Returns ValidResult if and only if provided value is an integer and it's absolute value is <= 2_147_483_647. Doesn't transform the value.
 
-Returns ValidResult if and only if value `#is_a?(klass)`. Doesn't transform the value.
+I18n keys:
 
-#### `optional(base)`
+* not an integer – `error_key`, `'.integer'`, `'datacaster.errors.integer'`
+* too big – `error_key`, `'.integer32'`, `'datacaster.errors.integer32'`
 
-Returns ValidResult if and only if value is either `Datacaster.absent` (singleton instance) or passes `base` validation. See below documentation on hash schemas for details on `Datacaster.absent`.
+#### `non_empty_string(error_key = nil)`
 
-```ruby
-item_with_optional_price =
-    Datacaster.schema do
-      hash_schema(
-        name: string,
-        price: optional(float)
-      )
-    end
+Returns ValidResult if and only if provided value is a string and is not empty. Doesn't transform the value.
 
-item_with_optional_price.(name: "Book", price: 1.23)
-# => Datacaster::ValidResult({:name=>"Book", :price=>1.23})
-item_with_optional_price.(name: "Book")
-# => Datacaster::ValidResult({:name=>"Book"})
+* not a string – `error_key`, `'.string'`, `'datacaster.errors.string'`
+* is empty – `error_key`, `'.non_empty_string'`, `'datacaster.errors.non_empty_string'`
 
-item_with_optional_price.(name: "Book", price: "wrong")
-# => Datacaster::ErrorResult({:price=>["must be float"]})
-```
+### Special types
 
-#### `pick(key)`
+#### `absent(error_key = nil)`
 
-Returns ValidResult if and only if value `#is_a?(Enumerable)`.
+Returns ValidResult if and only if provided value is `Datacaster.absent` (this is singleton instance). Relevant only for hash schemas (see below). Doesn't transform the value.
 
-Transforms the value to/returns:
+I18n keys: `error_key`, `'.absent'`, `'datacaster.errors.absent'`.
 
-* `value[key]` if key is set in the value
-* `nil` if `value[key]` is set and is nil
-* `Datacaster.absent` if key is not set
+#### `any(error_key = nil)`
 
-```ruby
-pick_name = Datacaster.schema { pick(:name) }
+Returns ValidResult if and only if provided value is not `Datacaster.absent` (this is singleton instance). Relevant only for hash schemas (see below). Doesn't transform the value.
 
-pick_name.(name: "George")       # => Datacaster::ValidResult("George")
-pick_name.(last_name: "Johnson") # => Datacaster::ValidResult(#<Datacaster.absent>)
+I18n keys: `error_key`, `'.any'`, `'datacaster.errors.any'`
 
-pick_name.("test")               # => Datacaster::ErrorResult(["must be Enumerable"])
-```
+#### `default(default_value, on: nil)`
 
-Alternative form could be used: `pick(*keys)`.
+Always returns ValidResult.
 
-In this case, an array of results is returned, each element in which corresponds to the element in `keys` array (i.e. is an argument of the `pick`) and evaluated in accordance with the above rules.
+Returns `default_value` in the following cases:
 
-```ruby
-pick_name_and_age = Datacaster.schema { pick(:name, :age) }
+* if the value is `Datacaster.absent` (`on` is disregarded in such case)
+* if `on` is set to a method name to which the value responds and yields truthy
 
-pick_name_and_age.(name: "George", age: 20)       # => Datacaster::ValidResult(["George", 20])
-pick_name_and_age.(last_name: "Johnson", age: 20) # => Datacaster::ValidResult([#<Datacaster.absent>, 20])
+Returns the initial value otherwise.
 
-pick_name_and_age.("test")                        # => Datacaster::ErrorResult(["must be Enumerable"])
-```
+Set `on` to `:nil?`, `:empty?` or similar method names.
 
 #### `merge_message_keys(*keys)`
 
-Returns ValidResult only if value `#is_a?(Hash)`.
+Returns ValidResult only if the value `#is_a?(Hash)`.
 
-Maps incoming hash to Datacaster styled messages.
+Picks given keys of incoming hash and merges their values recursively.
 
 ```ruby
 mapper =
@@ -551,7 +601,7 @@ mapping.(
 # })
 ```
 
-Hash keys with `nil` and `[]` values are deeply ignored:
+Hash keys with `nil` and `[]` values are removed recursively:
 
 ```ruby
 mapping = Datacaster.schema do
@@ -572,25 +622,111 @@ mapping.(
 #    })
 ```
 
-### "Web-form" types
+See also `#cast_errors` for [error remapping](#error-remapping-cast_errors).
 
-These types are convenient to parse and validate POST forms and decode JSON requests.
+See also `#pick` for [simpler picking of hash values](#pickkey).
 
-#### `to_integer`
+I18n keys:
 
-Returns ValidResult if and only if value is an integer, float or string representing integer/float. Transforms value to integer.
+* not a hash – `'.hash_value'`, `'datacaster.errors.hash_value'`
 
-#### `to_float`
+#### `must_be(klass, error_key = nil)`
 
-Returns ValidResult if and only if value is an integer, float or string representing integer/float. Transforms value to float.
+Returns ValidResult if and only if the value `#is_a?(klass)`. Doesn't transform the value.
 
-#### `to_boolean`
+I18n keys: `error_key`,  `'.must_be'`, `'datacaster.errors.must_be'`. Adds `reference` i18n variable, setting it to `klass.name`. 
 
-Returns ValidResult if and only if value is `true`, `1`, `'true'` or `false`, `0`, `'false'`. Transforms value to `true` or `false` (using apparent convention).
+#### `optional(base)`
 
-#### `iso8601`
+Returns ValidResult if and only if the value is either `Datacaster.absent` or passes `base` validation. See below documentation on hash schemas for details on `Datacaster.absent`.
 
-Returns ValidResult if and only if value is a string in [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) date-time format.
+```ruby
+item_with_optional_price =
+    Datacaster.schema do
+      hash_schema(
+        name: string,
+        price: optional(float)
+      )
+    end
+
+item_with_optional_price.(name: "Book", price: 1.23)
+# => Datacaster::ValidResult({:name=>"Book", :price=>1.23})
+item_with_optional_price.(name: "Book")
+# => Datacaster::ValidResult({:name=>"Book"})
+
+item_with_optional_price.(name: "Book", price: "wrong")
+# => Datacaster::ErrorResult({:price=>["is not a float"]})
+```
+
+#### `pass`
+
+Always returns ValidResult. Doesn't transform the value.
+
+Useful to "mark" the value as validated (see section below on hash schemas, where this could be applied).
+
+#### `pass_if(base)`
+
+Returns ValidResult if and only if base returns ValidResult. Returns base's error result otherwise.
+
+Doesn't transform the value: if base succeeds returns the original value (not the one that base returned).
+
+#### `pick(key)`
+
+Returns ValidResult if and only if the value `#is_a?(Enumerable)`.
+
+Transforms the value to/returns:
+
+* `value[key]` if key is set in the value
+* `nil` if `value[key]` is set and is nil
+* `Datacaster.absent` if key is not set
+
+```ruby
+pick_name = Datacaster.schema { pick(:name) }
+
+pick_name.(name: "George")       # => Datacaster::ValidResult("George")
+pick_name.(last_name: "Johnson") # => Datacaster::ValidResult(#<Datacaster.absent>)
+
+pick_name.("test")               # => Datacaster::ErrorResult(["is not Enumerable"])
+```
+
+Alternative form could be used: `pick(*keys)`.
+
+In this case, an array of results is returned, each element in which corresponds to the element in `keys` array (i.e. is an argument of the `pick`) and evaluated in accordance with the above rules.
+
+```ruby
+pick_name_and_age = Datacaster.schema { pick(:name, :age) }
+
+pick_name_and_age.(name: "George", age: 20)       # => Datacaster::ValidResult(["George", 20])
+pick_name_and_age.(last_name: "Johnson", age: 20) # => Datacaster::ValidResult([#<Datacaster.absent>, 20])
+
+pick_name_and_age.("test")                        # => Datacaster::ErrorResult(["is not Enumerable"])
+```
+
+I18n keys:
+
+* not a Enumerable – `'.must_be'`, `'datacaster.errors.must_be'`.
+
+#### `remove`
+
+Always returns ValidResult. Always returns `Datacaster.absent`.
+
+#### `responds_to(method, error_key = nil)`
+
+Returns ValidResult if and only if the value `#responds_to?(method)`. Doesn't transform the value.
+
+I18n keys: `error_key`, `'.responds_to'`, `'datacaster.errors.responds_to'`. Adds `reference` i18n variable, setting it to `method.to_s`.
+
+#### `transform_to_value(value)`
+
+Always returns ValidResult. The value is transformed to provided argument (disregarding the original value). See also [`default`](#defaultdefault_value-on-nil).
+
+### "Web-form" types
+
+These types are convenient to parse and validate POST forms and decode JSON requests.
+
+#### `iso8601(error_key = nil)`
+
+Returns ValidResult if and only if the value is a string in [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) date-time format.
 
 ```ruby
 dob = Datacaster.schema { iso8601 }
@@ -599,37 +735,53 @@ dob.("2011-02-03")
 # => Datacaster::ValidResult(#<DateTime: 2011-02-03T00:00:00+00:00 ...>)
 ```
 
-Transforms value to `DateTime` instance.
+Transforms the value to the `DateTime` instance.
+
+I18n keys: `error_key`, `'.iso8601'`, `'datacaster.errors.iso8601'`.
 
 #### `optional_param(base)`
 
-Returns ValidResult if and only if value is absent, empty string or passes `base` validation.
+Returns ValidResult if and only if the value is absent, empty string or passes `base` validation.
 
-If the value is empty string (`""`), transforms it to `Datacaster.absent` instance. It makes sense to use this type only in conjunction with hash schema validations (see below), where `Datacaster.absent` keys are removed from the resultant hash.
+If the value is empty string (`""`), transforms it to `Datacaster.absent` instance. It makes sense to use this type in conjunction with hash schema validations (see below), where `Datacaster.absent` keys are removed from the resultant hash.
 
 Otherwise, doesn't transform the value.
 
-### Custom and fundamental types
+#### `to_boolean(error_key = nil)`
+
+Returns ValidResult if and only if the value is `true`, `1`, `'true'` or `false`, `0`, `'false'`. Transforms the value to `true` or `false` (using apparent convention).
 
-These custom types (or 'meta' types) are used to create 'hand-crafted' validators.
+I18n keys: `error_key`, `'.to_boolean'`, `'datacaster.errors.to_boolean'`
 
-When `name` argument is available, that argument determines what would display with `#inspect` of that validator (and nothing else).
+#### `to_float(error_key = nil)`
 
-When `error` argument is available, that argument determines what error text (should be string, but actual error will automatically be displayed as array of strings, see examples in the previous sections of this file) will be used if validation fails.
+Returns ValidResult if and only if the value is an integer, float or string representing integer/float. Transforms value to float.
+
+I18n keys: `error_key`, `'.to_float'`, `'datacaster.errors.to_float'`
+
+#### `to_integer(error_key = nil)`
+
+Returns ValidResult if and only if the value is an integer, float or string representing integer/float. Transforms the value to the integer.
+
+I18n keys: `error_key`, `'.to_integer'`, `'datacaster.errors.to_integer'`.
+
+### Custom and fundamental types
 
-#### `cast(name = 'Anonymous') { |value| ... }`
+These types are used to create 'hand-crafted' validators.
+
+#### `cast { |value| ... }`
 
 The most basic &mdash; "fully manual" &mdash; validator.
 
-Calls block with the value. Returns whatever block returns.
+Calls the block with the value. Returns whatever the block returns.
 
-Provided block must return either `Datacaster::Result` or `Dry::Result::Monad` (the latter will automatically be converted to the former), otherwise `cast` will raise runtime `TypeError`.
+Provided block must return either a `Datacaster::Result` or a `Dry::Result::Monad` (the latter will automatically be converted to the former), otherwise `cast` will raise a runtime error.
 
 ```ruby
-# Actually, better use 'check' here instead (see below)
+# Actually, it's better to use 'check' here instead
 user_id_exists =
   Datacaster.schema do
-    cast('UserIdExists') do |user_id|
+    cast do |user_id|
       if User.exists?(user_id)
         Success(user_id) # or Datacaster::ValidResult(user_id)
       else
@@ -642,18 +794,18 @@ user_id_exists =
   end
 ```
 
-Notice, that for this example (as is written in the comment) `check` type is better option (see below). It's actually so hard to come up with an example where explicit `cast` is the best option that we didn't manage to do that. Refrain from using `cast` unless absolutely no other type could be used.
+Notice, that for this example (as is written in the comment) `check` type is a better option (see below).
 
-`cast` will transform value, if such is the logic of provided block.
+`cast` will transform the value, if such is the logic of the provided block.
 
-#### `check(name = 'Anonymous', error = 'is invalid') { |value| ... }`
+#### `check(error_key = nil) { |value| ... }`
 
-Returns ValidResult if and only if provided block returns truthy value (i.e. anything except `false` and `nil`).
+Returns ValidResult if and only if the provided block returns truthy value.
 
 ```ruby
 user_id_exists =
   Datacaster.schema do
-    check('UserIdExists', 'user is not found') do |user_id|
+    check do |user_id|
       User.exists?(user_id)
     end
   end
@@ -661,9 +813,11 @@ user_id_exists =
 
 Doesn't transform the value.
 
-#### `try(name = 'Anonymous', error = 'is invalid', catched_exception:) { |value| ... }`
+I18n keys: `error_key`, `'.check'`, `'datacaster.errors.check'`.
+
+#### `try(error_key = nil, catched_exception:) { |value| ... }`
 
-Returns ValidResult if and only if block finishes without exceptions. If block raises an exception:
+Returns ValidResult if and only if the block finishes without exceptions. If the block raises an exception:
 
 * if exception class equals to `catched_exception`, then ErrorResult is returned;
 * otherwise, exception is re-raised.
@@ -681,10 +835,10 @@ dangerous_validator =
   end
 ```
 
-As you see from the example, that's another 'meta type', which direct use is hard to justify. Consider using `check` instead (returning boolean value from the block instead of raising error).
-
 Doesn't transform the value.
 
+I18n keys: `error_key`, `'.try'`, `'datacaster.errors.try'`
+
 #### `validate(active_model_validations, name = 'Anonymous')`
 
 Requires ActiveModel.
@@ -710,7 +864,9 @@ nickname.("user32")   # Datacaster::ErrorResult(["only allows letters"])
 
 Doesn't transform the value.
 
-#### `compare(reference_value, name = 'Anonymous', error = nil)`
+I18n is performed by ActiveModel gem.
+
+#### `compare(reference_value, error_key = nil)`
 
 This type is the way to ensure some value in your schema is some predefined "constant".
 
@@ -725,9 +881,11 @@ agreed_with_tos =
   end
 ```
 
-#### `transform(name = 'Anonymous') { |value| ... }`
+I18n keys: `error_key`, `'.compare'`, `'datacaster.errors.compare'`. Adds `reference` i18n variable, setting it to `reference_value.to_s`.
+
+#### `transform { |value| ... }`
 
-Always returns ValidResult. Transforms the value: returns whatever block returned, automatically wrapping it into `ValidResult`.
+Always returns ValidResult. Transforms the value: returns whatever the block has returned.
 
 ```ruby
 city =
@@ -742,81 +900,34 @@ city =
 city.(name: "Denver", distance: "2.5") # => Datacaster::ValidResult({:name=>"Denver", :distance=>4.02335})
 ```
 
-#### `transform_if_present(name = 'Anonymous') { |value| ... }`
+#### `transform_if_present { |value| ... }`
 
-Always returns ValidResult. If the value is `Datacaster.absent` (singleton instance, see below section on hash schemas), then `Datacaster.absent` is returned (block isn't called). Otherwise, works like `transform`.
-
-###  Passing additional context to schemas
-
-You can pass `context` to schema using `.with_context` method
-
-```ruby
-# class User < ApplicationRecord
-#  ...
-# end
-#
-# class Post < ApplicationRecord
-#   belongs_to :user
-#   ...
-# end
-
-schema =
-  Datacaster.schema do
-    hash_schema(
-      post_id: to_integer & check { |id| Post.where(id: id, user_id: context.current_user).exists? }
-    )
-  end
-
-current_user = ...
-
-schema.with_context(current_user: current_user).(post_id: 15)
-```
-
-`context` is an [OpenStruct](https://ruby-doc.org/stdlib-3.1.0/libdoc/ostruct/rdoc/OpenStruct.html) instance which is initialized in `.with_context`
-
-**Note**
-
-`context` can be accesed only in types' blocks:
-```ruby
-mail_transformer = Datacaster.schema { transform { |v| "#{v}#{context.postfix}" } }
-
-mail_transformer.with_context(postfix: "@domen.com").("admin")
-# => #<Datacaster::ValidResult("admin@domen.com")>
-```
-It can't be used in schema definition block itself:
-```ruby
-Datacaster.schema { context.error }
-# leads to `NoMethodError`
-```
+Always returns ValidResult. If the value is `Datacaster.absent`, then `Datacaster.absent` is returned (the block isn't called). Otherwise, works like [`transform`](#transform--value).
 
 ### Array schemas
 
-To define compound data type, array of 'something', use `array_schema(something)` (or, synonymically, `array_of(something)`). There is no way to define array wherein each element is of different type.
+To define compound data type, array of 'something', use `array_schema(something)` (or the alias `array_of(something)`). There is no built-in way to define an array wherein each element is of a different type.
 
 ```ruby
 salaries = Datacaster.schema { array_of(integer) }
 
 salaries.([1000, 2000, 3000]) # Datacaster::ValidResult([1000, 2000, 3000])
 
-salaries.(["one thousand"])   # Datacaster::ErrorResult({0=>["must be integer"]})
-salaries.(:not_an_array)      # Datacaster::ErrorResult(["must be array"])
-salaries.([])                 # Datacaster::ErrorResult(["must not be empty"])
+salaries.(["one thousand"])   # Datacaster::ErrorResult({0=>["is not an integer"]})
+salaries.(:not_an_array)      # Datacaster::ErrorResult(["should be an array"])
+salaries.([])                 # Datacaster::ErrorResult(["should not be empty"])
 ```
 
 To allow empty array use the following construct: `compare([]) | array_of(...)`.
 
-If you want to define array of hashes, shortcut definition could be used: instead of `array_of(hash_schema({...}))` use `array_of({...})`:
+If you want to define an array of hashes, [shortcut definition](#shortcut-nested-definitions) could be used: instead of `array_of(hash_schema({...}))` use `array_of({...})`:
 
 ```ruby
 people =
   Datacaster.schema do
     array_of(
-      # hash_schema(
-      {
-        name: string,
-        salary: float
-      }
-      # )
+      name: string,
+      salary: float
     )
   end
 
@@ -826,25 +937,30 @@ people.([person1, person2]) # => Datacaster::ValidResult([{...}, {...}])
 
 people.([{salary: 250_000.0}, {salary: "50000"}])
 # => Datacaster::ErrorResult({
-#   0 => {:name => ["must be string"]},
-#   1 => {:name => ["must be string"], :salary => ["must be float"]}
+#   0 => {:name => ["is not a string"]},
+#   1 => {:name => ["is not a string"], :salary => ["is not a float"]}
 # })
 ```
 
-Notice, that extra keys of inner hashes could be validated only if each element is otherwise valid. In other words, if some of the elements have other validation errors, then "extra key must be absent" validation error won't appear on any element.
+Notice that extra keys of inner hashes could be validated only if each element is otherwise valid. In other words, if some of the elements have other validation errors, then "extra key must be absent" validation error won't appear on any element. This could be avoided by using nested `Datacaster.schema` call to define element schema instead of shortcut definition or `hash_schema` call.
 
-Formally, `array_of(x)` will return ValidResult if and only if:
+Formally, `array_of(x, error_keys = {})` will return ValidResult if and only if:
 
 a) provided value implements basic array methods (`#map`, `#zip`),  
 b) provided value is not `#empty?`,  
 c) each element of the provided value passes validation of `x`.
 
-If a) fails, `ErrorResult(["must be array"])` is returned.  
-If b) fails, `ErrorResult(["must not be empty"])` is returned.  
+If a) fails, `ErrorResult(["should be an array"]) is returned. 
+If b) fails, `ErrorResult(["should not be empty"])` is returned.  
 If c) fails, `ErrorResult({0 => ..., 1 => ...})` is returned. Wrapped hash contains keys which correspond to initial array's indices, and values correspond to failure returned from `x` validator, called for the corresponding element.
 
 Array schema transforms array if inner type (`x`) transforms element (in this case `array_schema` works more or less like `map` function). Otherwise, it doesn't transform.
 
+I18n keys:
+
+* not an array – `error_keys[:array]`, `'.array'`, `'datacaster.errors.array'`
+* empty array – `error_keys[:empty]`, `'.empty'`, `'datacaster.errors.empty'`
+
 ### Hash schemas
 
 Hash schemas are "bread and butter" of Datacaster.
@@ -864,7 +980,7 @@ person.(name: "John Smith", salary: 100_000)
 # => Datacaster::ValidResult({:name=>"John Smith", :salary=>100000})
 
 person.(name: "John Smith", salary: "100_000")
-# => Datacaster::ErrorResult({:salary=>["must be integer"]})
+# => Datacaster::ErrorResult({:salary=>["is not an integer"]})
 ```
 
 Formally, hash schema returns ValidResult if and only if:
@@ -873,17 +989,19 @@ a) provided value `is_a?(Hash)`,
 b) all values, fetched by keys mentioned in `hash_schema(...)` definition, pass corresponding validations,  
 c) after all checks (including logical operators), there are no unchecked keys in the hash.
 
-If a) fails, `ErrorResult(["must be hash"])` is returned.  
+If a) fails, `ErrorResult(["is not a hash"])` is returned.  
 if b) fails, `ErrorResult(key1 => [errors...], key2 => [errors...])` is returned. Each key of wrapped "error hash" corresponds to the key of validated hash, and each value of "error hash" contains array of errors, returned by the corresponding validator.  
-If b) fulfilled, then and only then validated hash is checked for extra keys. If they are found, `ErrorResult(extra_key_1 => ["must be absent"], ...)` is returned.
+If b) is fulfilled, then and only then validated hash is checked for extra keys. If they are found, `ErrorResult(extra_key_1 => ["should be absent"], ...)` is returned.
 
-Technically, last part is implemented with special singleton validator, called `#<Datacaster::Terminator::Raising>`, which is automatically added to the validation chain (with the use of `&` operator) by `Datacaster.schema` method. Don't be scared if you see it in the output of `#inspect` method of your validators (e.g. in `irb`).
+I18n keys:
+
+* not a hash – `error_key`, `'.hash_value'`, `'datacaster.errors.hash_value'`
 
 #### Absent is not nil
 
 In practical tasks it's important to distinguish between absent (i.e. not set or deleted) and `nil` values of a hash.
 
-To check some value for `nil`, use ordinary `compare(nil)` validator, mentioned above.
+To check some value for `nil`, use [`compare(nil)`](#comparereference_value-error_key--nil).
 
 To check some value for absence, use `absent` validator:
 
@@ -900,14 +1018,14 @@ restricted_params.(username: "test")
 # => Datacaster::ValidResult({:username=>"test"})
 
 restricted_params.(username: "test", is_admin: true)
-# => Datacaster::ErrorResult({:is_admin=>["must be absent"]})
+# => Datacaster::ErrorResult({:is_admin=>["should be absent"]})
 restricted_params.(username: "test", is_admin: nil)
-# => Datacaster::ErrorResult({:is_admin=>["must be absent"]})
+# => Datacaster::ErrorResult({:is_admin=>["should be absent"]})
 ```
 
 More practical case is to include `absent` validator in logical expressions, e.g. `something: absent | string`. If `something` is set to `nil`, this validation will fail, which could be the desired (and hardly achieved by any other validation framework) behavior.
 
-Also, see documentation for `optional(base)` and `optional_param(base)` above. If some value becomes `Datacaster.absent` in its chain of validations-transformations, it is removed from the resultant hash (on the same stage where the lack of extra/unchecked keys in the hash is validated):
+Also, see documentation for [`optional(base)`](#optionalbase) and [`optional_param(base)`](#optional_parambase). If some value becomes `Datacaster.absent` in its chain of validations-transformations, it is removed from the resultant hash (on the same stage where the lack of extra/unchecked keys in the hash is validated):
 
 ```ruby
 person =
@@ -924,10 +1042,10 @@ person.(name: "John Smith")
 # => Datacaster::ValidResult({:name=>"John Smith"})
 
 person.(name: "John Smith", dob: "invalid date")
-# => Datacaster::ErrorResult({:dob=>["must be iso8601 string"]})
+# => Datacaster::ErrorResult({:dob=>["is not a string with ISO-8601 date and time"]})
 ```
 
-Another use-case for `Datacaster.absent` is to directly set some key to that value. In that case, it will be removed from the resultant hash. The most convenient way to do that is to use `remove` type (described above in this file):
+Another use case for `Datacaster.absent` is to directly set some key to that value. In that case, it will be removed from the resultant hash. The most convenient way to do that is to use the [`remove`](#remove) cast:
 
 ```ruby
 anonimized_person =
@@ -942,9 +1060,9 @@ anonimized_person.(name: "John Johnson", dob: "1990-05-23")
 # => Datacaster::ValidResult({:dob=>"1990-05-23"})
 ```
 
-Note: we need to `pass` `dob` field to "mark" it as validated, otherwise `Datacaster.schema` will return ErrorResult, notifying that unchecked extra field was in the initial hash.
+Note: we need to `pass` `dob` field to "mark" it as validated, otherwise `Datacaster.schema` will return `ErrorResult`, notifying that unchecked extra field was in the initial hash.
 
-#### Schema vs Partial schema
+#### Schema vs Partial schema vs Choosy schema
 
 As written in the beginning of this section on `hash_schema`, at the last stage of validation it is ensured that hash contains no extra keys.
 
@@ -1006,7 +1124,7 @@ RecordValidator =
   end
 ```
 
-See "IF... THEN... ELSE" section above in this file for full description of how `a.then(b).else(c)` validator works.
+See also ["IF... THEN... ELSE"](#if-then-else-operator) section.
 
 Examples of how this validator would work:
 
@@ -1028,15 +1146,17 @@ RecordValidator.(
   description: 'CEO',
   extra: :key
 )
-# => Datacaster::ErrorResult({:extra=>["must be absent"]})
+# => Datacaster::ErrorResult({:extra=>["should be absent"]})
 ```
 
-Note that only the usage of `Datacaster.partial_schema` instead of `Datacaster.schema` allowed us to compose several `hash_schema`s from different files (from different calls to Datacaster API).
+Notice that only the usage of `Datacaster.partial_schema` instead of `Datacaster.schema` allowed us to compose several `hash_schema`s from different files (from different calls to Datacaster API).
 
 Had we used `schema` everywhere, `CommonFieldsValidator` would return failure for records which are supposed to be valid, because they would contain "extra" (i.e. not defined in `CommonFieldsValidator` itself) keys (e.g. `name` for person).
 
 As a rule of thumb, use `partial_schema` in any "intermediary" validators (extracted for the sake of clarity of code and reusability) and use `schema` in any "end" validators (ones which receive full record as input and use intermediary validators behind the scenes).
 
+Lastly, if you want to just delete extra unvalidated keys without returning a error, use `choosy_schema`.
+
 #### AND with error aggregation (`*`)
 
 Often it is useful to run validator which are "further down the conveyor" (i.e. placed at the right-hand side of AND operator `&`) even if current (i.e. left-hand side) validator has failed.
@@ -1068,10 +1188,10 @@ This code will work as expected (i.e. `RecordValidator`, the "end" validator, wi
 
 ```ruby
 RecordValidator.(kind: 'person', name: 1)
-# => Datacaster::ErrorResult({:description=>["must be string"]})
+# => Datacaster::ErrorResult({:description=>["is not a string"]})
 ```
 
-It correctly returns `ErrorResult`, but it doesn't mention that in addition to `description` being wrongfully absent, `name` field is of wrong type (integer instead of string). That could be inconvenient where Datacaster is used, for example, as a params validator for an API service: end user of the API would need to repeatedly send requests, essentially "brute forcing" his way in through all the errors (fixing them one by one), instead of having the list of all errors in one iteration.
+It correctly returns `ErrorResult`, but it doesn't mention that in addition to `description` being wrongfully absent, `name` field is of the wrong type (integer instead of string). Such error reporting would be incomplete.
 
 Specifically to resolve this, "AND with error aggregation" (`*`) operator should be used in place of regular AND (`&`):
 
@@ -1082,12 +1202,12 @@ RecordValidator =
   end
 
 RecordValidator.(kind: 'person', name: 1)
-# => Datacaster::ErrorResult({:description=>["must be string"], :name=>["must be string"]})
+# => Datacaster::ErrorResult({:description=>["is not a string"], :name=>["is not a string"]})
 ```
 
 Note: "star" (`*`) has been chosen arbitrarily among available Ruby operators. It shouldn't be read as multiplication (and, in fact, in Ruby it is used not only as multiplication sign).
 
-Described in this example is the only case where `*` and `&` differ: in all other aspects they are full equivalents.
+Described in this example is the only case where `*` and `&` differ: in all other aspects they are fully equivalent.
 
 Formally, "AND with error aggregation" (`*`):
 
@@ -1096,9 +1216,9 @@ b) in all other cases behaves as regular "AND" (`&`).
 
 ### Shortcut nested definitions
 
-Datacaster aimed at ease of use where multi-level embedded structures need to be validated, boilerplate reduced to inevitable minimum.
+Datacaster aimed at thr ease of use where multi-level embedded structures need to be validated, boilerplate reduced to inevitable minimum.
 
-The words `hash_schema` and `array_schema`/`array_of` could be, therefore, omitted from the definition of nested structures (replaced with `{...}` and `[...]` correspondingly):
+The words `hash_schema` and `array_schema`/`array_of` could be omitted from the definition of nested structures (replaced with `{...}` and `[...]`):
 
 ```ruby
 # full definition
@@ -1140,11 +1260,11 @@ person =
   end
 ```
 
-Note: in "root" scope (immediately inside of `schema { ... }` block) words `hash_schema` and `array_of` are still required. We consider that allowing to omit them as well would hurt readability of code.
+Note: in the "root" scope (immediately inside of `schema { ... }` block) the words `hash_schema` and `array_of` are still required. We consider that allowing to omit them as well would hurt readability of the code.
 
 ### Mapping hashes: `transform_to_hash`
 
-One common task in processing compound data structures is to map one set of hash keys to another set. That's where `transform_to_hash` type comes to play (see also `pluck` and `remove` description above in this file).
+One common task in processing compound data structures is to map one set of hash keys to another set. That's where `transform_to_hash` type comes to play (see also [`pick`](#pickkey) and [`remove`](#remove)).
 
 ```ruby
 city_with_distance =
@@ -1160,7 +1280,7 @@ city_with_distance.(distance_in_meters: 1200.0)
 # => Datacaster::ValidResult({:distance_in_km=>1.2, :distance_in_miles=>1.9307999999999998})
 ```
 
-Of course, order of keys in the definition hash doesn't change anything.
+Of course, order of keys in the definition hash doesn't change the result.
 
 Formally, `transform_to_hash`:
 
@@ -1168,7 +1288,7 @@ a) transforms (any) value to hash;
 b) this hash will contain keys listed in `transform_to_hash` definition;  
 c) value of these keys will be: initial value (*not the corresponding key of it, the value altogether*) transformed with the corresponding validator/type;  
 d) if any of the values from c) happen to be `Datacaster.absent`, this value *with its key* is removed from the resultant hash;  
-e) if the initial value happens to also be a hash, all its keys, except those which had been transformed, are merged to the resultant hash.
+e) if the initial value happens to also be a hash, all its unvalidated (unused) keys are merged to the resultant hash.
 
 `transform_to_hash` will return ValidResult if and only if all transformations return ValidResults.
 
@@ -1178,15 +1298,56 @@ Here is what is happening when `city_with_distance` (from the example above) is
 
 * Initial hash `{distance_in_meters: 1200}` is passed to `transform_to_hash`
 * `transform_to_hash` reads through its definition and creates resultant hash with the keys `distance_in_km`, `distance_in_miles`, `distance_in_meters`
-* The key `distance_in_km` of the resultant hash in the transformation of the initial hash: firstly, hash is transformed to the value of its key with `pluck`, then that value is divided by 1000
+* The key `distance_in_km` of the resultant hash is the transformation of the initial hash: firstly, hash is transformed to the value of its key with `pick`, then that value is divided by 1000
 * Similarly, `distance_in_miles` value is built
 * `distance_in_meters` value is created by transforming initial value to `Datacaster.absent` (that is how `remove` works)
 
-Note: because of point e) above we need to explicitly delete `distance_in_meters` key, because otherwise `transform_to_hash` will copy it to the resultant hash without validation. And all non-validated keys at the end of `Datacaster.schema` block (as explained above in section on partial schemas) result in error.
+Note: because of point e) above we need to explicitly delete `distance_in_meters` key, because otherwise `transform_to_hash` will copy it to the resultant hash without validation. And exitence of non-validated keys at the end of `Datacaster.schema` block results in an error result.
 
-## Error remapping
+##  Passing additional context to schemas
 
-In some cases it might be useful to remap resulting `Datacaster::ErrorResult`:
+It is often useful to extract common data which is used in validations, but not a main subject of validations, to a separate context object.
+
+This can be achived by using `#with_context`, which makes provided context available in the `context` structure:
+
+```ruby
+# class User < ApplicationRecord
+#  ...
+# end
+#
+# class Post < ApplicationRecord
+#   belongs_to :user
+#   ...
+# end
+
+schema =
+  Datacaster.schema do
+    hash_schema(
+      post_id: to_integer & check { |id| Post.where(id: id, user_id: context.current_user).exists? }
+    )
+  end
+
+current_user = ...
+
+schema.with_context(current_user: current_user).(post_id: 15)
+```
+
+`context` is an [OpenStruct](https://ruby-doc.org/stdlib-3.1.0/libdoc/ostruct/rdoc/OpenStruct.html) instance.
+
+**Note**
+
+`context` can be accesed only in casters' blocks. It can't be used in schema definition itself:
+
+```ruby
+# will raise NoMethodError
+Datacaster.schema { context.error }
+```
+
+## Error remapping: `cast_errors`
+
+Validation often includes [remapping](#mapping-hashes-transform_to_hash) of hash keys. In such cases errors require remapping back to the original keys.
+
+Let's see an example:
 
 ```ruby
 schema =
@@ -1197,11 +1358,11 @@ schema =
     )
   end
 
-schema.(user_id: 'wrong')  # => #<Datacaster::ErrorResult({:posts=>["must be integer"]})>
-# Instead of #<Datacaster::ErrorResult({:user_id=>["must be integer"]})>
+schema.(user_id: 'wrong')  # => #<Datacaster::ErrorResult({:posts=>["is not an integer"]})>
+# Instead of #<Datacaster::ErrorResult({:user_id=>["is not an integer"]})>
 ```
 
-`.cast_errors` can be used in such case:
+`.cast_errors` can be used to remap errors back:
 
 ```ruby
 schema =
@@ -1219,10 +1380,166 @@ schema =
     )
   end
 
-schema.(user_id: 'wrong')  # => #<Datacaster::ErrorResult({:user_id=>["must be integer"]})>
+schema.(user_id: 'wrong')  # => #<Datacaster::ErrorResult({:user_id=>["is not an integer"]})>
+```
+
+`.cast_errors` will extract errors from the `ErrorResult` and provide them as value for the provided caster. If that caster returns `ErrorResult`, runtime exception is raised. If that caster returns `ValidResult`, it is packed back into `ErrorResult` and returned.
+
+Any instance of `Datacaster` supports `#cast_errors`.
+
+See also [merge_message_keys](#merge_message_keyskeys) caster.
+
+## Internationalization (i18n)
+
+Datacaster natively supports i18n. Default messages (their keys are listed under "I18n keys" in the caster descriptions) are packed with the gem: [`en.yml`](config/locales/en.yml).
+
+There are several ways to customize messages, described in this section.
+
+### Custom absolute keys
+
+There are two ways to set absolute error key (i.e. key with full path to an error inside of a yml i18n file).
+
+Let's consider the following i18n file:
+
+```yml
+en:
+  user:
+    errors:
+      not_found: User %{value} has not been found
+```
+
+Interpolated i18n variable `value` is added automatically for all built-in casters.
+
+Firstly, you can set `error_key` of a caster:
+
+```ruby
+schema = Datacaster.schema { check('user.errors.not_found') { false } }
+schema.('john').errors # ['User john has not been found']
+```
+
+Secondly, you can call `#i18n_key` on a caster:
+
+```ruby
+schema =
+  Datacaster.schema do
+    check { false }.i18n_key('user.errors.not_found')
+  end
+
+schema.('john').errors # ['User john has not been found']
+```
+
+### Custom relative keys and scopes
+
+More often it is required to set specific i18n namespace for the whole validation schema. There is a manual way to do it with `#i18n_scope` and automatic scoping for hashes.
+
+Let's consider the following i18n file:
+
+```yml
+en:
+  user:
+    errors:
+      not_found: User has not been found
+    name:
+      wrong_format: wrong format
+```
+
+Let's gradually reduce the boilerplate, starting with the most explicit example. Notice that all relative keys (i.e. keys which will be scoped during the execution) start with `'.'`:
+
+```ruby
+schema =
+  Datacaster.schema(i18n_scope: 'user') do
+    check { |v| v[:id] == 1 }.i18n_key('.errors.not_found') &
+      hash_schema(
+        name: check { false }.i18n_key('.name.wrong_format')
+      )
+  end
+
+schema.({id: 3}).errors # ['User has not been found']
+schema.({id: 1, name: 'wrong'}).errors # {name: ['wrong format']}
+```
+
+To reduce the boilerplate, Datacaster will infer scopes from hash key names:
+
+```ruby
+schema =
+  Datacaster.schema(i18n_scope: 'user') do
+    check { |v| v[:id] == 1 }.i18n_key('.errors.not_found') &
+      hash_schema(
+        # '.wrong_format' inferred to be '.name.wrong_format'
+        name: check { false }.i18n_key('.wrong_format')
+      )
+  end
+
+schema.({id: 1, name: 'wrong'}).errors # {name: ['wrong format']}
+```
+
+Relative keys can be set as `error_key` argument of casters:
+
+```ruby
+schema =
+  Datacaster.schema(i18n_scope: 'user') do
+    check('.errors.not_found') { |v| v[:id] == 1 } &
+      hash_schema(
+        # '.wrong_format' inferred to be '.name.wrong_format'
+        name: check('.wrong_format') { false }
+      )
+  end
+
+schema.({id: 1, name: 'wrong'}).errors # {name: ['wrong format']}
+```
+
+When feasible, format yaml file in accordance with the default casters' keys. However, with this approach often key names wouldn't make much sense in the application context:
+
+```yml
+en:
+  user:
+    check: User has not been found
+    name:
+      check: wrong format
+```
+
+```ruby
+schema =
+  # Only root scope is set, no other boilerplate
+  Datacaster.schema(i18n_scope: 'user') do
+    check { |v| v[:id] == 1 } &
+      hash_schema(
+        name: check { false }
+      )
+  end
+
+schema.({id: 3}).errors # ['User has not been found']
+schema.({id: 1, name: 'wrong'}).errors # {name: ['wrong format']}
+```
+
+Use `#raw_errors` instead of `#errors` to get errors just before the I18n backend is called. This will allow to see all the i18n keys in the order of priority which will be used to produce final error messages.
+
+Notice that the use of `.i18n_scope` prevents auto-scoping of hash key:
+
+```ruby
+schema =
+  # Only root scope is set, no other boilerplate
+  Datacaster.schema(i18n_scope: 'user') do
+    hash_schema(
+      name: check { false }.i18n_scope('.data')
+    )
+  end
+
+# will search for the following keys:
+# - "user.data.check"
+# - "datacaster.errors.check"
+schema.(name: 'john').raw_errors
 ```
-any instance of `Datacaster` can be passed to `.cast_errors`
 
+### Providing interpolation variables
+
+Every caster will automatically provide `value` variable for i18n interpolation.
+
+All keyword arguments of `#i18n_key`, `#i18n_scope` and designed for that sole purpose `#i18n_vars` are provided as interpolation variables on i18n.
+
+It is possible to add i18n variables at the runtime (e.g. inside `check { ... }` block) by calling `i18n_vars!(variable: 'value')` or `i18n_var!(:variable, 'value')`.
+
+Outer calls of `#i18n_key` (`#i18n_scope`, `#i18n_vars`) have presedence before the inner if variable names collide. However, runtime calls of `#i18n_vars!` and `#i18n_var!` overwrite compile-time variables from the next nearest key, scope or vars on collision.
 
 ## Registering custom 'predefined' types