Classy Hash is a lightweight RubyGem for validating Ruby hashes against a simple schema Hash that indicates what data types are expected. Classy Hash will make sure your data matches, providing helpful error messages if it doesn't.
Classy Hash is fantastic for helping developers become familiar with an API, by letting them know exactly what they did wrong. It also guards against mistakes by verifying that incoming data meets expectations, and can serve as a convenient data structure documentation format.
Classy Hash was created as a lightweight alternative to the other good validation gems available. By taking advantage of built-in Ruby language features, Classy Hash can validate common Hashes much faster than some of the other gems we tested, with a dead simple schema syntax.
Classy Hash doesn't modify your Hashes or patch any core classes, so it's safe to use just about anywhere.
Classy Hash is thoroughly tested (see the Testing section below).
Finally, Classy Hash is blazingly fast:
Serializer | Validator | Ops/sec
----------------------+----------------------+-----------
msgpack | no_op | 123525
msgpack | classy_hash | 67798
msgpack | classy_hash_strict | 59952
msgpack | hash_validator | 27578
msgpack | schema_hash | 22217
msgpack | json_schema | 1255
msgpack | json_schema_full | 1251
msgpack | json_schema_strict | 1086
A Classy Hash schema can be as simple or as complex as you like. At the most basic level, you list each key your Hash is required to contain, with the expected Ruby class of the value.
For more examples, see benchmark.rb
and lib/spec/classy_hash_spec.rb
.
Let's look at a simple schema for a Hash with three members:
schema = {
key1: String,
key2: Integer,
key3: TrueClass
}
This specifies a Hash with a String
, an Integer
, and a boolean value (both
TrueClass
and FalseClass
will accept true
and false
). Here's how we
validate a Hash against our schema:
hash = {
key1: 'A Hash with class',
key2: 0,
key3: false
}
ClassyHash.validate(hash, schema) # Okay
Here's what happens if we try to validate an invalid Hash:
hash = {
key1: 'A less classy Hash',
key2: 1.25,
key3: 'Also wrong, but not checked'
}
ClassyHash.validate(hash, schema) # Throws ":key2 is not a/an Integer"
The validate
and validate_strict
methods will raise an exception if
validation fails. Validation proceeds until the first invalid value is found,
then an error is thrown for that value. Later values are not checked.
It's possible to specify more than one option for a key, allowing multiple
types and/or nil
to be used as the value for a key:
schema = {
key1: [ NilClass, String, FalseClass ]
}
ClassyHash.validate({ key1: nil }, schema) # Okay
ClassyHash.validate({ key1: 'Hi' }, schema) # Okay
ClassyHash.validate({ key1: true }, schema) # Okay
ClassyHash.validate({ key1: 1337 }, schema) # Throws ":key1 is not one of NilClass, String, FalseClass"
Classy Hash will raise an error if a key from the schema is missing from the hash being validated:
schema = {
key1: TrueClass
}
ClassyHash.validate({}, schema) # Throws ":key1 is not present"
If we want to allow a key to be omitted, we can mark it as optional by adding
the :optional
symbol as the first element of a multiple choice array:
schema = {
key1: [:optional, TrueClass]
}
ClassyHash.validate({}, schema) # Doesn't throw
Regexp
constraints, added in 0.1.4, will require values to be String
s that
match a regular expression:
schema = {
key1: /Re.*quired/i
}
ClassyHash.validate({ key1: /required/ }, schema) # Throws ":key1 is not a String matching /re.*quired/i"
ClassyHash.validate({ key1: 'invalid' }, schema) # Throws ":key1 is not a String matching /re.*quired/i"
ClassyHash.validate({ key1: 'The regional manager inquired about ClassyHash' }, schema) # Okay
As with Ruby's =~
operator, Regexp
s can match anywhere in the String
. To
require the entire String
to match, use the standard \A
and \z
anchors:
schema = {
key1: /\AStart.*end\z/
}
ClassyHash.validate({ key1: 'One must Start to end' }, schema) # Throws ":key1 is not a String matching /\\AStart.*end\\z/"
ClassyHash.validate({ key1: 'Start now, continue to the end' }, schema) # Okay
If you want to check more than just the type of a value, you can specify a
Range
or a Proc
as a constraint. If your Range
endpoints are Integer
s,
Numeric
s, or String
s, then Classy Hash will also restrict the type of the
value to Integer
, Numeric
, or String
.
# An Integer range
schema = {
key1: 1..10
}
ClassyHash.validate({ key1: 5 }, schema) # Okay
ClassyHash.validate({ key1: -5 }, schema) # Throws ":key1 is not in range 1..10"
ClassyHash.validate({ key1: 2.5 }, schema) # Throws ":key1 is not an Integer"
# A more interesting range -- this use is not recommended :-)
schema = {
key1: [1]..[5]
}
ClassyHash.validate({ key1: [2, 3, 4] }, schema) # Okay
ClassyHash.validate({ key1: [5, 0] }, schema) # Throws ":key1 is not in range [1]..[5]"
When using a Proc
, you should accept exactly one parameter and return true
if validation succeeds. Any other value will be treated as a validation
failure. If the Proc
returns a String
, that string will be used in the
error message.
# A lambda without an error message
schema = {
key1: lambda {|v| v.is_a?(Integer) && v.odd?}
}
ClassyHash.validate({ key1: 1 }, schema) # Okay
ClassyHash.validate({ key1: 2 }, schema) # Throws ":key1 is not accepted by Proc"
# A lambda with an error message
schema = {
key1: lambda {|v| (v.is_a?(Integer) && v.odd?) || 'an odd integer'}
}
ClassyHash.validate({ key1: 1 }, schema) # Okay
ClassyHash.validate({ key1: 2 }, schema) # Throws ":key1 is not an odd integer"
Classy Hash accepts nested schemas. You can also use a schema as one of the options in a multiple choice key.
schema = {
key1: {
msg: String
},
key2: {
n1: [Integer, { y: Numeric }]
}
}
hash1 = {
key1: { msg: 'Valid' },
key2: { n1: { y: 1.0 } }
}
hash2 = {
key1: { msg: 'Also valid' },
key2: { n1: -1 }
}
hash3 = {
key1: { msg: false },
key2: { n1: 1 }
}
hash4 = {
key1: { msg: 'Not valid' },
key2: { n1: { y: false } }
}
ClassyHash.validate(hash1, schema) # Okay
ClassyHash.validate(hash2, schema) # Okay
ClassyHash.validate(hash3, schema) # Throws ":key1[:msg] is not a/an String"
ClassyHash.validate(hash4, schema) # Throws ":key2[:n1][:y] is not a/an Numeric"
ClassyHash.validate({ key1: false }, schema) # Throws ":key1 is not a Hash"
You can use Classy Hash to validate the members of an array. Array constraints are specified by double-array-wrapping a multiple choice list. Array constraints can also themselves be part of a multiple choice list or array constraint. Empty arrays are always accepted by array constraints.
# Simple array of integers
schema = {
key1: [[Integer]]
}
ClassyHash.validate({ key1: [] }, schema) # Okay
ClassyHash.validate({ key1: [1, 2, 3, 4, 5] }, schema) # Okay
ClassyHash.validate({ key1: [1, 2, 3, 0.5] }, schema) # Throws ":key1[3] is not one of Integer"
ClassyHash.validate({ key1: false }, schema) # Throws ":key1 is not an Array"
# An integer, or an array of arrays of strings
schema = {
key1: [Integer, [[ [[ String ]] ]]]
}
ClassyHash.validate({ key1: 1 }, schema) # Okay
ClassyHash.validate({ key1: [ [], ['a'], ['b', 'c'] ] }, schema) # Okay
ClassyHash.validate({ key1: ['bad'] }, schema) # Throws ":key1[0] is not one of [[String]]"
ClassyHash.validate({ key1: [ [], ['a'], ['b', false] ] }, schema) # Throws ":key1[2][1] is not one of String"
If you want to check the length of an array, you can use a Proc
(also see the
Generators section below):
# An array of two integers
schema = {
key1: lambda {|v|
if v.is_a?(Array) && v.length == 2
begin
ClassyHash.validate({k: v}, {k: [[Integer]]})
true
rescue => e
"valid: #{e}"
end
else
"an array of length 2"
end
}
}
ClassyHash.validate({ key1: [1, 2] }, schema) # Okay
ClassyHash.validate({ key1: [1, false] }, schema) # Throws ":key1 is not valid: :k[1] is not one of Integer"
ClassyHash.validate({ key1: [1] }, schema) # Throws ":key1 is not an array of length 2"
Version 0.1.1 of Classy Hash introduces some helper methods in
ClassyHash::Generate
(or the CH::G
alias introduced in 0.1.2) that will
generate a constraint for common tasks that are difficult to represent in the
base Classy Hash syntax.
The simplest generator checks for a set of exact values.
# Enumerator -- value must be one of the elements provided
schema = {
key1: CH::G.enum(1, 2, 3, 4)
}
ClassyHash.validate({ key1: 1 }, schema) # Okay
ClassyHash.validate({ key1: -1 }, schema) # Throws ":key1 is not an element of [1, 2, 3, 4]"
The arbitrary length generator checks the length of any type that responds to
:length
.
# Simple length generator -- length of value must be equal to a value, or
# within a range
schema = {
key1: CH::G.length(5..6)
}
ClassyHash.validate({ key1: '123456' }, schema) # Okay
ClassyHash.validate({ key1: {a: 1, b: 2, c: 3, d: 4, e: 5} }, schema) # Okay
ClassyHash.validate({ key1: [1, 2] }, schema) # Throws ":key1 is not of length 5..6"
ClassyHash.validate({ key1: 5 }, schema) # Throws ":key1 is not a type that responds to :length"
Since checking the length of a String
or an Array
is very common, there are
generators that will verify a value is the correct type and the correct
length.
# String length generator
schema = {
key1: CH::G.string_length(0..15)
}
ClassyHash.validate({ key1: 'x' * 15 }, schema) # Okay
ClassyHash.validate({ key1: 'x' * 16 }, schema) # Throws ":key1 is not a String of length 0..15"
ClassyHash.validate({ key1: false }, schema) # Throws ":key1 is not a String of length 0..15"
The Array
length constraint generator also checks the values of the array.
# Array length generator
schema = {
key1: CH::G.array_length(4, Integer, String)
}
ClassyHash.validate({ key1: [1, 'two', 3, 4] }, schema) # Okay
ClassyHash.validate({ key1: [1, 2, false, 4] }, schema) # Throws ":key1 is not valid: :array[2] is not one of Integer, String"
ClassyHash.validate({ key1: false }, schema) # Throws ":key1 is not an Array of length 4"
Here's a more practical application of Classy Hash. Suppose you have an API
that accepts POSTs containing JSON user data, that you convert to a Ruby
Hash with something like JSON.parse(data, symbolize_names: true)
. The user
should have some basic fields, an array of addresses, and no extra fields.
Here's how you might use Classy Hash to validate your user objects and generate helpful error messages:
# Note: this is not guaranteed to be a useful address checking schema.
address_schema = {
street1: /[0-9]+/,
street2: [NilClass, String],
city: String,
state: [NilClass, String],
country: String,
postcode: [NilClass, Integer, String]
}
user_schema = {
id: Integer,
name: String,
email: lambda {|v| (v.is_a?(String) && v.include?('@')) || 'an e-mail address'},
addresses: [[ address_schema ]]
}
data = <<JSON
{
"id": 1,
"name": "",
"email": "@",
"addresses": [
{
"street1": "123 Fake Street",
"street2": null,
"city": "",
"state": "",
"country": "",
"postcode": ""
},
{
"street1": "Building 53",
"street2": "",
"city": 5
}
]
}
JSON
# ClassyHash#validate_strict raises an error if the Hash contains any keys not
# specified by the schema.
ClassyHash.validate_strict({ :extra_key => 0 }, user_schema) # Throws "Hash contains members not specified in schema"
ClassyHash.validate_strict(JSON.parse(data, symbolize_names: true), user_schema) # Throws ":addresses[1][:city] is not a/an String
Classy Hash includes extremely thorough RSpec tests:
# Execute within a clone of the classy_hash Git repository:
bundle install
rspec
Classy Hash was written by Mike Bourgeous for API validation and documentation in internal DeseretBook.com systems.
If you decide Classy Hash isn't for you, here are some of the other options we considered before deciding to roll our own:
Classy Hash is released under the MIT license (see the LICENSE
file for the
license text and copyright notice).