stannum 0.3.0 → 0.4.0

data/README.md

@@ -2,24 +2,23 @@
 
 A library for defining and validating data structures.
 
-Stannum defines the following objects:
-
-- [Constraints](#constraints): A validator object that responds to `#match`, `#matches?` and `#errors_for` for a given object.
-- [Contracts](#contracts): A collection of constraints about an object or its properties. Obeys the `Constraint` interface.
-- [Errors](#errors): Data object for storing validation errors. Supports arbitrary nesting of errors.
-- [Entities](#entities): Defines a mutable data object with a specified set of typed attributes.
-
-## About
+<blockquote>
+  Read The
+  <a href="https://www.sleepingkingstudios.com/stannum" target="_blank">
+    Documentation
+  </a>
+</blockquote>
 
 Stannum provides a framework-independent toolkit for defining structured data entities and validations. It provides a middle ground between unstructured data (raw `Hash`es, `Structs`, or libraries like `Hashie`) and full frameworks like `ActiveModel`.
 
-First and foremost, Stannum provides you with the tools to validate your data. Using a `Stannum::Constraint`, you can apply your validation logic to literally any object, whether pure Ruby or from any framework or toolkit. Stannum provides a range of pre-defined constraints, including constraints for validating object types, defined methods, and more. You can also define custom constraints for any check that can output either `true` or `false`.
+It defines the following objects:
 
-Finally, you can combine your constraints into a `Stannum::Contract` to combine multiple validations of your object and its properties. Stannum provides pre-defined contracts for asserting on objects, `Array`s, `Hash`es, and even method parameters.
+- [Constraints](http://sleepingkingstudios.github.io/stannum/constraints): A validator object that responds to `#match`, `#matches?` and `#errors_for` for a given object.
+- [Contracts](http://sleepingkingstudios.github.io/stannum/contracts): A collection of constraints about an object or its properties. Obeys the `Constraint` interface.
+- [Errors](http://sleepingkingstudios.github.io/stannum/errors): Data object for storing validation errors. Supports arbitrary nesting of errors.
+- [Entities](http://sleepingkingstudios.github.io/stannum/entities): Defines a mutable data object with a specified set of typed attributes.
 
-Stannum also defines the `Stannum::Entity` module for defining structured data entities that are not tied to any framework or datastore. Stannum entities have more functionality and a friendlier interface than a core library `Struct`, provide more structure than a `Hash` or hash-like object (such as an `OpenStruct` or `Hashie::Mash`), and are completely independent from the source of the data. Need to load seed data from a YAML configuration file, perform operations in a SQL database, cross-reference with a MongoDB data store, and use an in-memory data array for lightning-fast tests? A `Stannum::Entity` won't fight you every step of the way.
-
-### Why Stannum?
+## Why Stannum?
 
 Stannum is not tied to any framework. You can create constraints and contracts to validate Ruby objects and Entities, data structures such as Arrays, Hashes, and Sets, and even framework objects such as `ActiveRecord::Model`s and `Mongoid::Document`s.
 
@@ -33,15 +32,19 @@ Still, most projects and applications use one framework to handle their data. Wh
 
 ### Compatibility
 
-Stannum is tested against Ruby (MRI) 2.7 through 3.2.
+Stannum is tested against Ruby (MRI) 3.1 through 3.4.
 
 ### Documentation
 
-Documentation is generated using [YARD](https://yardoc.org/), and can be generated locally using the `yard` gem.
+Code documentation is generated using [YARD](https://yardoc.org/), and can be generated locally using the `yard` gem.
+
+The full documentation is available via [GitHub Pages](http://sleepingkingstudios.github.io/stannum), and includes the code documentation as well as a deeper explanation of Stannum's features and design philosophy. It also includes documentation for prior versions of the gem.
+
+To generate documentation locally, see the [SleepingKingStudios::Docs](https://github.com/sleepingkingstudios/sleeping_king_studios-docs) gem.
 
 ### License
 
-Copyright (c) 2019-2021 Rob Smith
+Copyright (c) 2019-2025 Rob Smith
 
 Stannum is released under the [MIT License](https://opensource.org/licenses/MIT).
 
@@ -57,1335 +60,198 @@ To contribute code, please fork the repository, make the desired updates, and th
 
 Please note that the `Stannum` project is released with a [Contributor Code of Conduct](https://github.com/sleepingkingstudios/stannum/blob/master/CODE_OF_CONDUCT.md). By contributing to this project, you agree to abide by its terms.
 
-<!-- ## Getting Started  -->
+## Getting Started
+Let's take a look at using Stannum to model a problem domain. Consider the following case study: we are implementing an ecommerce application. We want to ensure that our Order object is valid through each stage of our ordering process. For the sake of simplicity, let's say our process has three steps:
 
-## Reference
+- A customer creates an order.
+- The customer is billed for the order.
+- The order is shipped to the customer.
 
-<a id="constraints"></a>
+### Defining Entities
 
-### Constraints
+Our first step is to define some entities to represent our data.
 
 ```ruby
-require 'stannum/constraint'
-```
+class Customer
+  include Stannum::Entity
 
-Constraints provide the foundation for data validation in Stannum. Fundamentally, each `Stannum::Constraint`encapsulates a predicate - a statement that can be either true or false - that can be applied to other objects. If the statement is true about the object, that object "matches" the constraint. If the statement is false, the object does not match the constraint.
+  define_primary_key :id, Integer
 
-The easiest way to define a constraint is by passing a block to `Stannum::Constraint.new`:
+  define_attribute :email,   String
+  define_attribute :address, String
 
-```ruby
-constraint = Stannum::Constraint.new do |object|
-  object.is_a?(String) && !object.empty?
+  define_association :many, :orders
 end
 ```
 
-Here, we've created a very simple constraint, which will match any non-empty string and will not match empty strings or other objects. When you define a constraint using `Stannum::Constraint.new`, the constraint will pass for an object if and only if the block returns `true` for that object. We can also pass in additional metadata about the constraint such as a type or message to display - we will revisit this in [Errors, Types and Messages](#constraints-errors-types-messages), below.
-
-#### Matching Objects
-
-Defining a constraint is only half the battle - next, we need to use the constraint. Each `Stannum::Constraint` defines a standard set of methods to match objects.
-
-First, the `#matches?` method will return true if the object matches the constraint, and will return false if the object does not match.
-
-```ruby
-constraint.matches?(nil)
-#=> false
-
-constraint.matches?('')
-#=> false
-
-constraint.matches?('Greetings, programs!')
-#=> true
-```
-
-Knowing that an object does not match isn't always enough information - we need to know why. Stannum defines the `Stannum::Errors` object for this purpose (see [Errors](#errors), below). We can use the `#match` method to both check whether an object matches the constraint and return any errors with one method call.
-
-```ruby
-status, errors = constraint.matches?(nil)
-status
-#=> false
-errors
-#=> an instance of Stannum::Errors
-errors.empty?
-#=> false
-
-status, errors = constraint.matches?('Greetings, programs!')
-status
-#=> true
-errors
-#=> an instance of Stannum::Errors
-errors.empty?
-#=> true
-```
-
-Finally, if we already know that an object does not match the constraint, we can check its errors using the `#errors_for` method.
-
-```ruby
-errors = constraint.errors_for(nil)
-#=> an instance of Stannum::Errors
-errors.empty?
-#=> false
-```
-
-*Important Note:* Stannum **does not** guarantee that `#errors_for` will return an empty `Errors` object for an object that matches the constraint. Always check whether the object matches the constraint before checking the errors.
-
-#### Negated Matching
-
-A constraint can also be used to check if an object does not match the constraint. Each `Stannum::Constraint` defines helpers for the negated use case.
-
-The `#does_not_match?` method is the inverse of `#matches?`. It will return false if the object matches the constraint, and will return true if the object does not match.
-
-```ruby
-constraint.does_not_match?(nil)
-#=> true
-
-constraint.does_not_match?('')
-#=> true
-
-constraint.does_not_match?('Greetings, programs!')
-#=> false
-```
-
-Negated matches can also generate errors objects. Whereas the errors from a standard match will list how the object fails to match the constraint, the errors from a negated match will list how the object does match the constraint. The `#negated_match` method will both check that the object does not match the constraint and return the relevant errors, while the `#negated_errors_for` method will return the negated errors for a matching object.
-
-<a id="constraints-errors-types-messages"></a>
-
-#### Errors, Types and Messages
-
-We can customize the error returned by the constraint for a non-matching object by setting the constraint type and/or message.
-
-```ruby
-constraint = Stannum::Constraint.new(
-  message: 'must be even',
-  type:    'example.constraints.even'
-) { |i| i.even? }
-```
-
-The constraint `#type` identifies the kind of constraint. For example, a `case` or conditional statement that checks for an error of a particular variety would look at the error's type. The constraint `#message`, on the other hand, is a human-readable description of the error. A flash message or rendered might use the error's message to display the status to the user. An API response might provide both the type and the message.
-
-The constraint type and message are used to generate the corresponding error:
-
-```ruby
-errors = constraint.errors_for(nil)
-errors.count
-#=> 1
-errors.first.message
-#=> 'must be even'
-errors.first.type
-#=> 'example.constraints.even'
-
-```
-
-The error message can also be generated automatically from the type (see [Generating Messages](#errors-generating-messages), below).
-
-#### Constraint Subclasses
-
-Defining a subclass of `Stannum::Constraint` allows for greater control over the predicate logic and the generated errors.
+Our `Customer` class represents a user who can create an order in our system. We define an `#id` primary key, attributes `#email` and `#address`, and a plural association to our `Order` entity.
 
 ```ruby
-class EvenIntegerConstraint < Stannum::Constraint
-  NEGATED_TYPE = 'examples.constraints.odd'
-  TYPE         = 'examples.constraints.even'
+class Payment
+  include Stannum::Entity
 
-  def errors_for(actual, errors: nil)
-    return super if actual.is_a?(Integer)
+  define_primary_key :id, Integer
 
-    (errors || Stannum::Errors.new)
-      .add('examples.constraints.type', type: Integer)
-  end
+  define_attribute :amount, BigDecimal
 
-  def matches?(actual)
-    actual.is_a?(Integer) && actual.even?
-  end
+  define_association :one, :order, foreign_key: true
 end
 ```
 
-Let's take it from the top. We start by defining `::NEGATED_TYPE` and `::TYPE` constraints. These serve two purposes: first, the constraint will use these values as the default `#type` and `#negated_type` properties, without having to pass in values to the constructor. Second, we are declaring the type of error this constraints will return to the rest of the code. This allows us to reference these values elsewhere, such as a `case` or conditional statement checking for the presense of this error.
-
-Second, we define our `#matches?` method. This method takes one parameter (the object being matched) and returns either `true` or `false`. Our other matching methods - `#does_not_match?`, `#match`, and `#negated_match` - will delegate to this implementation unless we specifically override them.
-
-Finally, we are defining the errors to be returned from our constraint using the `#errors_for` method. This method takes one required argument `actual`, which is the object being matched. If the object is an integer, then we fall back to the default behavior: `super` will add an error with a `#type` equal to the constraint's `#type` (or the `:type` passed into the constructor, if any). If the object is not an integer, then we instead display a custom error. In addition to the error `#type`, we are defining some error `#data`. In addition, `#errors_for` can take an optional keyword `:errors`, which is either an instance of `Stannum::Errors` or `nil`. This allows the user to pass an existing errors object to `#errors_for`, which will add its own errors to the given errors object instead of creating a new one.
-
-```ruby
-errors = constraint.errors_for(nil)
-errors.count
-#=> 1
-errors.first.type
-#=> 'examples.constraints.type'
-errors.first.data
-#=> { type: Integer }
-
-errors = constraint.errors_for('')
-errors.count
-#=> 1
-errors.first.type
-#=> 'examples.constraints.even'
-errors.first.data
-#=> {}
-```
-
-We can likewise define the behavior of the constraint when negated. We've already set the `::NEGATED_TYPE` constant, but we can go further and override the `#does_not_match?` and/or `#negated_errors_for` methods as well for full control over the behavior when performing a negated match.
-
-<a id="contracts"></a>
-
-### Contracts
+Our `Payment` class represents a payment submitted by our customer for an order. We again define an `#id` primary key, as well as an `#amount` attribute and a singular association to an `Order`. Note that we are specifying a foreign key for the `#order` association, which automatically creates an `#order_id` attribute.
 
 ```ruby
-require 'stannum/contract'
-```
-
-A contract is a collection of constraints that validate an object and its properties. Each `Stannum::Contract` holds a set of `Stannum::Constraints`, each of which must match an object or the referenced property for that object to match the contract as a whole. Contracts also obey the Constraint interface, and can be used inside other contracts to compose complex or nested validations.
+class Order
+  include Stannum::Entity
 
-Like constraints, contracts can be created by passing a block to `Stannum::Contract.new`:
+  define_primary_key :id, Integer
 
-```ruby
-contract = Stannum::Contract.new do
-  constraint(type: 'examples.constraints.numeric') do |actual|
-    actual.is_a?(Numeric)
-  end
+  define_attribute :amount, BigDecimal
 
-  constraint(type: 'examples.constraints.integer') do |actual|
-    actual.is_a?(Integer)
-  end
+  define_association :one, :customer, foreign_key: true
+  define_association :one, :payment
 
-  constraint(type: 'examples.constraints.in_range') do |actual|
-    actual >= 0 && actual <= 10 rescue false
-  end
+  constraint :customer, Stannum::Constraints::Presence.new
 end
-
-contract.matches?(nil)
-#=> false
-contract.errors_for(nil).map(&:type)
-#=> ['examples.constraints.numeric', 'examples.constraints.integer', 'examples.constraints.in_range']
-
-contract.matches?(99.0)
-#=> false
-contract.errors_for(99.0).map(&:type)
-#=> ['examples.constraints.integer', 'examples.constraints.in_range']
-
-contract.matches?(99)
-#=> false
-contract.errors_for(99).map(&:type)
-#=> ['examples.constraints.in_range']
-
-contract.matches?(5)
-#=> true
 ```
 
-As you can see, the contract matches the object against each of its constraints. If any of the constraints fail to match the object, then the contract also does not match. Finally, the errors from each failing constraint are aggregated together.
-
-You can also add constraints to an existing contract using the `#add_constraint` method.
-
-```ruby
-constraint = Stannum::Constraint.new(type: 'examples.constraints.even') do |actual|
-  actual.respond_to?(:even) && actual.even?
-end
+Our core class for this workflow is the `Order` entity. We define our `#id` and `#amount`, and associations to the `Customer` and `Payment` entities - again, by passing `foreign_key: true` to our `#customer` association, we also define a `#customer_id` attribute. Finally, we are defining an additional constraint. When validating the `Order` using the default contract, we will require the `#customer` association to be populated - an `Order` must always have an associated `Customer`. However, we are *not* requiring the presence of a `Payment`, since that requirement is not applicable to the entire `Order` lifecycle.
 
-contract.add_constraint(constraint)
-
-contract.matches?(5)
-#=> false
-contract.errors_for(99).map(&:type)
-#=> ['examples.constraints.even']
+### Defining Validators
 
-contract.matches?(6)
-#=> true
-```
+Actually implementing the business logic for orders is outside the scope of Stannum - for a structured approach to defining your business logic, take a look at the [Cuprum](https://www.sleepingkingstudios.com/cuprum/) gem.
 
-The `#add_constraint` method returns the contract, so you can chain multiple `#add_constraint` calls together.
+However, that doesn't mean we're finished. One of the challenges in implementing a multi-step process like our ordering flow is validation. Specifically, this kind of workflow requires *contextual* validation - an `Order` object that is valid for one part of the flow may not be valid for others. Rather than defining conditional logic in our `Order` class, let's instead apply the concept of a Validator: an object that is responsible for validating an entity or data structure *in a particular context*.
 
-#### Negated Matching
+Let's start with our first step, order creation. Creating an order requires a valid `#id`, a valid `#amount` (can be zero at this point in the workflow), and an associated `#customer`. Fortunately, we already have a contract defined for these requirements: the existing `Order::Contract`, which validates the entity's attributes and any additional `constraint`s defined on the entity.
 
-Like a constraint, a contract can perform a negated match. Whereas an object matches the contract if **all** of the constraints match the object, the object will pass a negated match if **none** of the constraints match the object.
+Here's how we could use that in our business logic:
 
 ```ruby
-contract = Stannum::Contract.new do
-  constraint(type: 'examples.constraints.color') do |hsh|
-    hsh[:color] == 'red'
-  end
-
-  constraint(type: 'examples.constraints.shape') do |hsh|
-    hsh[:color] == 'circle'
-  end
-end
+customer = Customer.new(
+  id:      0,
+  email:   'user@example.com',
+  address: '123 Example St'
+)
+order = Order.new(id: 1)
 
-contract.matches?({ color: 'red', shape: 'circle' })
-#=> true
-contract.does_not_match?({ color: 'red', shape: 'circle' })
+Order::Contract.matches?(order)
 #=> false
-contract.errors_for({ color: 'red', shape: 'square' }).map(&:type)
-#=> ['examples.constraints.color', 'examples.constraints.shape']
+errors = Order::Contract.errors_for(order)
+#=> an instance of Stannum::Errors
+errors.summary
+#=> "amount: is not a BigDecimal, customer: is nil or empty"
 
-contract.matches?({ color: 'red', shape: 'square' })
-#=> false
-contract.does_not_match?({ color: 'red', shape: 'square' })
-#=> false
-contract.errors_for({ color: 'red', shape: 'square' }).map(&:type)
-#=> ['examples.constraints.color']
+order.amount   = BigDecimal('0.0')
+order.customer = customer
 
-contract.matches?({ color: 'blue', shape: 'square'})
-#=> false
-contract.does_not_match?({ color: 'blue', shape: 'square'})
+Order::Contract.matches?(order)
 #=> true
 ```
 
-Note that for an object that partially matches the contract, both `#matches?` and `#does_not_match?` methods will return false. If you want to check whether **any** of the constraints do not match the object, use the `#matches?` method and apply the `!` boolean negation operator (or switch from an `if` to an `unless`).
-
-#### Constraining Properties
-
-Constraints can also define constraints on the *properties* of the matched object. This is a powerful feature for defining validations on objects and nested data structures. To define a property constraint, use the `property` macro in a contract constructor block, or use the `#add_property_constraint` method on an existing contract.
-
-```ruby
-gadget_contract = Stannum::Contract.new do
-  property :name, Stannum::Constraints::Presence.new
-
-  property :name, Stannum::Constraints::Types::StringType.new
-
-  property(:size, type: 'examples.constraints.size') do |size|
-    %w[small medium large].include?(size)
-  end
-
-  property :manufacturer, Stannum::Contract.new do
-    constraint Stannum::Constraints::Presence.new
-
-    property :address, Stannum::Constraints::Presence.new
-  end
-end
-```
-
-There's a lot going on here, so let's break it down. First, we're defining constraints on the *properties* of the object, rather than on the object as a whole. In particular, note that we're setting multiple constraints on the `:name` property - an object will only match the contract if it's `#name` matches both of those constraints.
-
-We're also using some pre-defined constraints, rather than having to start from scratch. The `Presence` constraint validates that an object is not `nil` and not `#empty?`, while the `Types::StringType` constraint validates that the object is an instance of `String`. For a full list of pre-defined constraints, see [Built-In Constraints](#builtin-constraints) and [Contracts](#builtin-contracts), below. You can also define your own constraint classes and reference them in your contracts.
-
-Finally, note that the constraint for the `:manufacturer` property is itself a contract. We are asserting that the actual object has a non-`nil` `#manufacturer` property and that the manufacturer's `#address` is also non-`nil` (and not `#empty?`).
-
-```ruby
-gadget = Gadget.new(manufacturer: Manufacturer.new)
-gadget_contract.matches?(gadget)
-#=> false
-gadget_contract.errors_for(gadget).map { |err| [err.path, err.type] }
-#=> [
-#     [%i[name], 'stannum.constraints.absent'],
-#     [%i[name], 'stannum.constraints.is_not_type'],
-#     [%i[size], 'examples.constraints.size'],
-#     [%i[manufacturer address], 'stannum.constraints.absent']
-#   ]
-```
-
-We've established that each error has a `#type`, which identifies which type of constraint failed to match the object. Here, we can see that each error also has a `#path` property, which represents the relative path of the property from the original matched object. For example, errors on the `gadget.name` property will have a path of `%i[name]`, while the error on the `gadget.manufacturer.address` will have a path of `%i[manufacturer address]`. A constraint without a property, i.e. on the matched object itself, will have a path of `[]`, an empty string.
+If our contract `#matches?` the order, we proceed with the creation logic. Otherwise, we return an error message, possibly using the errors `#summary`.
 
-The errors for a property or nested contract can also be accessed using the `#[]` operator or the `#dig` method.
+Now we move on to validating that an order is ready for billing. Our validation logic gets more complicated here: in addition to requiring a valid order (the same validations as above), we need to make sure that the billable amount is greater than zero.
 
-```ruby
-gadget_contract.errors_for(gadget)[:manufacturer].map { |err| [err.path, err.type] }
-#=> [[%i[address], 'stannum.constraints.absent']]
-
-gadget_contract.errors_for(gadget).dig(:manufacturer, :address).map { |err| [err.path, err.type] }
-#=> [[[], 'stannum.constraints.absent']]
-```
-
-Be careful when defining property constraints on a contract that might be matched against `nil` or an unknown object type - Ruby will raise a `NoMethodError` when trying to access the property. To avoid this, you can add a sanity constraint (see below) to ensure that the contract only validates the expected type of object.
-
-#### Sanity Constraints
-
-In some cases, before running through the full set of constraints in a contract, we want to run a quick sanity check to make sure the contract is even applicable to the object. By adding `sanity: true` when defining the constraint, you can mark a constraint as a sanity check.
-
-```ruby
-gadget_contract.add_constraint(Stannum::Constraints::Type.new(Gadget), sanity: true)
-```
-
-When matching an object, all of a contract's sanity constraints will be evaluated first. The remaining constraints will be matched against the object *only* if all of the sanity constraints match the object. This can be especially important if some of the constraints return nonsensical results or even raise exceptions when given an invalid object.
-
-```ruby
-gadget_contract.matches?(nil)
-#=> false
-gadget_contract.errors_for(nil).map { |err| [err.path, err.type] }
-#=> [[[], 'stannum.constraints.is_not_type']]
-```
-
-Likewise, when performing a negated match, the sanity constraints will be evaluated first, and the remaining constraints will be evaluated only if all of the sanity constraints match.
-
-#### Combining Contracts
-
-Stannum provides two mechanisms for composing contracts together. Each contract is a constraint, and so can be added to another contract (with or without a property or scope). This allows you to create and reuse validation logic simply by adding a contract as a constraint:
-
-```ruby
-named_contract = Stannum::Contract.new do
-  property :name, Stannum::Constraints::Presence.new
-end
-
-widget_contract = Stannum::Contract.new do
-  constraint(Stannum::Constraints::Type.new(Widget))
-
-  constraint(named_contract)
-end
-
-widget = Widget.new
-widget_contract.matches?(Widget.new)
-#=> false
-widget_contract.matches?(Widget.new(name: 'Whirlygig'))
-#=> true
-```
-
-The second mechanism is contract *concatenation*. Under the hood, concatenation directly pulls in the constraints from a concatenated contract, rather than evaluating that contract on its own. This can be likened to inheriting methods from a superclass or an included Module.
+One common approach is to add conditional validation to the `Order` class itself. For example, defining a `#status` attribute asserting that the `#amount` is greater than zero if the status matches a value. However, as new cases and conditions are added, this approach quickly becomes difficult to read and reason about. Instead, we're going to define a validator object.
 
 ```ruby
-gadget_contract = Stannum::Contract.new do
-  constraint(Stannum::Constraints::Type.new(Gadget))
-
-  concat(named_contract)
-end
-```
-
-Using concatenation, you have finer control over the constraints that are added to the contract. Specifically, when defining a contract you can mark certain constraints as excluded from concatenation by adding the `concatenatable: false` keyword to `#add_constraint`. As an example, this can be useful if you want to inherit constraints about the properties of an object, but not potentially conflicting constraints about the object's type.
+module Orders
+  module Contracts
+    IS_BILLABLE = Stannum::Contract.new do
+      concat(Order::Contract)
 
-<a id="array-contracts"></a>
-
-#### Array Contracts
-
-By default, a `Stannum::Contract` accesses an object's properties as method calls, using the `.` dot notation. When validating `Array`s and `Hash`es, this approach is less useful. Therefore, Stannum provides special contracts for operating on data structures.
-
-A `Stannum::Contracts::ArrayContract` is used for validating sequential data, using the `#[]` method to access indexed values.
-
-```ruby
-class BaseballContract < Stannum::Contracts::ArrayContract
-  def initialize
-    super do
-      item { |actual| actual == 'Who' }
-      item { |actual| actual == 'What' }
-      item { |actual| actual == "I Don't Know" }
+      property :amount,
+        message: 'must be greater than zero',
+        type:    'orders.constraints.greater_than_zero' \
+      do |value|
+        value.is_a?(Numeric) && value > 0
+      end
+      property :payment, Stannum::Constraints::Types::NilType.new
     end
   end
 end
-
-contract = BaseballContract.new
-contract.matches?(nil)
-#=> false
-contract.errors_for(nil).map { |err| [err.path, err.type] }
-#=> [[[], 'stannum.constraints.is_not_type']]
-
-array = %w[Who What]
-contract.matches?(array)
-#=> false
-contract.errors_for(array).map { |err| [err.path, err.type] }
-#=> [[[2], 'stannum.constraints.invalid']]
-
-array = ['Who', 'What', "I Don't Know"]
-contract.matches?(array)
-#=> true
-
-array = ['Who', 'What', "I Don't Know", 'Tomorrow']
-contract.matches?(array)
-#=> false
-contract.errors_for(array).map { |err| [err.path, err.type] }
-#=> [[[3], 'stannum.constraints.tuples.extra_items']]
-```
-
-Here, we are defining an ArrayContract using the `#item` macro, which defines an item constraint for each successive item in the array. We can also define a property constraint using the `#property` macro, using an Integer as the property to validate. This would allow us to add multiple constraints for the value at a given index, although the recommended approach is to use a nested contract.
-
-When matching an object, the contract first validates that the object is an instance of `Array`. If not, it will immedidately fail matching and the remaining constraints will not be matched against the object. If the object is an an array, then the contract checks each of the defined constraints against the value of the array at that index.
-
-Finally, the constraint checks for the highest index expected by an item constraint. If the array contains additional items after this index, those items will fail with a type of `"extra_items"`. To allow additional items instead, pass `allow_extra_items: true` to the `ArrayContract` constructor.
-
-```ruby
-contract = BaseballContract.new(allow_extra_items: true)
-contract.matches?(['Who', 'What', "I Don't Know", 'Tomorrow'])
-#=> true
 ```
 
-An `ArrayContract` will first validate that the object is an instance of `Array`. For validating Array-like objects that access indexed data using the `#[]` method, you can instead use a `Stannum::Contracts::TupleContract`.
-
-<a id="hash-contracts"></a>
-
-#### Hash Contracts
-
-A `Stannum::Contracts::HashContract` is used for validating key-value data, using the `#[]` method to access values by key.
-
-```ruby
-class ResponseContract < Stannum::Contracts::HashContract
-  def initialize
-    super do
-      key :status, Stannum::Constraints::Types::IntegerType.new
-
-      key :json,
-        Stannum::Contracts::HashContract.new(allow_extra_keys: true) do
-          key :ok, Stannum::Constraints::Boolean.new
-        end
-
-      key :signature, Stannum::Constraints::Presence.new
-    end
-  end
-end
-
-contract = ResponseContract.new
-contract.matches?(nil)
-#=> false
-contract.errors_for(nil).map { |err| [err.path, err.type] }
-#=> [[[], 'stannum.constraints.is_not_type']]
+Our validator is an instance of `Stannum::Contract`, and our first step is to `concat` the existing `Order::Contract`. This means that all of the constraints in the `Order::Contract` will also be applied when matching an order with the `IS_BILLABLE` contract. This means we don't need to duplicate our existing constraints.
 
-response = { status: 500, json: {} }
-contract.matches?(response)
-#=> false
-contract.errors_for(response).map { |err| [err.path, err.type] }
-#=> [
-#     %i[json ok], 'stannum.constraints.is_not_boolean'],
-#     %i[signature], 'stannum.constraints.absent'
-#   ]
-
-response = { status: 200, json: { ok: true }, signature: '12345' }
-contract.matches?(response)
-#=> true
+Second, we are adding a custom `constraint` on the `#amount` attribute. Notice that the first check inside the block checks that the value is `Numeric`; otherwise, comparing a `nil` value would raise an exception, rather than failing the validation. We are also defining a custom `message` and `type` for the constraint. The `message` is intended to be a human-readable representation of the error, while the `type` is intended for machines.
 
-response = { status: 200, json: { ok: true }, signature: '12345', role: 'admin' }
-#=> false
-contract.errors_for(response).map { |err| [err.path, err.type] }
-#=> [[%i[role], 'stannum.constraints.hashes.extra_keys']]
-```
+Finally, we validate that the `#payment` association is nil, since we don't want to accidentally bill the same order twice. Here we can see why a validator object is so powerful - we obviously can't add this kind of constraint directly to `Order`, since orders later in the workflow will clearly not match. However, since our `IS_BILLABLE` contract applies only to this specific context, we can make the validation logic as specific as we want.
 
-We define a HashContract using the `#key` macro, which defines a key-value constraint for the specified value in the hash. When validating a Hash, the value at each key must match the given constraint. The contract will also fail if there are additional keys without a corresponding constraint. To allow additional keys instead, pass `allow_extra_keys: true` to the `HashContract` constructor.
+Our final step is to ship the order to the customer. Again, to determine if the order is ready to be shipped, we define a validator object:
 
 ```ruby
-contract = ResponseContract.new(allow_extra_keys: true)
-response = { status: 200, json: { ok: true }, signature: '12345', role: 'admin' }
-contract.matches?(response)
-#=> true
-```
-
-A `HashContract` will first validate that the object is an instance of `Hash`. For validating Hash-like objects that access key-value data using the `#[]` method, you can instead use a `Stannum::Contracts::MapContract`.
+module Orders
+  module Contracts
+    IS_SHIPPABLE = Stannum::Contract.new do
+      concat(Order::Contract)
 
-#### Contract Subclasses
+      property :payment, Stannum::Constraints::Presence.new
 
-For most use cases, defining a custom contract subclass will involve adding default constraints for the contact. Stannum provides two easy methods for doing so. First, you can leverage the default behavior by passing a block to `super` in the contract constructor. This will allow you to take advantage of the `constraint`, `property`, and other macros.
-
-```ruby
-class GizmoContract
-  def initialize(**_options)
-    super do
-      constraint Stannum::Constraints::Type.new(Gizmo), sanity: true
-
-      property :complexity, Stannum::Constraints::Presence.new
+      property :customer, Stannum::Contract.new {
+        property :address, Stannum::Constraints::Presence.new
+      }
     end
   end
 end
 ```
 
-As an alternative, `Stannum::Contract` defines a private `#define_constraints` method that is used to initialize any constraints.
-
-```ruby
-class WhirlygigContract
-  private
-
-  def define_constraints
-    super
-
-    constraint Stannum::Constraints::Type.new(Whirlygig), sanity: true
-
-    property :rotation_speed, Stannum::Constraints::Types::Float.new
-  end
-end
-```
-
-<a id="errors"></a>
-
-### Errors
-
-```ruby
-require 'stannum/errors'
-```
+Again, we define a custom `Stannum::Contract` and `concat` the existing `Order::Contract`, and we add a constraint that the `#payment` association needs to be populated - we don't want to ship an order that hasn't been paid for yet. Next, we define a nested contract to assert that the `#customer` association has a present `#address` attribute. You can define complex validation logic easily by composing together multiple constraints and contracts.
 
-When a constraint or contract fails to match an object, Stannum can return the reasons for that failure in the form of an errors object. Specifically, a `Stannum::Errors` object is returned by calling `#errors_for` or `#negated_errors-for` with a failing object, or as part of the result of calling `#match` or `#negated_match`.
+Here is how we would use the `IS_BILLABLE` and `IS_SHIPPABLE` contracts in our business logic:
 
 ```ruby
-contract.matches?(nil)
-#=> false
-contract.errors_for(nil)
-#=> an instance of Stannum::Errors
-status, errors = contract.match(nil)
-status
-#=> false
-errors
-#=> an instance of Stannum::Errors
-```
-
-A `Stannum::Errors` object is an `Enumerable` collection, while each error is a `Hash` with the following properties:
-
-- `#type`: A unique value that defines what kind of error was encountered. Each error's type should be a namespaced `String`, e.g. `"stannum.constraints.invalid"`.
-- `#data`: A `Hash` of additional data about the error. For example, a failed type validation will include the expected type for the value; a failed range validation might include the minimum and maximum allowable values.
-- `#path`: The path of the error relative to the top-level object that was validated. The path is always an `Array`, and each item in the array is either an `Integer` or a non-empty `Symbol`. Some examples:
-    - An error on the object itself will have an empty path, `[]`.
-    - An error on the item at index `3`of an array would have a path of `[3]`.
-    - An error on the `#name` property of an object would have a path of `[:name]`.
-    - An error on the address of the first manufacturer would have a path of `[:manufacturers, 3, :address]`.
-- `#message`: A human-readable description of the error. Error messages are not generated by default; either specify a message when defining the constraint, or call `#with_messages` to generate the error messages based on the error types and data. See [Generating Messages](errors-generating-messages), below.
-
-The simplest way to access the errors in a `Stannum::Errors` object is via the `#each` method, which will yield each error in the collection to the given block. Because each `Stannum::Errors` is enumerable, you can use the standard `Enumerable` methods such as `#map`, `#reduce`, `#select`, and so on. You can also use `#count` to return the number of errors, or `#empty?` to check if there are any errors in the collection.
+customer = Customer.new(
+  id:      0,
+  email:   'user@example.com',
+  address: '123 Example St'
+)
+order = Order.new(id: 1, customer:)
 
-```ruby
-errors.count
-#=> 3
-errors.empty?
+Orders::Contracts::IS_BILLABLE.matches?(order)
 #=> false
-errors.first
-#=> {
-#     data: {},
-#     message: nil,
-#     path: [:name],
-#     type: 'stannum.constraints.invalid'
-#   }
-errors.map(&:type)
-#=> [
-#     'stannum.constraints.invalid',
-#     'stannum.constraints.absent',
-#     'stannum.constraints.is_not_type'
-#   ]
-```
-
-Usually, an errors object is generated automatically by a constraint or contract with its errors already defined. If you want to add custom errors to an errors object, use the `#add` method, which takes the error `type` as one required argument. You can also specify the `message` keyword, which sets the message of the error. Finally, any additional keywords are added to the error `data`.
+errors = Orders::Contracts::IS_BILLABLE.errors_for(order)
+errors.summary
+#=> "amount: is not a BigDecimal, amount: must be greater than zero"
 
-```ruby
-errors = Stannum::Errors.new
-errors.count
-#=> 0
-errors.empty?
+order.amount = BigDecimal('100.0')
+Orders::Contracts::IS_BILLABLE.matches?(order)
 #=> true
 
-errors.add('example.constraints.out_of_range', message: 'out of range', min: 0, max: 10)
-#=> the errors object
-errors.count
-#=> 1
-errors.empty?
+Orders::Contracts::IS_SHIPPABLE.matches?(order)
 #=> false
-errors.first
-#=> {
-#     data: { min: 0, max: 10 },
-#     message: 'out of range',
-#     path: [],
-#     type: 'example.constraints.out_of_range'
-#   }
-```
-
-Conveniently, `#add` returns the errors object itself, so you can chain together multiple `#add` calls.
-
-#### Nested Errors
-
-To represent the properties of an object or the values in a data structure, `Stannum::Errors` can be nested together. Nested error objects are accessed using the `#[]` operator.
-
-```ruby
-errors = Stannum::Errors.new
-errors[:manufacturers][0][:address].add('stannum.constraints.invalid')
-errors[:manufacturers][0][:address]
-#=> an instance of Stannum::Errors
-errors[:manufacturers][0][:address].count
-#=> 1
-errors[:manufacturers][0][:address].first
-#=> {
-#     data: {},
-#     message: nil,
-#     path: [],
-#     type: 'stannum.constraints.invalid'
-#   }
-
-errors.count
-#=> 1
-errors.first
-#=> {
-#     data: {},
-#     message: nil,
-#     path: [:manufacturers, 0, :address],
-#     type: 'stannum.constraints.invalid'
-#   }
-```
-
-You can also use the `#dig` method to access nested errors:
-
-```ruby
-errors.dig(:manufacturers, 0, :address).first
-#=> {
-#     data: {},
-#     message: nil,
-#     path: [],
-#     type: 'stannum.constraints.invalid'
-#   }
-```
-
-<a id="errors-generating-messages"></a>
-
-#### Generating Messages
-
-By default, errors objects do not generate messages. `Stannum::Errors` defines the `#with_messages` method to generate messages for a given errors object. If the `:force` keyword is set to true, then `#with_messages` will overwrite any messages that are already set on an error, whether from a constraint or generated by a different strategy.
+errors = Orders::Contracts::IS_SHIPPABLE.errors_for(order)
+errors.summary
+#=> "payment: is nil or empty"
 
-```ruby
-errors.first.message
-#=> nil
-
-errors = errors.with_messages.first.message
-errors.first.message
-#=> 'is invalid'
+order.payment = Payment.new(id: 2, amount: order.amount)
+Orders::Contracts::IS_SHIPPABLE.matches?(order)
+#=> true
 ```
 
-Stannum uses the strategy pattern to determine how error messages are generated. You can pass the `strategy:` keyword to `#with_messages` to force Stannum to use the specified strategy, or set the `Stannum::Messages.strategy` property to define the default for your application. The default strategy for Stannum uses an I18n-like configuration file to define messages based on the type and optionally the data for each error.
-
-<a id="entities"></a>
+As we define our `BillOrder` and `ShipOrder` classes, we will be able to use our `IS_BILLABLE` and `IS_SHIPPABLE` contracts to quickly identify orders that are invalid for that context.
 
-### Entities
+### Validating Other Data
 
-While constraints and contracts are used to validate data, entities are used to define and structure that data. Each `Stannum::Entity` contains a specific set of attributes, and each attribute has a type definition that is a `Class` or `Module` or the name of a Class or Module.
-
-Entities are defined by creating a new class and including `Stannum::Entity`:
+In addition to using them with entities, `Stannum` constraints and contracts can be used to validate almost any sort of data. For example, consider our ordering workflow. Perhaps we make a API call to a company that actually ships the order to the customer. We want to ensure that the API response contains the expected data. We can define a contract to validate the returned JSON body:
 
 ```ruby
-require 'stannum'
+SUCCESS_RESPONSE_CONTRACT = Stannum::Contract.new do
+  property :status, Stannum::Constraints::Identity.new(200)
 
-class Gadget
-  include Stannum::Entity
+  property :body, Stannum::Contracts::HashContract.new {
+    key 'ok', Stannum::Constraints::Identity.new(true)
 
-  attribute :name,        String
-  attribute :description, String,  optional: true
-  attribute :quantity,    Integer, default:  0
+    key 'shipping_confirmation',
+      Stannum::Constraint.new(
+        message: 'be a string with length 24',
+        type:    'orders.constraints.valid_shipping_confirmation'
+      ) { |value|
+        value.is_a?(String) && value.size == 24
+      }
+  }
 end
-
-gadget = Gadget.new(name: 'Self-Sealing Stem Bolt')
-gadget.name
-#=> 'Self-Sealing Stem Bolt'
-gadget.description
-#=> nil
-gadget.attributes
-#=> {
-#     name:        'Self-Sealing Stem Bolt',
-#     description: nil,
-#     quantity:    0
-#   }
-
-gadget.quantity = 10
-gadget.quantity
-#=> 10
-
-gadget[:description] = 'No one is sure what a self-sealing stem bolt is.'
-gadget[:description]
-#=> 'No one is sure what a self-sealing stem bolt is.'
 ```
 
-Our `Gadget` class has three attributes: `#name`, `#description`, and `#quantity`, which we are defining using the `.attribute` class method.
-
-We can initialize a gadget with values by passing the desired attributes to `.new`. We can read or write the attributes using either dot `.` notation or `#[]` notation. Finally, we can access all of a entity's attributes and values using the `#attributes` method.
-
-`Stannum::Entity` defines a number of helper methods for interacting with a entity's attributes:
-
-- `#[](attribute)`: Returns the value of the given attribute.
-- `#[]=(attribute, value)`: Writes the given value to the given attribute.
-- `#assign_attributes(values)`: Updates the entity's attributes using the given values. If an attribute is not given, that value is unchanged.
-- `#attributes`: Returns a hash containing the attribute keys and values.
-- `#attributes=(values)`: Sets the entity's attributes to the given values. If an attribute is not given, that attribute is set to `nil`.
-
-For all of the above methods, if a given attribute is invalid or the attribute is not defined on the entity, an `ArgumentError` will be raised.
-
-#### Attributes
-
-A entity's attributes are defined using the `.attribute` class method, and can be accessed and enumerated using the `.attributes` class method on the entity class or via the `::Attributes` constant. Internally, each attribute is represented by a `Stannum::Attribute` instance, which stores the attribute's `:name`, `:type`, and `:attributes`.
-
-```ruby
-Gadget::Attributes
-#=> an instance of Stannum::Schema
-Gadget.attributes
-#=> an instance of Stannum::Schema
-Gadget.attributes.count
-#=> 3
-Gadget.attributes.keys
-#=> [:name, :description, :quantity]
-Gadget.attributes[:name]
-#=> an instance of Stannum::Attribute
-Gadget.attributes[:quantity].options
-#=> { default: 0, required: true }
-```
-
-##### Default Values
-
-Entities can define default values for attributes by passing a `:default` value to the `.attribute` call.
-
-```ruby
-class LightsCounter
-  include Stannum::Entity
-
-  attribute :count, Integer, default: 4
-end
-
-LightsCounter.new.count
-#=> 4
-```
-
-##### Optional Attributes
-
-Entity classes can also mark attributes as `optional`. When an entity is validated (see [Validation](#entities-validation), below), optional attributes will pass with a value of `nil`.
-
-```ruby
-class WhereWeAreGoing
-  include Stannum::Entity
-
-  attribute :roads, Object, optional: true
-end
-```
-
-`Stannum` supports both `:optional` and `:required` as keys. Passing either `optional: true` or `required: false` will mark the attribute as optional. Attributes are required by default.
-
-<a id="entities-validation"></a>
-
-#### Validation
-
-Each `Stannum::Entity` automatically generates a contract that can be used to validate instances of the entity class. The contract can be accessed using the `.contract` class method or via the `::Contract` constant.
-
-```ruby
-class Gadget
-  attribute :name,        String
-  attribute :description, String,  optional: true
-  attribute :quantity,    Integer, default:  0
-end
-
-Gadget::Contract
-#=> an instance of Stannum::Contract
-Gadget.contract
-#=> an instance of Stannum::Contract
-
-gadget = Gadget.new
-Gadget.contract.matches?(gadget)
-#=> false
-Gadget.contract.errors_for(gadget)
-#=> [
-#     {
-#       data:    { type: String },
-#       message: nil,
-#       path:    [:name],
-#       type:    'stannum.constraints.is_not_type'
-#     }
-#   ]
-
-gadget = Gadget.new(name: 'Self-Sealing Stem Bolt')
-Gadget.contract.matches?(gadget)
-#=> true
-```
-
-You can also define additional constraints using the `.constraint` class method.
-
-```ruby
-class Gadget
-  constraint :name, Stannum::Constraints::Presence.new
-
-  constraint :quantity do |qty|
-    qty >= 0
-  end
-end
-
-gadget = Gadget.new(name: '')
-Gadget.contract.matches?(gadget)
-#=> false
-Gadget.contract.errors_for(gadget)
-#=> [
-#     {
-#       data:    {},
-#       message: nil,
-#       path:    [:name],
-#       type:    'stannum.constraints.absent'
-#     }
-#   ]
-```
-
-The `.constraint` class method takes either an instance of `Stannum::Constraint` or a block. If given an attribute name, the constraint will be matched against the value of that attribute; otherwise, the constraint will be matched against the object itself.
-
-<a id="builtin-constraints"></a>
-
-### Built-In Constraints
-
-Stannum defines a set of built-in constraints that can be used in any project.
-
-**Absence Constraint**
-
-The inverse of a [Presence constraint](#builtin-constraints-presence). Matches `nil`, and objects that both respond to `#empty?` and for whom `#empty?` returns true, such as empty `String`s, `Array`s and `Hash`es.
-
-```ruby
-constraint = Stannum::Constraints::Absence.new
-
-constraint.matches?(nil)
-#=> true
-constraint.matches?('')
-#=> true
-constraint.matches?('Greetings, programs!')
-#=> false
-constraint.matches?(Object.new)
-#=> false
-```
-
-**Anything Constraint**
-
-Matches any object, even `nil`.
-
-```ruby
-constraint = Stannum::Constraints::Anything.new
-
-constraint.matches?(nil)
-#=> true
-constraint.matches?(Object.new)
-#=> true
-constraint.matches?('Hello, world')
-#=> true
-```
-
-**Boolean Constraint**
-
-Matches `true` and `false`.
-
-```ruby
-constraint = Stannum::Constraints::Boolean.new
-
-constraint.matches?(nil)
-#=> false
-constraint.matches?(Object.new)
-#=> false
-constraint.matches?(false)
-#=> true
-constraint.matches?(true)
-#=> true
-```
-
-**Enum Constraint**
-
-Matches any the specified values.
-
-```ruby
-constraint = Stannum::Constraints::Enum.new('red', 'blue', 'green')
-
-constraint.matches?(nil)
-#=> false
-constraint.matches?('purple')
-#=> false
-constraint.matches?('red')
-#=> true
-constraint.matches?('green')
-#=> true
-```
-
-**Equality Constraint**
-
-Matches any object equal to the given object.
-
-```ruby
-value      = 'Greetings, programs!'
-constraint = Stannum::Constraints::Equality.new(value)
-
-constraint.matches?(nil)
-#=> false
-constraint.matches?(value.dup)
-#=> true
-constraint.matches?(value)
-#=> true
-```
-
-**Identity Constraint**
-
-Matches the given object.
-
-```ruby
-value      = 'Greetings, starfighter!'
-constraint = Stannum::Constraints::Identity.new(value)
-
-constraint.matches?(nil)
-#=> false
-constraint.matches?(value.dup)
-#=> false
-constraint.matches?(value)
-#=> true
-```
-
-**Nothing Constraint**
-
-Does not match any objects.
-
-```ruby
-constraint = Stannum::Constraints::Nothing.new
-
-constraint.matches?(nil)
-#=> false
-constraint.matches?(Object.new)
-#=> false
-constraint.matches?('Hello, world')
-#=> false
-```
-
-<a id="builtin-constraints-presence"></a>
-
-**Presence Constraint**
-
-Matches objects that are not `nil`, and that either do not respond to `#empty?` or for whom `#empty?` returns false.
-
-```ruby
-constraint = Stannum::Constraints::Presence.new
-
-constraint.matches?(nil)
-#=> false
-constraint.matches?('')
-#=> false
-constraint.matches?('Greetings, programs!')
-#=> true
-constraint.matches?(Object.new)
-#=> true
-```
-
-**Signature Constraint**
-
-Matches if the object responds to all of the specified methods.
-
-```ruby
-constraint = Stannum::Constraints::Signature.new(:[], :keys)
-
-constraint.matches?(nil)
-#=> false
-constraint.matches?([])
-#=> false
-constraint.matches?({})
-#=> true
-```
-
-<a id="builtin-constraints-type"></a>
-
-**Type Constraint**
-
-Matches if the specified type is an ancestor of the object.
-
-```ruby
-constraint = Stannum::Constraints::Type.new(StandardError)
-
-constraint.matches?(nil)
-#=> false
-constraint.matches?(Object.new)
-#=> false
-constraint.matches?(StandardError.new)
-#=> true
-constraint.matches?(ArgumentError.new)
-#=> true
-```
-
-Type constraints can be `optional` by passing either `optional: true` or `required: false` to the constructor. An optional type constraint will also accept `nil` as a value.
-
-```ruby
-constraint = Stannum::Constraints::Type.new(String, optional: true)
-
-constraint.matches?(nil)
-#=> true
-constraint.matches?(Object.new)
-#=> false
-constraint.matches?('a String')
-#=> true
-```
-
-**Union Constraint**
-
-Matches if the object matches any of the given constraints.
-
-```ruby
-constraint = Stannum::Constraints::Union.new(
-  Stannum::Constraints::Type.new(String),
-  Stannum::Constraints::Type.new(Symbol)
-)
-
-constraint.matches?(nil)
-#=> false
-constraint.matches?(Object.new)
-#=> false
-constraint.matches?('a String')
-#=> true
-constraint.matches?(:a_symbol)
-#=> true
-```
-
-#### Property Constraints
-
-Property constraints match against the properties of the object.
-
-**Do Not Match Property Constraint**
-
-Matches if none of the values of the given properties are equal to the value of the expected property.
-
-```ruby
-UpdatePassword = Struct.new(:old_password, :new_password)
-constraint    = Stannum::Constraints::Properties::DoNotMatchProperty.new(
-  :old_password,
-  :new_password
-)
-
-params = UpdatePassword.new('tronlives', 'ifightfortheusers')
-constraint.matches?(params)
-#=> true
-
-params = UpdatePassword.new('tronlives', 'tronlives')
-constraint.matches?(params)
-#=> false
-constraint.errors_for(params)
-#=> [
-  {
-    path: [:confirmation],
-    type: 'stannum.constraints.is_equal_to',
-    data: { expected: '[FILTERED]', actual: '[FILTERED]' }
-  }
-]
-```
-
-**Match Property Constraint**
-
-Matches if all the values of the given properties are equal to the value of the expected property.
-
-```ruby
-ConfirmPassword = Struct.new(:password, :confirmation)
-constraint    = Stannum::Constraints::Properties::MatchProperty.new(
-  :password,
-  :confirmation
-)
-
-params = ConfirmPassword.new('tronlives', 'ifightfortheusers')
-constraint.matches?(params)
-#=> false
-constraint.errors_for(params)
-#=> [
-  {
-    path: [:confirmation],
-    type: 'stannum.constraints.is_not_equal_to',
-    data: { expected: '[FILTERED]', actual: '[FILTERED]' }
-  }
-]
-
-params = ConfirmPassword.new('tronlives', 'tronlives')
-constraint.matches?(params)
-#=> true
-```
-
-#### Type Constraints
-
-Stannum also defines a set of built-in type constraints. Unless otherwise noted, these are identical to a [Type Constraint](#builtin-constraints-type) with the given Class.
-
-```ruby
-constraint = Stannum::Constraints::Types::StringType.new
-
-constraint.matches?(nil)
-#=> false
-constraint.matches?(Object.new)
-#=> false
-constraint.matches?('a String')
-#=> true
-```
-
-The following type constraints are defined:
-
-- **ArrayType**
-- **BigDecimalType**
-- **DateTimeType**
-- **DateType**
-- **FloatType**
-- **HashType**
-- **IntegerType**
-- **NilType**
-- **ProcType**
-- **StringType**
-- **SymbolType**
-- **TimeType**
-
-In addition, the following type constraints have additional options or behavior.
-
-**ArrayType Constraint**
-
-You can specify an `item_type` for an `ArrayType` constraint. An object will only match if the object is an `Array` and all of the array's items are of the specified type or match the given constraint.
-
-```ruby
-constraint = Stannum::Constraints::Types::ArrayType.new(item_type: String)
-
-constraint.matches?(nil)
-#=> false
-constraint.matches?([])
-#=> true
-constraint.matches?([1, 2, 3])
-#=> false
-constraint.matches?(['uno', 'dos', 'tres'])
-#=> true
-```
-
-You can also specify whether the constraint allows an empty Array by setting the `allow_empty: false` keyword in the constructor. If `false`, the constraint will only match arrays with one or more items. The default value is `true`.
-
-```ruby
-constraint = Stannum::Constraints::Types::ArrayType.new(allow_empty: false)
-
-constraint.matches?(nil)
-#=> false
-constraint.matches?([])
-#=> false
-constraint.matches?([1, 2, 3])
-#=> true
-```
-
-**HashType Constraint**
-
-You can specify a `key_type` and/or a `value_type` for a `HashType` constraint. An object will only match if the object is a `Hash`, all of the hash's keys and/or values are of the specified type or match the given constraint.
-
-```ruby
-constraint = Stannum::Constraints::Types::HashType.new(key_type: String, value_type: Integer)
-
-constraint.matches?(nil)
-#=> false
-constraint.matches?({})
-#=> true
-constraint.matches?({ ichi: 1 })
-#=> false
-constraint.matches?({ 'ichi' => 'one' })
-#=> false
-constraint.matches?({ 'ichi' => 1 })
-```
-
-You can also specify whether the constraint allows an empty Hash by setting the `allow_empty: false` keyword in the constructor. If `false`, the constraint will only match hashes with one or more keys. The default value is `true`.
-
-```ruby
-constraint = Stannum::Constraints::Types::HashType.new(allow_empty: false
-
-constraint.matches?(nil)
-#=> false
-constraint.matches?({})
-#=> false
-constraint.matches?({ ichi: 1 })
-#=> true
-```
-
-There are predefined constraints for matching `Hash`es with common key types:
-
-- **HashWithIndifferentKeys:** Matches keys that are either `String`s or `Symbol`s and not empty.
-- **HashWithStringKeys:** Matches keys that are `String`s.
-- **HashWithSymbolKeys:** Matches keys that are `Symbol`s.
-
-<a id="signature-constraints"></a>
-
-#### Signature Constraints
-
-Stannum provides a small number of built-in signature constraints.
-
-```ruby
-constraint = Stannum::Constraints::Signatures::Map.new
-
-constraint.matches?(nil)
-#=> false
-constraint.matches?([])
-#=> false
-constraint.matches?({})
-#=> true
-```
-
-- **Map:** Matches objects that behave like a `Hash`. Specifically, objects responding to `#[]`, `#each`, and `#keys`.
-- **Tuple:** Matches objects that behave like an `Array`. Specifically, objects responding to `#[]`, `#each`, and `#size`.
-
-<a id="builtin-contracts"></a>
-
-### Built-In Contracts
-
-Stannum defines some pre-defined contracts.
-
-**Array Contract**
-
-Matches an instance of `Array` and defines the `.item` class method to add constraints on the array items. See also [Array Contracts](#array-contracts), above.
-
-```ruby
-class BaseballContract < Stannum::Contracts::ArrayContract
-  def initialize
-    super do
-      item { |actual| actual == 'Who' }
-      item { |actual| actual == 'What' }
-      item { |actual| actual == "I Don't Know" }
-    end
-  end
-end
-```
-
-**Hash Contract**
-
-Matches an instance of `Hash` and defines the `.key` class method to add constraints on the hash keys and values. See also [Hash Contracts](#hash-contracts), above.
-
-```ruby
-class ResponseContract < Stannum::Contracts::HashContract
-  def initialize
-    super do
-      key :status, Stannum::Constraints::Types::IntegerType.new
-
-      key :json,
-        Stannum::Contracts::HashContract.new(allow_extra_keys: true) do
-          key :ok, Stannum::Constraints::Boolean.new
-        end
-
-      key :signature, Stannum::Constraints::Presence.new
-    end
-  end
-end
-```
-
-Stannum also defines an `IndifferentHashContract` class, which will match against both string and symbol keys.
-
-**Map Contract**
-
-As a `HashContract`, but matches against any object which uses the `#[]` operator to access key-value data. See [Map Constraint](signature-constraints), above.
-
-**Parameters Contract**
-
-Matches the parameters of a method call.
-
-```ruby
-class AuthorizationParameters < Stannum::Contracts::ParametersContract
-  def initialize
-    super do
-      argument :action, Symbol
-
-      argument :record_class, Class, default: true
-
-      keyword :role, String, default: true
-
-      keyword :user, Stannum::Constraints::Type.new(User)
-    end
-  end
-end
-
-contract   = AuthorizationParameters.new
-parameters = {
-  arguments: [:create, Article],
-  keywords:  {},
-  block:     nil
-}
-contract.matches?(parameters)
-#=> false
-errors = contract.errors_for(parameters)
-errors[:arguments].empty?
-#=> true
-errors[:keywords].empty?
-#=> false
-```
-
-Each `ParametersContract` defines `.argument`, `.keyword`, and `.block` class methods to define the expected method parameters.
-
-- The `.argument` class method defines an expected argument. Like the `.item` class method in an `ArrayContract` (see [Array Contracts](#array-contracts), above), each call to `.argument` will reference the next positional argument.
-- The `.keyword` class method defines an expected keyword.
-- The `.block` class method can accept either a constraint, or `true` or `false`. If given a constraint, the block passed to the method will be matched against the constraint. If given `true`, then the contract will match against any block and will fail if the method is not called with a block; likewise, if given `false`, the contract will match if no block is given and fail if the method is called with a block.
-
-Because of Ruby's semantics around arguments and keywords with default values, the `:default` keyword has a special meaning for parameters contracts. If `.argument` or `.keyword` is called with the `:default` keyword, it indicates that that parameter has a default value in the method definition. If that argument or keyword is *omitted*, the parameters will still match the contract. However, an explicit value of `nil` will still fail unless `nil` is a valid value for the relevant constraint.
-
-`ParametersContract` also has support for variadic arguments and keywords.
-
-```ruby
-class RecipeParameters < Stannum::Contracts::ParametersContract
-  def initialize
-    super do
-      arguments :tools,       String
-      keywords  :ingredients, Stannum::Contracts::TupleContract.new do
-        item Stannum::Constraints::Type.new(String),
-          property_name: :amount
-        item Stannum::Constraints::Type.new(String, optional: true),
-          property_name: :unit
-      end
-      block     true
-    end
-  end
-end
-```
-
-The `.arguments` class method creates a constraint that matches against any arguments without an explicit `.argument` expectation. Likewise, the `.keywords` class method creates a constraint that matches against any keywords without an explicit `.keyword` expectation. The contract will automatically convert a Class into the corresponding Type constraint (see [Type Constraint](#builtin-constraints-type), above).
-
-**Tuple Contract**
-
-As an `ArrayContract`, but matches against any object which uses the `#[]` operator to access indexed data. See [Tuple Constraint](signature-constraints), above.
+We can then validate the API response by calling `SUCCESS_RESPONSE_CONTRACT.matches?(response)`.