dry-schema

To use dry-schema in your Ruby project, ensure the gem is installed and require the main entrypoint. This makes the Dry::Schema namespace available for defining data schemas and validation rules.

require 'dry/schema'

The bin/console script provides an interactive Pry-based REPL for exploring the dry-schema API. When running the console, you have access to a Context object that provides shorthand methods for defining different types of schemas.

Available shorthand methods in the console:

• schema { ... }: Calls Dry::Schema.define.
• params { ... }: Calls Dry::Schema.Params (optimized for HTTP params, handling string keys/coercion).
• json { ... }: Calls Dry::Schema.JSON (optimized for JSON data, handling symbol keys).

Additionally, Dry::Types are available via the Types module.

# Start the console from your terminal
./bin/console

# Inside the console, you can use shorthand methods:
dry-schema> my_schema = params { required(:name).filled(:string) }
dry-schema*> my_schema.call(name: 'Alice')
=> {:name=>"Alice"}

The Processor class supports several configuration settings via Dry::Configurable:

• key_map_type: Configures how keys are mapped.
• type_registry_namespace: Sets the namespace for the type registry (defaults to :strict).
• filter_empty_string: A boolean setting to determine if empty strings should be filtered (defaults to false).

In dry-schema, you can negate a predicate within a schema block using the ! operator. This is useful when you want to ensure a value does not satisfy a specific condition (e.g., ensuring a string is not empty).

Example usage:

required(:name).value(:string) { !empty? }

The #coercible method returns a new KeyMap that is configured to use a provided coercer function when processing keys. This allows the schema to transform input values during the key mapping process.

coercible_map = key_map.coercible { |value| value.to_s }

The value() macro sets predicates for a key. It can be used with simple predicates, predicates with arguments, or by passing a block for complex logic. You can also pass a type specification.

# With a predicate
required(:name).value(:filled?)

# With a predicate with arguments
required(:name).value(min_size?: 2)

# With a predicate and arguments
required(:name).value(:filled?, min_size?: 2)

# With a block
required(:name).value { filled? & min_size?(2) }

You can merge two KeyMap instances or a KeyMap with an array of key specs using the + operator. This returns a new KeyMap containing the combined keys.

new_map = key_map1 + key_map2
# or
new_map = key_map1 + [:new_key]

Use the empty? method to determine if the validation result contains any error messages.

if result.errors.empty?
  puts "Validation passed!"
end

The #write method allows you to take a source hash and rebuild its structure into a target hash based on the keys defined in the KeyMap. This is a core step in schema processing for extracting or restructuring data.

# source is the input hash, target is the output hash being built
key_map.write(source, target)

If you need to find all error messages associated with a specific attribute, you can use the [] method or the fetch method on the MessageSet.

• message_set[key]: Returns an Array<String> of error texts for the given key. Returns nil if the key does not exist.
• message_set.fetch(key): Returns an Array<String> of error texts for the given key. Raises a KeyError if the key is not found.

# Returns an array of strings, e.g., ["must be filled", "must be a string"]
errors = result.errors[:email]

# Raises KeyError if :email has no errors
errors = result.errors.fetch(:email)