Simple and composable validation and coercion of data structures. It also includes a ValueObject for convenience.
Add this line to your application's Gemfile:
gem 'definition'
And then execute:
$ bundle
Or install it yourself as:
$ gem install definition
Definitions can be used to validate data structures like for example Hashes:
schema = Definition.Keys do
required :first_name, Definition.Type(String)
required :last_name, Definition.Type(String)
optional :birthday, Definition.Type(Date)
end
conform_result = schema.conform({first_name: "John", last_name: "Doe", birthday: Date.today})
conform_result.passed? # => true
conform_result = schema.conform({first_name: "John", last_name: "Doe", birthday: "2018/02/09"})
conform_result.passed? # => false
conform_result.error_message # => hash fails validation for key birthday: { Is of type String instead of Date }
conform_result.error_hash # =>
# {
# :birthday => [
# [0] <Definition::ConformError
# description: "hash fails validation for key birthday: { Is of type String instead of Date }",
# json_pointer: "/birthday">
# ]
# }
But it can also transform those data structures at the same time. The following example shows how a Unix timestamp in milliseconds can be transformed to a Time object while validating:
milliseconds_time_definition = Definition.Lambda(:milliseconds_time) do |value|
conform_with(Time.at(value.to_r / 1000).utc) if value.is_a?(Integer)
end
schema = Definition.Keys do
required :title, Definition.Type(String)
required :body, Definition.Type(String)
optional :publication_date, milliseconds_time_definition
end
conform_result = schema.conform({title: "My first blog post", body: "Shortest one ever!", publication_date: 1546170180339})
conform_result.passed? # => true
conform_result.value # => {title: "My first blog post", body: "Shortest one ever!", publication_date: 2018-12-30 11:43:00 UTC}
Because definitions do not only validate input but also transform input, we use
the term conform
which stands for validation and coercion.
For end users you best use the translated errors that you get from definition:
schema = Definition.Keys do
required :title, Definition.NonEmptyString
required :body, Definition::And(
Definition.Type(String),
Definition.MinSize(100)
)
end
conform_result = schema.conform({title: "", body: "this is not long enough"})
conform_result.errors # => returns an array of Definition::ConformError
conform_result.errors.each do |error|
puts "----"
puts error.json_pointer # provides a path to the invalid value, also works with nested objects and arrays
puts error.translated_error
end
# =>
# ----
# /title
# Value is shorter than 1
# ----
# /body
# Value is shorter than 100
The error messages are only translated into English for now, but you can add or change translations by adding a yaml file like this to your I18n load path.
To get a quick error summary during debugging, you can also use conform_result.error_message
Instead of getting a flat array of all errors via conform_result.errors
, you can also get a hierarchical representation:
conform_result.error_hash
# =>
# {
# :title => [
# [0] <Definition::ConformError
# message: "hash fails validation for key title: { Not all definitions are valid for 'non_empty_string': { Did not pass test for min_size (1) } }",
# json_pointer: "/title">
# ],
# :body => [
# [0] <Definition::ConformError
# message: "hash fails validation for key body: { Not all definitions are valid for 'and': { Did not pass test for min_size (100) } }",
# json_pointer: "/body">
# ]
# }
Hashes can be conformed by using the Keys
definition. It allows you to configure
required and optional attributes. The first argument of required
and optional
takes either Symbols or Strings. If you use a Symbol, then the validated Hash
needs to have a Symbol key with that name, otherwise a string key.
The key definition will also fail if the input value contains extra keys.
You can configure default values for optional keys, see the following example.
Definition.Keys do
required :title, Definition.NonEmptyString
optional :publication_date, Definition.Type(Date)
optional :is_draft, Definition.Boolean, default: true
end
By default the Keys
Definition does not conform with input hashes that contains
keys that are not defined in the Definition. You can set the :ignore_extra_keys
option to disable this.
schema = Definition.Keys do
option :ignore_extra_keys
required :title, Definition.NonEmptyString
optional :publication_date, Definition.Type(Time)
end
conform_result = schema.conform({title: "My first blog post", body: "Shortest one ever!", publication_date: Time.new})
conform_result.passed? # => true
conform_result.value # => {title: "My first blog post", publication_date: 2018-12-30 11:43:00 UTC}
This will validate that the value is of the specified type.
Definition.Type(String)
Definition.Type(Float)
Definition.Type(MyClass)
Definition.Type(MyClass).conform(0.1).passed? # => false
Definition.Type(MyClass).conform(MyClass.new).passed? # => true
This will validate that the value is of the specified type. But if its not it will try to coerce it into that type. This Definition works only with primitive types.
Definition.CoercibleType(String) # Uses String() to coerce values
Definition.CoercibleType(Float) # Uses Float() to coerce values
Definition.CoercibleType(Float).conform("0.1").passed? # => true
Definition.CoercibleType(Float).conform("0.1").value # => 0.1
Definition.And(definition1, definition2, ...)
This definition will only conform if all definitions conform. The definitions will be processed from left to right and the output of the previous will be the input of the next. Processing of the And-Definition stops as soon as one definition does not conform.
Definition.Or(definition1, definition2, ...)
This definition will conform if at least one definition conforms. The definitions will be processed from left to right and stop as soon as a definition conforms. The output of that definition will be the output of the Or definition.
Definition.Each(item_definition)
Definition.Each(Definition.Type(Integer)).conform([1,2,3,"4"]).error_message
# => Not all items conform with each: { Item "4" did not conform to each: { Is of type String instead of Integer } }
This definition will only conform if all elements of the value conform to the
item_definition
.
Definition.Lambda(:password) do |value|
matches = Regexp.new(/^
(?=.*[a-z]) # should contain at least one lower case letter
(?=.*[A-Z]) # should contain at least one upper case letter
(?=.*\d) # should contain at least one digit
.{6,50} # should be between 6 and 50 characters long
$/x).match(value.to_s)
conform_with(value) if matches
end
This definition can be used to build any custom validation or coercion you want. The example above makes sure that a password conforms with a set of rules.
The block gets the input value as argument and you can do any transformation or
validation on it that you want. If you determine that the value is valid, then
you must call conform_with
and pass it the value you want to return. This can
either be the original value or any transformed version of it. By not calling
conform_with
you tell the definition to fail for the current input value.
The first argument of Definition.Lambda
is a name you can give this definition.
It will only be used in the error message to make it more readable.
If you want to provide detailed custom error messages you can use fail_with
:
Definition.Lambda(:password) do |value|
if !value.match(/[a-z]+/)
fail_with("must contain at least one lower case letter")
elsif !value.match(/[A-Z]+/)
fail_with("must contain at least one upper case letter")
elsif !value.match(/\d+/)
fail_with("must contain at least one digit")
elsif value.size < 6 || value.size > 50
fail_with("must be between 6 and 50 characters long")
else
conform_with(value)
end
end
Definitions are reusable and can be easily composed:
country_code_definition = Definition.Lambda(:iso_county_code) do |value|
if iso_code = IsoCountryCodes.find(value)
conform_with(iso_code.alpha2)
end
end
address_definition = Definition.Keys do
required :street, Definition.Type(String)
required :postal_code, Definition.Type(String)
required :country_code, country_code_definition
end
order = Definition.Keys do
required :user, user_definition
required :invoice_address, address_definition
required :shipping_address, address_definition
end
Besides composing Definitions, you can also include Keys
Definitions in each
other. This will basically copy all required and optional keys as well as defaults into the other definition.
address_definition = Definition.Keys do
required :street, Definition.Type(String)
required :postal_code, Definition.Type(String)
required :country_code, Definition.Type(String)
end
user_definition = Definition.Keys do
required :user, user_definition
include address_definition
end
Above Definition will equal the following:
user_definition = Definition.Keys do
required :user, user_definition
required :street, Definition.Type(String)
required :postal_code, Definition.Type(String)
required :country_code, Definition.Type(String)
end
Definition.MaxSize(5).conform("house") # => pass
Definition.MaxSize(5).conform([1,2,3,4,5]) # => pass
Definition.MinSize(5).conform("house") # => pass
Definition.MinSize(5).conform([1,2,3,4,5]) # => pass
Definition.NonEmptyString.conform("house") # => pass
Definition.Regex(/^\d*$/).conform("123") # => pass
Definition.GreaterThan(5).conform(5.1) # => pass
Definition.GreaterThanEqual(5).conform(5) # => pass
Definition.LessThan(5).conform(4) # => pass
Definition.LessThanEqual(5).conform(5) # => pass
Definition.Empty.conform("") # => pass
Definition.Empty.conform([]) # => pass
Definition.Empty.conform({}) # => pass
Definition.NonEmpty.conform("Joe") # => pass
Definition.NonEmpty.conform([1]) # => pass
Definition.NonEmpty.conform({ a: 1 }) # => pass
Definition.Nil.conform(nil) # => pass
Definition.Boolean.conform(true) # => pass
Definition.Equal(5).conform(5) # => pass
Definition.Equal("foo").conform("foo") # => pass
The Nilable Definition allows a value to be nil or to conform with the definition you pass it as argument:
Definition.Nilable(Definition.Type(String)).conform(nil) # => pass
Definition.Nilable(Definition.Type(String)).conform("foo") # => pass
The Enum Definition checks if the input equals one of the values you pass it as argument. You can pass in as many arguments as you like:
Definition.Enum("foo", 1, 2.0).conform("foo") # => pass
Definition.Enum("foo", 1, 2.0).conform(1) # => pass
Definition.Enum("foo", 1, 2.0).conform("bar) # => fail
Check out the integration specs for more usage examples.
Every error object has a method translated_error
that will give you a translated
version of the error message. You can load the default English translations shipped
with the gem by adding them to your I18n load path.
schema = Definition.Keys do
required :title, Definition.Type(String)
required :body, Definition.Type(String)
required(:author, Definition.Keys do
required :name, Definition.Type(String)
required :email, Definition.Type(String)
end)
end
schema.conform(input_hash).errors.first.translated_error # => Value is of wrong type, needs to be a String"
Provides simple immutable objects that can validate and hold your data so that it can be safely passed around in your application.
class User < Definition::Model
required :username, Definition.Type(String)
required :password, Definition.Type(String)
optional :age, Definition.Type(Integer)
end
user = User.new(username: "johndoe", password: "zg(2ds8x2/")
user.username # => "johndoe"
user.age # => nil
user.to_h # => { username: "johndoe", password: "zg(2ds8x2/" }
user.new(age: 21) # => new model instance with username and password from before plus the age set to 21
user.username = "Alice" # => raises NoMethodError (Models are immutable)
User.new(username: "johndoe") # => raises a Definition::InvalidModelError: hash is missing :password
You can access the conform result of InvalidModel errors via their conform_result
method.
Models can be nested by either using the model object itself as type definition,
or by using the CoercibleModel
Definition. The latter is less strict and will
convert input hashes that conform with the model schema to an instance of the model.
class Address < Definition::Model
required :street, Definition.Type(String)
required :postal_code, Definition.Type(String)
end
class User < Definition::Model
required :username, Definition.Type(String)
required :address, Definition.CoercibleModel(Address)
end
# Address is converted into an Address model automatically:
user = User.new(username: "John", address: { street: "123 Fakestreet", postal_code: "2dfx4" })
user.address.street # => "123 Fakestreet"
class UserNotCoercibleAddress < Definition::Model
required :username, Definition.Type(String)
required :address, Address
end
# Address is not converted automatically, instead it needs to be of type Address already:
UserNotCoercibleAddress.new(username: "John", address: { street: "123 Fakestreet", postal_code: "2dfx4" }) # => raises a Definition::InvalidModelError
UserNotCoercibleAddress.new(username: "John", address: Address.new(street: "123 Fakestreet", postal_code: "2dfx4")).address.street # => "123 Fakestreet"
Definition provides a mixin that allows you to validate keyword arguments of class initialization methods. This is meant to be used with classes that provide business logic whereas the models are meant to be used to pass data around.
The major differences to a Definition::Model are:
- The values are not frozen and can be changed by the classes internal business logic
- None of the getters for the attributes are public
class User
include Definition::Initializer
required :id, Definition.Type(Integer)
required :name, Definition.Type(String)
optional :phone, Definition.Type(String), default: nil
def hello
puts "Hello, I'm #{name}"
end
end
user = User.new(id: 1, name: "Joe")
user.hello # => "Hello, I'm Joe"
user.name # => raises NoMethodError
User.new(id: "1", name: "Joe") # => raises a Definition::Initializer::InvalidArgumentError
After checking out the repo, run bin/setup
to install dependencies. Then, run rake spec
to run the tests. You can also run bin/console
for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install
. To release a new version, update the version number in version.rb
, and then run bundle exec rake release
, which will create a git tag for the version, push git commits and tags, and push the .gem
file to rubygems.org.
Bug reports and pull requests are welcome on GitHub at https://github.com/Goltergaul/definition.