Schemas

Schemas are a crucial part of dry-validation, they pre-process the data before it's validated by the rules and can provide detailed error messages. By default, the exposed DSL for defining schemas uses dry-schema under the hood.

Defining a schema without coercion

To define a schema that does not perform coercion, use the schema method:

class NewUserContract < Dry::Validation::Contract
  schema do
    required(:email).value(:string)
    required(:age).value(:integer)
  end
end

Now when a contract is applied, it will check the structure and types of the input:

contract = NewUserContract.new

result = contract.call(unexpected: :reality, age: 21)
# => #<Dry::Validation::Result{:age=>21} errors={:email=>["is missing"]}>

result.to_h
# => {:age=>21}

result.errors.to_h
# => {:email=>["is missing"]}

Defining a schema with Params coercion

To define a schema suitable for validating HTTP parameters, use the params method:

class NewUserContract < Dry::Validation::Contract
  params do
    required(:email).value(:string)
    required(:age).value(:integer)
  end
end

The major difference between params and the plain schema is that params will perform params-specific coercions before applying the contract's rules. For example, it will coerce strings into integers:

result = contract.call('email' => 'jane@doe.org', 'age' => '21')
# => #<Dry::Validation::Result{:email=>"jane@doe.org", :age=>21} errors={}>

result.to_h
# => {:email=>"jane@doe.org", :age=>21}

Defining a schema with JSON coercion

You can also use json to define a schema suitable for validating JSON data:

class NewUserContract < Dry::Validation::Contract
  json do
    required(:email).value(:string)
    required(:age).value(:integer)
  end
end

The coercion logic is different to params. For example, since JSON natively supports integers, it will not coerce them from strings:

result = contract.call('email' => 'jane@doe.org', 'age' => '21')
# => #<Dry::Validation::Result{:email=>"jane@doe.org", :age=>"21"} errors={:age=>["must be an integer"]}>

result = contract.call('email' => 'jane@doe.org', 'age' => 21)
# => #<Dry::Validation::Result{:email=>"jane@doe.org", :age=>21} errors={}>

result.to_h
# => {:email=>"jane@doe.org", :age=>21}

Re-using schemas

You can re-use an existing schema, or even multiple schemas, by simply passing them to schema definition method. All schema types support this feature.

require "dry/validation"

AddressSchema = Dry::Schema.Params do
  required(:country).value(:string)
  required(:zipcode).value(:string)
  required(:street).value(:string)
end

ContactSchema = Dry::Schema.Params do
  required(:email).value(:string) 
  required(:mobile).value(:string)
end

class NewUserContract < Dry::Validation::Contract
  params(AddressSchema, ContactSchema) do
    required(:name).value(:string)
    required(:age).value(:integer) 
  end
end

contract = NewUserContract.new

contract.(name: "Jane", age: "31", email: "jane@doe.org", country: "foo")
# => #<Dry::Validation::Result{:name=>"Jane", :age=>31, :email=>"jane@doe.org",
#   :country=>"foo"} errors={:zipcode=>["is missing"], :street=>["is missing"],
#   :mobile=>["is missing"]}>

Using custom types

When you define a schema using params or json, the coercion logic is handled by type objects that are resolved from the type specifications within the schema. For example, when you use params and define the type to be an :integer, then the resolved type will be Dry::Schema::Types::Params::Integer. This is just a convenience to make schema definition more concise.

If you want to use custom types, you can pass them explicitly when defining your schema:

module Types
  include Dry::Types()

  StrippedString = Types::String.constructor(&:strip)
end

class NewUserContract < Dry::Validation::Contract
  params do
    required(:email).value(Types::StrippedString)
    required(:age).value(:integer)
  end
end

Now your type will be applied:

contract.call(email: '   jane@doe   ', age: 21)
# => #<Dry::Validation::Result{:email=>"jane@doe", :age=>21} errors={}>

Learn more

  • dry-schema learn how to fully leverage schemas!
  • dry-types learn more about the coercion backend used in the schemas
  • rules learn how to define validation rules in addition to schemas

octocatEdit on GitHub