philiprehberger-schema_validator 0.2.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 55525c7f988aea6bd1d007871569d66a11b8b79f328d85b33244b86f4e5b66c5
-  data.tar.gz: 8d7c5f754c183e5b55c82d2560d2c1af39427ca20a73fd0d639ecb047166cedd
+  metadata.gz: d8df4265e7d600d1e257959c9f8241af55300b726ec88d640c5dced38bcf452f
+  data.tar.gz: 729098b84f4986fd5bd7a34aabe0dd1908a9174a11b1df7f21917ce9f80ecda9
 SHA512:
-  metadata.gz: 21c96da7a71f69d774eafe5c3e6bfd05aec1303643ed7c615a5083bf1cd73067b82a484a4efa5b71b52c253e87e499fac6d3368c2268d93e885b8dec8cf59683
-  data.tar.gz: 4e4f524265420757023b069ec79cfc091b71f6e097627e6905bfc003d19a74883051bb04330273818de3524986d8b52b09fde5a39b765ee6afd1efced00f1be4
+  metadata.gz: 808853b4f3a53335d6bb5dec753fed996e192eaac9a346dba9ddae78f8fe5b25d91f7a1e43144a5498b42a8a58d6c70ea478784427f5928e2ba22d3f2df429e7
+  data.tar.gz: 34a39d9763676a48031e9202a72e493d3862c2efb405884f9b2017e77364032f00ec1ba50035a84c852d0582ee5f9c00ec53db876ba325acac761ee758c8d79a

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.3.0
+
+### 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
 
 - Fix rubocop: string interpolation style, ParameterLists cop

data/README.md

@@ -80,6 +80,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 +123,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
@@ -148,6 +272,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.0"
   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.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-16 00:00:00.000000000 Z
+date: 2026-03-17 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