philiprehberger-schema_validator 0.2.2 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 55525c7f988aea6bd1d007871569d66a11b8b79f328d85b33244b86f4e5b66c5
-  data.tar.gz: 8d7c5f754c183e5b55c82d2560d2c1af39427ca20a73fd0d639ecb047166cedd
+  metadata.gz: 5d514d5f95607aabc375a5890cce18f6c7db4832830f280dff18409c745a04cc
+  data.tar.gz: 75b430ee553c1cd579de30d76d4ffdceec7a3ce733b016edbee8457d8ec17484
 SHA512:
-  metadata.gz: 21c96da7a71f69d774eafe5c3e6bfd05aec1303643ed7c615a5083bf1cd73067b82a484a4efa5b71b52c253e87e499fac6d3368c2268d93e885b8dec8cf59683
-  data.tar.gz: 4e4f524265420757023b069ec79cfc091b71f6e097627e6905bfc003d19a74883051bb04330273818de3524986d8b52b09fde5a39b765ee6afd1efced00f1be4
+  metadata.gz: 30d7cbc99c870665fbc4267df522c2f9d8e111224cbf830a169a62b3071d975aaf7c8c25c9c3f7307ec5e6e29161a22cfb85dca4f79944f43f87f41216965b9a
+  data.tar.gz: 3731586da1bd4fbc31de7cd699c5279bb8effc6b39cfd627910f1f9a2d72428604b1191a14fb8b173c4ea898e7ba96700b4db8c5408893aad05afa8ec8db1a4f

data/CHANGELOG.md

@@ -1,23 +1,44 @@
 # Changelog
 
-## 0.2.2
+All notable changes to this gem will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+n## [0.3.1] - 2026-03-22
+
+### Changed
+- Remove extra Supported Types section from README for template compliance
+
+## [0.3.1] - 2026-03-21
+
+### Fixed
+- Standardize Installation section in README
+
+## [0.3.0] - 2026-03-17
 
+### Added
+- Nested schema validation via `nested` DSL method with recursive error prefixing
+- Array element validation with `of:` option for type-checked elements
+- Array of objects validation with `schema:` option
+- Built-in format presets: `:email`, `:url`, `:uuid`, `:iso8601`, `:phone`
+- Cross-field validation via `validate` block at schema level
+- Schema composition via `merge` method to combine and extend schemas
+
+## [0.2.2] - 2026-03-16
+
+### Fixed
 - Fix rubocop: string interpolation style, ParameterLists cop
 
-## 0.2.1
+## [0.2.1] - 2026-03-16
 
-- Add License badge to README
+### Changed
+- Remove extra Supported Types section from README for template compliance
 - Add bug_tracker_uri to gemspec
 - Add Development section to README
 - Add Requirements section to README
 
-All notable changes to this gem will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [Unreleased]
-
 ## [0.2.0] - 2026-03-13
 
 ### Added

data/README.md

@@ -1,6 +1,10 @@
-# Philiprehberger::SchemaValidator
+# philiprehberger-schema_validator
 
-Lightweight schema validation for Ruby hashes with type checking and coercion.
+[![Tests](https://github.com/philiprehberger/rb-schema-validator/actions/workflows/ci.yml/badge.svg)](https://github.com/philiprehberger/rb-schema-validator/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/philiprehberger-schema_validator.svg)](https://rubygems.org/gems/philiprehberger-schema_validator)
+[![License](https://img.shields.io/github/license/philiprehberger/rb-schema-validator)](LICENSE)
+
+Lightweight schema validation for Ruby hashes with type checking and coercion
 
 ## Requirements
 
@@ -8,7 +12,7 @@ Lightweight schema validation for Ruby hashes with type checking and coercion.
 
 ## Installation
 
-Add this line to your Gemfile:
+Add to your Gemfile:
 
 ```ruby
 gem "philiprehberger-schema_validator"
@@ -80,6 +84,32 @@ schema = Philiprehberger::SchemaValidator.define do
 end
 ```
 
+#### Format Presets
+
+Use built-in format presets instead of writing regex patterns:
+
+```ruby
+schema = Philiprehberger::SchemaValidator.define do
+  string :email, format: :email
+  string :website, format: :url
+  string :id, format: :uuid
+  string :created_at, format: :iso8601
+  string :phone, format: :phone
+end
+```
+
+Available presets:
+
+| Preset     | Matches                                          |
+|------------|--------------------------------------------------|
+| `:email`   | Basic email format (`user@domain.tld`)           |
+| `:url`     | HTTP/HTTPS URLs                                  |
+| `:uuid`    | UUID v4 format                                   |
+| `:iso8601` | ISO 8601 date and datetime                       |
+| `:phone`   | International phone numbers                      |
+
+Both symbol presets and `Regexp` values are supported for `format:`.
+
 #### `in:` — Allowlist Validation
 
 ```ruby
@@ -97,6 +127,104 @@ schema = Philiprehberger::SchemaValidator.define do
 end
 ```
 
+### Nested Schema Validation
+
+Validate objects within objects using the `nested` DSL method:
+
+```ruby
+schema = Philiprehberger::SchemaValidator.define do
+  string :name, required: true
+  nested :address, required: true do
+    string :city, required: true
+    string :zip, required: true
+  end
+end
+
+result = schema.validate({ name: "Alice", address: { city: "Vienna" } })
+result.errors # => ["address.zip is required"]
+```
+
+Nested schemas support all the same field types and options. Nesting can go arbitrarily deep:
+
+```ruby
+schema = Philiprehberger::SchemaValidator.define do
+  nested :config, required: true do
+    nested :database, required: true do
+      string :host, required: true
+      integer :port, required: true
+    end
+  end
+end
+```
+
+### Array Element Validation
+
+Validate the type of each element in an array with `of:`:
+
+```ruby
+schema = Philiprehberger::SchemaValidator.define do
+  array :tags, of: :string
+  array :scores, of: :integer
+end
+
+result = schema.validate({ tags: ["a", "b"], scores: [1, "bad", 3] })
+result.errors # => ["scores[1] must be a integer"]
+```
+
+Validate arrays of objects with `schema:`:
+
+```ruby
+address_schema = Philiprehberger::SchemaValidator.define do
+  string :city, required: true
+  string :zip, required: true
+end
+
+schema = Philiprehberger::SchemaValidator.define do
+  array :addresses, schema: address_schema
+end
+
+result = schema.validate({ addresses: [{ city: "Vienna" }] })
+result.errors # => ["addresses[0].zip is required"]
+```
+
+### Cross-Field Validation
+
+Add schema-level validation blocks for relational checks between fields:
+
+```ruby
+schema = Philiprehberger::SchemaValidator.define do
+  integer :min_age, required: false
+  integer :max_age, required: false
+
+  validate do |data, errors|
+    if data[:min_age] && data[:max_age] && data[:min_age] > data[:max_age]
+      errors << "min_age must be less than or equal to max_age"
+    end
+  end
+end
+```
+
+Multiple `validate` blocks can be defined on the same schema.
+
+### Schema Composition
+
+Combine and extend schemas using `merge`:
+
+```ruby
+base = Philiprehberger::SchemaValidator.define do
+  string :name, required: true
+end
+
+extended = base.merge do
+  integer :age, required: false
+  string :email, required: true
+end
+
+extended.fields # => [:name, :age, :email]
+```
+
+The original schema is not modified. Nested schemas and cross-field validators are preserved in the merged schema.
+
 ### Schema Introspection
 
 ```ruby
@@ -119,17 +247,6 @@ schema = Philiprehberger::SchemaValidator.define do
 end
 ```
 
-## Supported Types
-
-| DSL Method   | Ruby Type | Coerces From       |
-|-------------|-----------|-------------------|
-| `string`    | String    | any (via `to_s`)  |
-| `integer`   | Integer   | String            |
-| `float`     | Float     | String            |
-| `boolean`   | Boolean   | String (true/false/yes/no/1/0/on/off) |
-| `array`     | Array     | -                 |
-| `hash_field`| Hash      | -                 |
-
 ## API
 
 ### `Philiprehberger::SchemaValidator.define(&block)` -> `Schema`
@@ -148,6 +265,10 @@ Validates a hash against the schema. Returns a `Result` object.
 
 Validates and raises `ValidationError` if invalid.
 
+### `Schema#merge(&block)` -> `Schema`
+
+Creates a new schema combining the current schema with additional definitions from the block.
+
 ### `Result#valid?` -> `Boolean`
 
 Returns `true` if there are no errors.

data/lib/philiprehberger/schema_validator/constraints.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module SchemaValidator
+    module Constraints
+      private
+
+      def check_type(field, value, errors, field_label)
+        coerced = Coercer.coerce(value, field.type)
+        if coerced.nil?
+          errors << "#{field_label} must be #{field.type}"
+        else
+          check_constraints(field, coerced, errors, field_label)
+        end
+      end
+
+      def check_constraints(field, value, errors, field_label)
+        check_format(field, value, errors, field_label)
+        check_inclusion(field, value, errors, field_label)
+        check_range(field, value, errors, field_label)
+        check_array_elements(field, value, errors, field_label)
+        run_custom_validator(field, value, errors, field_label)
+      end
+
+      def check_format(field, value, errors, field_label)
+        return unless field.format
+
+        pattern = resolve_format(field.format)
+        errors << "#{field_label} does not match expected format" unless value.match?(pattern)
+      end
+
+      def resolve_format(fmt)
+        return fmt if fmt.is_a?(Regexp)
+
+        Formats::FORMATS.fetch(fmt) do
+          raise ArgumentError, "unknown format preset: #{fmt}"
+        end
+      end
+
+      def check_inclusion(field, value, errors, field_label)
+        return unless field.in
+
+        errors << "#{field_label} must be one of: #{field.in.join(', ')}" unless field.in.include?(value)
+      end
+
+      def check_range(field, value, errors, field_label)
+        errors << "#{field_label} must be >= #{field.min}" if field.min && value < field.min
+        errors << "#{field_label} must be <= #{field.max}" if field.max && value > field.max
+      end
+
+      def check_array_elements(field, value, errors, field_label)
+        return unless field.type == :array && value.is_a?(Array)
+
+        if field.of
+          validate_array_of_type(field, value, errors, field_label)
+        elsif field.schema
+          validate_array_of_schema(field, value, errors, field_label)
+        end
+      end
+
+      def validate_array_of_type(field, value, errors, field_label)
+        value.each_with_index do |elem, idx|
+          coerced = Coercer.coerce(elem, field.of)
+          errors << "#{field_label}[#{idx}] must be a #{field.of}" if coerced.nil?
+        end
+      end
+
+      def validate_array_of_schema(field, value, errors, field_label)
+        value.each_with_index do |elem, idx|
+          unless elem.is_a?(Hash)
+            errors << "#{field_label}[#{idx}] must be a hash"
+            next
+          end
+
+          field.schema.validate(elem).errors.each do |err|
+            errors << "#{field_label}[#{idx}].#{err}"
+          end
+        end
+      end
+
+      def run_custom_validator(field, value, errors, field_label)
+        return unless field.validator
+
+        msg = field.validator.call(value)
+        errors << "#{field_label} #{msg}" if msg.is_a?(String)
+      end
+    end
+  end
+end

data/lib/philiprehberger/schema_validator/field.rb

@@ -3,22 +3,34 @@
 module Philiprehberger
   module SchemaValidator
     class Field
-      attr_reader :name, :type, :default, :validator, :format, :in, :min, :max
+      attr_reader :name, :type, :default, :validator, :format, :in, :min, :max, :of, :schema
 
-      def initialize(name, type, required: true, default: nil, format: nil, in: nil, min: nil, max: nil, &validator) # rubocop:disable Metrics/ParameterLists
+      def initialize(name, type, required: true, default: nil, format: nil, in: nil, min: nil, max: nil, of: nil, schema: nil, &validator) # rubocop:disable Metrics/ParameterLists,Layout/LineLength
+        assign_basic_attrs(name, type, required, default, format)
+        assign_constraint_attrs(binding.local_variable_get(:in), min, max, of, schema)
+        @validator = validator
+      end
+
+      def required?
+        @required
+      end
+
+      private
+
+      def assign_basic_attrs(name, type, required, default, format)
         @name = name
         @type = type
         @required = required
         @default = default
         @format = format
-        @in = binding.local_variable_get(:in)
-        @min = min
-        @max = max
-        @validator = validator
       end
 
-      def required?
-        @required
+      def assign_constraint_attrs(inclusion, min, max, of, schema)
+        @in = inclusion
+        @min = min
+        @max = max
+        @of = of
+        @schema = schema
       end
     end
   end

data/lib/philiprehberger/schema_validator/formats.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module SchemaValidator
+    module Formats
+      FORMATS = {
+        email: /\A[^@\s]+@[^@\s]+\.[^@\s]+\z/,
+        url: %r{\Ahttps?://[^\s]+\z},
+        uuid: /\A[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\z/i,
+        iso8601: /\A\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(.\d+)?(Z|[+-]\d{2}:\d{2})?)?\z/,
+        phone: /\A\+?[0-9\s\-().]{7,}\z/
+      }.freeze
+    end
+  end
+end

data/lib/philiprehberger/schema_validator/schema.rb

@@ -5,10 +5,14 @@ module Philiprehberger
     class ValidationError < StandardError; end
 
     class Schema
+      include Constraints
+
       TYPES = %i[string integer float boolean array hash].freeze
 
       def initialize(&block)
         @fields = {}
+        @nested_schemas = {}
+        @cross_validators = []
         instance_eval(&block) if block
       end
 
@@ -19,13 +23,21 @@ module Philiprehberger
         end
       end
 
-      def fields
-        @fields.keys
+      def nested(name, **opts, &)
+        sub_schema = Schema.new(&)
+        @nested_schemas[name] = { schema: sub_schema, required: opts.fetch(:required, false) }
       end
 
-      def validate(data)
+      def validate(data = nil, &block)
+        if block
+          @cross_validators << block
+          return
+        end
+
         errors = []
         @fields.each_value { |field| validate_field(field, data, errors) }
+        @nested_schemas.each { |name, config| validate_nested(name, config, data, errors) }
+        @cross_validators.each { |cv| cv.call(data, errors) }
         Result.new(errors: errors)
       end
 
@@ -36,13 +48,31 @@ module Philiprehberger
         result
       end
 
+      def fields
+        @fields.keys
+      end
+
+      def merge(&block)
+        new_schema = Schema.new
+        new_schema.instance_variable_set(:@fields, @fields.dup)
+        new_schema.instance_variable_set(:@nested_schemas, @nested_schemas.dup)
+        new_schema.instance_variable_set(:@cross_validators, @cross_validators.dup)
+        new_schema.instance_eval(&block) if block
+        new_schema
+      end
+
       private
 
       def validate_field(field, data, errors)
         value = fetch_value(field, data)
-        return check_required(field, errors) if value.nil?
+        field_label = field.name.to_s
 
-        check_type(field, value, errors)
+        if value.nil?
+          errors << "#{field_label} is required" if field.required?
+          return
+        end
+
+        check_type(field, value, errors, field_label)
       end
 
       def fetch_value(field, data)
@@ -51,48 +81,21 @@ module Philiprehberger
         field.default
       end
 
-      def check_required(field, errors)
-        errors << "#{field.name} is required" if field.required?
-      end
+      def validate_nested(name, config, data, errors)
+        value = data[name]
 
-      def check_type(field, value, errors)
-        coerced = Coercer.coerce(value, field.type)
-        if coerced.nil?
-          errors << "#{field.name} must be #{field.type}"
-        else
-          check_constraints(field, coerced, errors)
+        if value.nil?
+          errors << "#{name} is required" if config[:required]
+          return
         end
-      end
 
-      def check_constraints(field, value, errors)
-        check_format(field, value, errors)
-        check_inclusion(field, value, errors)
-        check_range(field, value, errors)
-        run_custom_validator(field, value, errors)
-      end
-
-      def check_format(field, value, errors)
-        return unless field.format
+        return errors << "#{name} must be a hash" unless value.is_a?(Hash)
 
-        errors << "#{field.name} does not match expected format" unless value.match?(field.format)
+        collect_nested_errors(name, config[:schema], value, errors)
       end
 
-      def check_inclusion(field, value, errors)
-        return unless field.in
-
-        errors << "#{field.name} must be one of: #{field.in.join(', ')}" unless field.in.include?(value)
-      end
-
-      def check_range(field, value, errors)
-        errors << "#{field.name} must be >= #{field.min}" if field.min && value < field.min
-        errors << "#{field.name} must be <= #{field.max}" if field.max && value > field.max
-      end
-
-      def run_custom_validator(field, value, errors)
-        return unless field.validator
-
-        msg = field.validator.call(value)
-        errors << "#{field.name} #{msg}" if msg.is_a?(String)
+      def collect_nested_errors(name, schema, value, errors)
+        schema.validate(value).errors.each { |err| errors << "#{name}.#{err}" }
       end
     end
   end

data/lib/philiprehberger/schema_validator/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module SchemaValidator
-    VERSION = "0.2.2"
+    VERSION = "0.3.1"
   end
 end

data/lib/philiprehberger/schema_validator.rb

@@ -4,6 +4,8 @@ require_relative "schema_validator/version"
 require_relative "schema_validator/field"
 require_relative "schema_validator/result"
 require_relative "schema_validator/coercer"
+require_relative "schema_validator/formats"
+require_relative "schema_validator/constraints"
 require_relative "schema_validator/schema"
 
 module Philiprehberger

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-schema_validator
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.1
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-16 00:00:00.000000000 Z
+date: 2026-03-22 00:00:00.000000000 Z
 dependencies: []
 description: A zero-dependency Ruby gem for validating hash data against schemas with
   type checking, coercion, required/optional fields, and custom validators.
@@ -23,7 +23,9 @@ files:
 - README.md
 - lib/philiprehberger/schema_validator.rb
 - lib/philiprehberger/schema_validator/coercer.rb
+- lib/philiprehberger/schema_validator/constraints.rb
 - lib/philiprehberger/schema_validator/field.rb
+- lib/philiprehberger/schema_validator/formats.rb
 - lib/philiprehberger/schema_validator/result.rb
 - lib/philiprehberger/schema_validator/schema.rb
 - lib/philiprehberger/schema_validator/version.rb
@@ -35,6 +37,7 @@ metadata:
   source_code_uri: https://github.com/philiprehberger/rb-schema-validator
   changelog_uri: https://github.com/philiprehberger/rb-schema-validator/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
+  bug_tracker_uri: https://github.com/philiprehberger/rb-schema-validator/issues
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -43,7 +46,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.1'
+      version: 3.1.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="