Hash Schemas

It is possible to define a type for a hash with a known set of keys and corresponding value types. Let’s say you want to describe a hash containing the name and the age of a user:

# using simple kernel coercions
user_hash = Types::Hash.schema(name: Types::Strict::String, age: Types::Coercible::Integer)

user_hash[name: 'Jane', age: '21']
# => { name: 'Jane', age: 21 }
# :name left untouched and :age was coerced to Integer

If a value doesn’t conform to the type, an error is raised:

user_hash[name: :Jane, age: '21']
# => Dry::Types::SchemaError: :Jane (Symbol) has invalid type
#    for :name violates constraints (type?(String, :Jane) failed)

All keys are required by default:

user_hash[name: 'Jane']
# => Dry::Types::MissingKeyError: :age is missing in Hash input

Extra keys are omitted by default:

user_hash[name: 'Jane', age: '21', city: 'London']
# => { name: 'Jane', age: 21 }

Default values

Default types are only evaluated if the corresponding key is missing in the input:

user_hash = Types::Hash.schema(
  name: Types::Strict::String,
  age: Types::Strict::Integer.default(18)
)
user_hash[name: 'Jane']
# => { name: 'Jane', age: 18 }

# nil violates the constraint
user_hash[name: 'Jane', age: nil]
# => Dry::Types::SchemaError: nil (NilClass) has invalid type
#    for :age violates constraints (type?(Integer, nil) failed)

In order to evaluate default types on nil, wrap your type with a constructor and map nil to Dry::Types::Undefined:

user_hash = Types::Hash.schema(
  name: Types::Strict::String,
  age: Types::Strict::Integer.
         default(18).
         constructor { |value|
           value.nil? ? Dry::Types::Undefined : value
         }
)

user_hash[name: 'Jane', age: nil]
# => { name: 'Jane', age: 18 }

The process of converting types to constructors like that can be automated, see “Type transformations” below.

Optional keys

By default, all keys are required to present in the input. However, if a type has meta omittable: true, the corresponding key can be omitted:

user_hash = Types::Hash.schema(
  name: Types::Strict::String,
  age: Types::Strict::Integer.meta(omittable: true)
)

user_hash[name: 'Jane']
# => { name: 'Jane' }

Extra keys

All keys not declared in the schema are silently ignored. This behavior can be changed by calling .strict on the schema:

user_hash = Types::Hash.schema(name: Types::Strict::String).strict
user_hash[name: 'Jane', age: 21]
# => Dry::Types::UnknownKeysError: unexpected keys [:age] in Hash input

Transforming input keys

Keys are supposed to be symbols but you can attach a key tranformation to a schema, e.g. for converting strings into symbols:

user_hash = Types::Hash.schema(name: Types::Strict::String).with_key_transform(&:to_sym)
user_hash['name' => 'Jane']

# => { name: 'Jane' }

Inheritance

Hash schemas can be inherited in a sense you can define a new schema based on an existing one. Declared keys will be merged, key and type transformations will be preserved. The strict option is also passed to the new schema if present.

# Building an empty base schema
StrictSymbolizingHash = Types::Hash.schema({}).strict.with_key_transform(&:to_sym)

user_hash = StrictSymbolizingHash.schema(
  name: Types::Strict::String
)

user_hash['name' => 'Jane']
# => { name: 'Jane' }

user_hash['name' => 'Jane', 'city' => 'London']
# => Dry::Types::UnknownKeysError: unexpected keys [:city] in Hash input

Transforming types

A schema can transform types with a block. For example, the following code makes all keys optional:

user_hash = Types::Hash.with_type_transform { |type| type.meta(omittable: true) }.schema(
  name: Types::Strict::String,
  age: Types::Strict::Integer
)

user_hash[name: 'Jane']
# => { name: 'Jane' }
user_hash[{}]
# => {}

Type transformations work perfectly with inheritance, you don’t have to define same rules more than once:

SymbolizeAndOptionalSchema = Types::Hash.
  schema({}).
  with_key_transform(&:to_sym).
  with_type_transform { |type| type.meta(omittable: true) }

user_hash = SymbolizeAndOptionalSchema.schema(
  name: Types::Strict::String,
  age: Types::Strict::Integer
)

user_hash['name' => 'Jane']

Transformation block yields a key name as second argument:

Types::Hash.with_type_transform do |type, name|
  if name.to_s.end_with?('_at')
    type.constructor { |v| Time.iso8601(v) }
  else
    type
  end
end