dynamicschema 1.0.0.beta01

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 32cb8398626d7ac822a228c89778e566ef62182b054ab267b8edf45bc718eda3
+  data.tar.gz: 3475b1a090f57e4702076677b426300c892d91a06ac55841cd6e48657f69d7aa
+SHA512:
+  metadata.gz: a39f196fc0f7e3a657a6e776163ac5d1d90d42ff8cba556b99691074dead341d42bc9e8230cfab4ece6fd81617540a09462278ce4d5fbca97eadec218ee09902
+  data.tar.gz: bd2c0f880a7c088ccecd5df2574acf32e6242dacac8b730d44141d9b95f334828c0b39c860a24f7abd7e815eaf82c97499119c95664f565b557f80688ad955ac

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Endless International
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,548 @@
+# DynamicSchema
+
+The **DynamicSchema** gem provides a elegant and expressive way to define a domain-specific 
+language (DSL) schemas, making it effortless to build and validate complex Ruby `Hash` 
+constructs. 
+
+This is particularly useful when dealing with intricate configuration or interfacing with 
+external APIs, where data structures need to adhere to specific formats and validations. 
+By allowing default values, type constraints, nested schemas, and transformations, 
+DynamicSchema ensures that your data structures are both robust and flexible. 
+
+You can trivially define a custom schema:
+
+```ruby
+openai_request_schema = DynamicSchema.define do 
+  model           String, default: 'gpt-4o'
+  max_tokens      Integer, default: 1024
+  temperature     Float, in: 0..1
+
+  message         arguments: [ :role ], as: :messages, array: true do 
+    role          Symbol, in: [ :system, :user, :assistant ]
+    content       array: true do 
+      type        Symbol, default: :text 
+      text        String
+    end
+  end
+end
+```
+
+And then repetedly use that schema to elegantly build a schema conformant `Hash`:
+```ruby
+request = openai_request_schema.build {
+  message :system do 
+    content text: "You are a helpful assistant that talks like a pirate."
+  end
+  message :user do 
+    content text: ARGV[0] || "say hello!"
+  end
+}
+```
+
+You can find a full OpenAI request example in the `/examples` folder of this repository.
+
+---
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Usage](#usage)
+- [Values](#values)
+- [Objects](#objects)
+- [Types](#types)
+- [Options](#options)
+  - [default Option](#default-option)
+  - [required Option](#required-option)
+  - [array Option](#array-option)
+  - [as Option](#as-option)
+  - [in Option (Values Only)](#in-option)
+  - [arguments Option](#arguments-option)
+- [Validation Methods](#validation-methods)
+  - [Validation Rules](#validation-rules) 
+  - [validate!](#validate)
+  - [validate](#validate-1)
+  - [valid?](#valid)
+- [Error Types](#error-types)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'dynamicschema'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install dynamicschema
+```
+
+## Usage
+
+### Requiring the Gem
+
+To start using the `dynamic_schema` gem, simply require it in your Ruby file:
+
+```ruby
+require 'dynamic_schema'
+```
+
+### Defining Schemas with **DynamicSchema**
+
+DynamicSchema permits the caller to define a domain specific language (DSL) schema with *values*, 
+*objects* and related *options*. You can use the `DynamicSchema.define` convenience method, or 
+instantiate `DynamicSchema::Builder`, then call it's `define` method, to prepare a builder.
+
+In all cases the `define` methods require a block where the names of schema components as well as 
+their options are specified. 
+
+Once a schema is defined you may repeatedly use the `Builder` instance to 'build' a Hash of values 
+using the DSL you've defined. The builder has a 'build' method which will construct a Hash without 
+validating the values. If you've specified that a value should be of a specific type and an 
+incompatible type was given that type will be in the Hash with no indication of that violation. 
+Alterativelly, you can call the `build!` method which will validate the Hash, raising an exception
+if any of the schema criteria is violated. 
+
+Finally, you can use a builder to validate a given Hash against the schema you've defined using 
+the `validate`, `validate!` and `valid?` `Builder` instance methods.
+
+---
+
+## Values 
+
+A *value* is the basic building blocks of your schema. Values represent individual settings, 
+options or API paramters that you can define with specific types, defaults, and other options.
+
+When defining a value, you provide the name as though you were calling a Ruby method, with 
+arguments that include an optional type (which can be a `Class`, `Module` or an `Array` of these ) 
+as well as a `Hash` of options, all of which are optional: 
+
+`name {type} default: {true|false}, required: {true|false}, array: {true|false}, as: {name}, in: {Array|Range}`
+
+#### example:
+
+```ruby
+require 'dynamic_schema'
+
+# define a schema structure with values
+schema = DynamicSchema::Builder.new.define do
+  api_key
+  version, String, default: '1.0'
+end
+
+# build the schema and set values
+result = schema.build! do
+  api_key 'your-api-key'
+end
+
+# access the schema values
+puts result[:api_key]     # => "your-api-key"
+puts result[:version]     # => "1.0"
+```
+
+- defining
+  - `api_key` defines a value named `api_key`. Any type can be used to assign the value.
+  - `version, String, default: '1.0'` defines a value with a default.
+- building 
+  - `schema.build!` build accepts both a Hash and a block where you can set the values.
+  - Inside the block, `api_key 'your-api-key'` sets the value of `api_key`.
+- accessing 
+  - `result[:api_key]` retrieves the value of `api_key`.
+  - If a value has a default and you don't set it, the default value will be included in 
+    resulting hash.
+
+---
+
+## Objects
+
+A schema may be organized hierarchically, by creating collections of related values and 
+even other collections. These collections are called objects. 
+
+An *object* is defined in a similar manner to a value. Simply provide the name as though 
+calling a Ruby method, with a Hash of options and a block which encloses the child values 
+and objects:
+
+```
+name arguments: [ {argument} ], default: {true|false}, required: {true|false}, array: {true|false}, as: {name} do 
+  # child values and objects can be defined here
+end 
+```
+
+Notice an *object* does not accept a type as it is always of type `Object`.
+
+#### example:
+
+```ruby
+require 'dynamic_schema'
+
+schema = DynamicSchema::Builder.new do
+  api_key, String
+  chat_options do
+    model String, default: 'claude-3'
+    max_tokens Integer, default: 1024
+    temperature, Float, default: 0.5, in: 0..1
+    stream [ TrueClass, FalseClass ]
+  end
+end
+
+result = schema.build! do
+  api_key 'your-api-key'
+  chat_options do
+    temperature 0.8
+    stream true
+  end
+end
+
+# Accessing values
+puts result[:api_key]                     # => "your-api-key"
+puts result[:chat_options][:model]        # => "claude-3"
+puts result[:chat_options][:temperature]  # => 0.8
+puts result[:chat_options][:stream]       # => true
+```
+
+- defining
+  - `chat_options do ... end` defines an object named `chat_options`.
+  - Inside the object you can define values that belong to that object.
+- building 
+  - In the build block, you can set values for values within objects by nesting blocks.
+  - `chat_options do ... end` allows you to set values inside the `chat_options` object.
+- accessing
+  - You access values by chaining the keys: `result[:chat_options][:model]`.
+
+---
+
+## Types 
+
+An *object* is always of type `Object`. A *value* can have no type or it can be of one or 
+more types. You specify the value type by providing an instance of a `Class` when defining 
+the value. If you want to specify multiple types simply provide an array of types.
+
+#### example:
+
+```ruby
+require 'dynamic_schema'
+
+schema = DynamicSchema::Builder.new do
+  typeless_value
+  symbol_value      Symbol 
+  boolean_value     [ TrueClass, FalseClass ]
+end
+
+result = schema.build! do
+  typeless_value    Struct.new(:name).new(name: 'Kristoph')
+  symbol_value      "something"
+  boolean_value     true 
+end 
+
+puts result[:typeless_value].name             # => "Kristoph"
+puts result[:symbol_value]                    # => :something
+puts result[:boolean_value]                   # => true 
+```
+
+- defining
+  - `typeless_value` defines a value that has no type and will accept an assignment of any type 
+  - `symbol_value` defines a value that accepts symbols or types that can be coerced into 
+    symbols, such as strings (see **Type Coercion**) 
+  - `boolean_value` defines a value that can be either `true` or `false`
+
+## Options 
+
+Both *values* and *objects* can be customized through *options*. The options for both values and
+objects include `default`, `required`, `as` and `array`. In addition values support the `in`
+criteria option while objects support the `arguments` option. 
+
+### :default Option 
+
+The `:default` option allows you to specify a default value that will be used if no value is 
+provided during build.
+
+#### example:
+
+```ruby
+schema = DynamicSchema.define do
+  api_version String, default: 'v1'
+  timeout Integer, default: 30
+end
+
+result = schema.build!
+puts result[:api_version]  # => "v1"
+puts result[:timeout]      # => 30
+```
+
+### :required Option
+
+The `:required` option ensures that a value must be provided when building the schema. If a 
+required value is missing when using `build!`, `validate`, or `validate!`, 
+a `DynamicSchema::RequiredOptionError` will be raised.
+
+#### example:
+
+```ruby
+schema = DynamicSchema.define do
+  api_key String, required: true
+  timeout Integer, default: 30
+end
+
+# This will raise DynamicSchema::RequiredOptionError
+result = schema.build!
+
+# This is valid
+result = schema.build! do
+  api_key 'my-secret-key'
+end
+```
+
+### :array Option
+
+The `:array` option wraps the value or object in an array in the resulting Hash, even if only 
+one value is provided. This is particularly useful when dealing with APIs that expect array 
+inputs.
+
+#### example:
+
+```ruby
+schema = DynamicSchema.define do
+  tags String, array: true
+  message array: true do
+    text String
+    type String, default: 'plain'
+  end
+end
+
+result = schema.build! do
+  tags 'important'
+  message do
+    text 'Hello world'
+  end
+end
+
+puts result[:tags]      # => ["important"]
+puts result[:message]   # => [{ text: "Hello world", type: "plain" }]
+```
+
+### :as Option
+
+The `:as` option allows you to use a different name in the DSL than what appears in the final 
+Hash. This is particularly useful when interfacing with APIs that have specific key 
+requirements.
+
+#### example:
+
+```ruby
+schema = DynamicSchema.define do
+  content_type String, as: "Content-Type", default: "application/json"
+  api_key String, as: "Authorization"
+end
+
+result = schema.build! do
+  api_key 'Bearer abc123'
+end
+
+puts result["Content-Type"]    # => "application/json"
+puts result["Authorization"]   # => "Bearer abc123"
+```
+
+### :in Option
+
+The `:in` option provides validation for values, ensuring they fall within a specified Range or 
+are included in an Array of allowed values. This option is only available for values.
+
+#### example:
+
+```ruby
+schema = DynamicSchema.define do
+  temperature Float, in: 0..1
+  status String, in: ['pending', 'processing', 'completed']
+end
+
+# Valid
+result = schema.build! do
+  temperature 0.7
+  status 'pending'
+end
+
+# Will raise validation error - temperature out of range
+result = schema.build! do
+  temperature 1.5
+  status 'pending'
+end
+
+# Will raise validation error - invalid status
+result = schema.build! do
+  temperature 0.7
+  status 'invalid'
+end
+```
+
+### :arguments Option 
+
+The `:arguments` option allows objects to accept arguments when building. Any arguments provided
+must appear when the object is built ( and so are implicitly 'required' ).
+
+If the an argument is provided, the same argument appears in the attributes hash, or in the object 
+block, the assignemnt in the block will take priority, followed by the attributes assigned and 
+finally the argument. 
+
+#### example:
+
+```ruby
+schema = DynamicSchema.define do
+  message arguments: [ :role ], as: :messages, array: true do
+    role Symbol, required: true, in: [ :system, :user, :assistant ]
+    content String
+  end
+end
+
+result = schema.build! do
+  message :system do
+    content "You are a helpful assistant."
+  end
+  message :user do
+    content "Hello!"
+  end
+end
+```
+
+## Validation
+
+DynamicSchema provides three different methods for validating Hash structures against your 
+defined schema: `validate!`, `validate`, and `valid?`. 
+
+These methods allow you to verify that your data conforms to your schema's requirements, 
+including type constraints, required fields, and value ranges.
+
+### Validation Rules
+
+When validating, DynamicSchema checks:
+
+1. **Required Fields**: 
+   Any value or object marked as `required: true` are present.
+2. **Type Constraints**: 
+   Any values match their specified types or can be coerced to the specified type.
+3. **Value Ranges**:
+   Any values fall within their specified `:in` constraints.
+4. **Objects**: 
+   Any objects are recursively validates.
+5. **Arrays**: 
+   Any validation rules are applied to each element when `array: true`
+
+### validate!
+
+The `validate!` method performs strict validation and raises an exception when it encounters 
+the first validation error.
+
+#### example:
+
+```ruby
+schema = DynamicSchema.define do
+  api_key String, required: true
+  temperature Float, in: 0..1
+end
+
+# this will raise DynamicSchema::RequiredOptionError
+schema.validate!( { temperature: 0.5 } )
+
+# this will raise DynamicSchema::IncompatibleTypeError
+schema.validate!( {
+  api_key: ["not-a-string"],            
+  temperature: 0.5
+} )
+
+# this will raise DynamicSchema::InOptionError
+schema.validate!( {
+  api_key: "abc123",
+  temperature: 1.5     
+} )
+
+# this is valid and will not raise any errors
+schema.validate!( {
+  api_key: 123,  
+  temperature: 0.5
+} )
+```
+
+### validate
+
+The `validate` method performs validation but instead of raising exceptions, it collects and 
+returns an array of all validation errors encountered.
+
+#### example:
+
+```ruby
+schema = DynamicSchema.define do
+  api_key String, required: true
+  model String, in: ['gpt-3.5-turbo', 'gpt-4']
+  temperature Float, in: 0..1
+end
+
+errors = schema.validate({
+  model: 'invalid-model',
+  temperature: 1.5,
+  api_key: ["invalid-type"]  # Array cannot be coerced to String
+})
+
+# errors will contain:
+# - IncompatibleTypeError for api_key being an Array
+# - InOptionError for invalid model
+# - InOptionError for temperature out of range
+```
+
+### valid?
+
+The `valid?` method provides a simple boolean check of whether a Hash conforms to the schema.
+
+#### example:
+
+```ruby
+schema = DynamicSchema.define do
+  name String, required: true
+  age Integer, in: 0..120
+  id String  # Will accept both strings and numbers due to coercion
+end
+
+# Returns false
+schema.valid?({
+  name: ["Not a string"],  # Array cannot be coerced to String
+  age: 150                 # Outside allowed range
+})
+
+# Returns true
+schema.valid?({
+  name: "John",
+  age: 30,
+  id: 12345               # Numeric value can be coerced to String
+})
+```
+
+### Error Types
+
+DynamicSchema provides specific error types for different validation failures:
+
+- `DynamicSchema::RequiredOptionError`: Raised when a required field is missing
+- `DynamicSchema::IncompatibleTypeError`: Raised when a value's type doesn't match the schema 
+  and cannot be coerced
+- `DynamicSchema::InOptionError`: Raised when a value falls outside its specified range/set
+- `ArgumentError`: Raised when the provided values structure isn't a Hash
+
+Each error includes helpful context about the validation failure, including the path to the failing field and the specific constraint that wasn't met.
+
+---
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at [https://github.com/EndlessInternational/adaptive-schema](https://github.com/EndlessInternational/dynamic-schema).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/dynamicschema.gemspec

@@ -0,0 +1,39 @@
+Gem::Specification.new do | spec |
+
+  spec.name           = 'dynamicschema'
+  spec.version        = '1.0.0.beta01'
+  spec.authors        = [ 'Kristoph Cichocki-Romanov' ]
+  spec.email          = [ 'rubygems.org@kristoph.net' ]
+
+  spec.summary        = <<~TEXT.gsub( /(?<!\n)\n(?!\n)/, ' ').strip    
+    DynamicSchema is a lightweight and simple yet powerful gem that enables flexible semantic  
+    schema definitions for constructing and validating complex configurations and other similar 
+    payloads.  
+  TEXT
+  spec.description    = <<~TEXT.gsub( /(?<!\n)\n(?!\n)/, ' ').strip     
+    The DynamicSchema gem provides a elegant and expressive way to define a domain-specific 
+    language (DSL) schemas, making it effortless to build and validate complex Ruby hashes. 
+
+    This is particularly useful when dealing with intricate configurations or 
+    interfacing with external APIs, where data structures need to adhere to specific formats 
+    and validations. By allowing default values, type constraints, nested schemas, and 
+    transformations, DynamicSchema ensures that your data structures are both robust and 
+    flexible.  
+  TEXT
+
+  spec.license        = 'MIT'
+  spec.homepage       = 'https://github.com/EndlessInternational/dynamic_schema'
+  spec.metadata       = {
+    'source_code_uri'   => 'https://github.com/EndlessInternational/dynamic_schema',
+    'bug_tracker_uri'   => 'https://github.com/EndlessInternational/dynamic_schema/issues',
+#    'documentation_uri' => 'https://github.com/EndlessInternational/dynamic_schema'
+  }
+
+  spec.required_ruby_version = '>= 3.0'
+  spec.files         = Dir[ "lib/**/*.rb", "LICENSE", "README.md", "dynamicschema.gemspec" ]
+  spec.require_paths = [ "lib" ]
+
+  spec.add_development_dependency 'rspec', '~> 3.13'
+  spec.add_development_dependency 'debug', '~> 1.9'
+
+end

data/lib/dynamic_schema/builder.rb

@@ -0,0 +1,38 @@
+require_relative 'builder_methods/conversion'
+require_relative 'builder_methods/validation'
+require_relative 'resolver'
+require_relative 'receiver'
+
+module DynamicSchema
+  class Builder 
+
+    include BuilderMethods::Validation 
+    include BuilderMethods::Conversion 
+  
+    def initialize( schema = nil )
+      self.schema = schema 
+      super()
+    end
+
+    def define( &block )
+      self.schema = Resolver.new( self.schema ).resolve( &block ).schema 
+      self
+    end 
+
+    def build( values = nil, &block )
+      receiver = Receiver.new( values, schema: self.schema, converters: self.converters )
+      receiver.instance_eval( &block ) if block
+      receiver.to_h 
+    end
+
+    def build!( values = nil, &block )
+      result = self.build( values, &block )
+      validate!( result )
+      result 
+    end
+
+  private 
+    attr_accessor :schema
+
+  end
+end

data/lib/dynamic_schema/builder_methods/conversion.rb

@@ -0,0 +1,54 @@
+# types must be included to support coersion
+require 'time'
+require 'date'
+require 'uri'
+
+module DynamicSchema 
+  module BuilderMethods
+    module Conversion 
+
+      DEFAULT_CONVERTERS = {
+
+        Array       => ->( v ) { Array( v ) },
+        Date        => ->( v ) { v.respond_to?( :to_date ) ? v.to_date : Date.parse( v.to_s ) },
+        Time        => ->( v ) { v.respond_to?( :to_time ) ? v.to_time : Time.parse( v.to_s ) },
+        URI         => ->( v ) { URI.parse( v.to_s ) },
+        String      => ->( v ) { String( v ) },
+        Symbol      => ->( v ) { v.respond_to?( :to_sym ) ? v.to_sym : nil },
+        Rational    => ->( v ) { Rational( v ) },
+        Float       => ->( v ) { Float( v ) },
+        Integer     => ->( v ) { Integer( v ) },
+        TrueClass   => ->( v ) { 
+          case v
+          when Numeric 
+            v.nonzero? ? true : nil 
+          else
+            v.to_s.match(  /\A\s*(true|yes)\s*\z/i ) ? true : nil 
+          end
+        },
+        FalseClass  => ->( v ) {  
+          case v
+          when Numeric 
+            v.zero? ? false : nil 
+          else
+            v.to_s.match(  /\A\s*(false|no)\s*\z/i ) ? false : nil 
+          end
+        }
+
+      }
+
+      def initialize
+        self.converters = DEFAULT_CONVERTERS.dup
+      end
+
+      def convertor( klass, &block )
+        self.converters[ klass ] = block 
+      end
+
+    private
+
+      attr_accessor :converters
+    
+    end
+  end
+end

data/lib/dynamic_schema/builder_methods/validation.rb

@@ -0,0 +1,109 @@
+module DynamicSchema
+  module BuilderMethods
+    module Validation
+
+      def validate!( values, schema: self.schema )
+        traverse_and_validate_values( values, schema: schema ) { | error | 
+          raise error 
+        } 
+      end
+    
+      def validate( values, schema: self.schema )
+        errors = []
+          traverse_and_validate_values( values, schema: schema ) { | error | 
+            errors << error 
+        }
+        errors
+      end
+
+      def valid?( values, schema: self.schema )
+        traverse_and_validate_values( values, schema: schema ) { 
+          return false 
+        }
+        return true
+      end
+
+    protected
+
+      def value_matches_types?( value, types )
+        type_match = false  
+        Array( types ).each do | type |
+          type_match = value.is_a?( type )
+          break if type_match
+        end
+        type_match
+      end 
+
+      def traverse_and_validate_values( values, schema:, path: nil, options: nil, &block )  
+        path.chomp( '/' ) if path
+        unless values.is_a?( Hash )
+          raise ArgumentError, "The values must always be a Hash." 
+        end
+
+        schema.each do | key, criteria |
+
+          name = criteria[ :as ] || key 
+          value = values[ name ]
+
+          if criteria[ :required ] && 
+             ( !value || ( value.respond_to?( :empty ) && value.empty? ) )
+            block.call( RequiredOptionError.new( path: path, key: key ) )
+          elsif criteria[ :in ] 
+            Array( value ).each do | v |
+              unless criteria[ :in ].include?( v ) || v.nil?
+                block.call( 
+                  InOptionError.new( path: path, key: key, option: criteria[ :in ], value: v )
+                )
+              end
+            end
+          elsif !criteria[ :default_assigned ] && !value.nil?
+            unless criteria[ :array ]
+              if criteria[ :type ] == Object
+                traverse_and_validate_values( 
+                  values[ name ],
+                  schema: criteria[ :schema ] ||= criteria[ :resolver ].schema,
+                  path: "#{ ( path || '' ) + ( path ? '/' : '' ) + key.to_s }", 
+                  &block 
+                )
+              else     
+                if criteria[ :type ] && value && !criteria[ :default_assigned ]
+                  unless value_matches_types?( value, criteria[ :type ] )
+                    block.call( IncompatibleTypeError.new( 
+                      path: path, key: key, type: criteria[ :type ], value: value
+                    ) )
+                  end          
+                end
+              end
+            else 
+              if criteria[ :type ] == Object
+                groups = Array( value )
+                groups.each do | group |
+                  traverse_and_validate_values(
+                    group, 
+                    schema: criteria[ :schema ] ||= criteria[ :resolver ].schema,
+                    path: "#{ ( path || '' ) + ( path ? '/' : '' ) + key.to_s }", 
+                    &block 
+                  )
+                end
+              else
+                if criteria[ :type ] && !criteria[ :default_assigned ]
+                  value_array = Array( value )
+                  value_array.each do | v | 
+                    unless value_matches_types?( v, criteria[ :type ] )
+                      block.call( IncompatibleTypeError.new( 
+                        path: path, key: key, type: criteria[ :type ], value: v
+                      ) )
+                    end
+                  end  
+                end
+              end
+            end
+          end
+
+        end
+        nil
+      end
+
+    end
+  end
+end

data/lib/dynamic_schema/definition.rb

@@ -0,0 +1,23 @@
+require_relative 'builder'
+
+module DynamicSchema
+	module Definition
+
+    def schema( schema = nil, &block )
+      return @_schema_builder if ( schema.nil? || schema.empty? ) && !block
+      @_schema_builder = DynamicSchema::Builder.new( schema ).define( &block )
+    end
+
+    def build_with_schema( attributes = nil, &block )
+      raise RuntimeError, "The schema has not been defined." if @_schema_builder.nil?
+      @_schema_builder.build( attributes, &block )
+    end
+    
+    def build_with_schema!( attributes = nil, &block )
+      raise RuntimeError, "The schema has not been defined." if @_schema_builder.nil?
+      @_schema_builder.build!( attributes, &block )
+    end
+
+  end
+end
+

data/lib/dynamic_schema/errors.rb

@@ -0,0 +1,50 @@
+module DynamicSchema 
+  
+  class Error < StandardError; end
+
+  class IncompatibleTypeError < Error
+
+    attr_reader :keypath 
+    attr_reader :key 
+    attr_reader :type
+
+    def initialize( path: nil, key:, type:, value: )
+      path = path ? path.to_s.chomp( '/' ) : nil 
+      @key = key
+      @keypath = path ? ( path + '/' + @key.to_s ) : @key.to_s 
+      @type = type
+      type_text = @type.respond_to?( :join ) ? type.join( ', ' ) : type
+      super( "The attribute '#{@keypath}' expects '#{type_text}' but incompatible '#{value.class.name}' was given." )
+    end
+
+  end
+
+  class RequiredOptionError < Error
+
+    attr_reader :keypath 
+    attr_reader :key 
+
+    def initialize( path: nil, key:  )
+      path = path ? path.chomp( '/' ) : nil 
+      @key = key
+      @keypath = path ? ( path + '/' + @key.to_s ) : key.to_s    
+      super( "The attribute '#{@keypath}' is required but no value was given." )
+    end
+
+  end
+
+  class InOptionError < Error 
+    
+    attr_reader :keypath 
+    attr_reader :key 
+
+    def initialize( path: nil, key:, option:, value: )
+      path = path ? path.chomp( '/' ) : nil 
+      @key = key
+      @keypath = path ? ( path + '/' + @key.to_s ) : key.to_s    
+      super( "The attribute '#{@keypath}' must be in '#{option.to_s}' but '#{value.to_s}' was given." )
+    end
+
+  end
+
+end

data/lib/dynamic_schema/receiver.rb

@@ -0,0 +1,222 @@
+module DynamicSchema 
+  class Receiver < BasicObject
+
+    if defined?( ::PP )
+      include ::PP::ObjectMixin 
+      def pretty_print( pp )
+        pp.pp( { values: @values, schema: @schema } )
+      end
+    end
+
+    def initialize( values = nil, schema:, converters: )
+      raise ArgumentError, 'The Receiver values must be a nil or a Hash.'\
+        unless values.nil? || ( values.respond_to?( :[] ) && values.respond_to?( :key? ) )
+      
+      @values = {}
+      @schema = schema
+      @defaults_assigned = {}
+
+      @converters = converters&.dup 
+      
+      @schema.each do | key, criteria |
+        name = criteria[ :as ] || key 
+        if criteria.key?( :default )
+          self.__send__( key, criteria[ :default ] )
+          @defaults_assigned[ key ] = true        
+        end
+        self.__send__( key, values[ key ] ) if values && values.key?( key ) 
+      end
+
+    end
+
+    def evaluate( &block )
+      self.instance_eval( &block )
+      self
+    end
+
+    def nil?
+      false  
+    end
+
+    def empty?
+      @values.empty?
+    end
+
+    def to_h
+      recursive_to_h = ->( object ) do
+        case object
+        when ::NilClass
+          nil
+        when ::DynamicSchema::Receiver
+          recursive_to_h.call( object.to_h )
+        when ::Hash
+          object.transform_values { | value | recursive_to_h.call( value ) }
+        when ::Array
+          object.map { | element | recursive_to_h.call( element ) }
+        else
+          object.respond_to?( :to_h ) ? object.to_h : object
+        end
+      end
+
+      recursive_to_h.call( @values )
+    end
+
+    def to_s
+      inspect
+    end
+
+    def inspect
+      { values: @values, schema: @schema }.inspect 
+    end
+
+    def class
+      ::DynamicSchema::Receiver
+    end
+
+    def is_a?( klass )
+      klass == ::DynamicSchema::Receiver || klass == ::BasicObject
+    end
+
+    alias :kind_of? :is_a?
+
+    def method_missing( method, *args, &block )
+      if @schema.key?( method )
+        criteria = @schema[ method ]
+        name = criteria[ :as ] || method
+        value = @values[ name ]
+
+        unless criteria[ :array ] 
+          if criteria[ :type ] == ::Object 
+            value = __object( method, args, value: value, criteria: criteria, &block )
+          else 
+            value = __value( method, args, value: value, criteria: criteria )
+          end
+        else
+          value = @defaults_assigned[ method ] ? ::Array.new : value || ::Array.new
+          if criteria[ :type ] == ::Object
+            value = __object_array( method, args, value: value, criteria: criteria, &block )
+          else
+            value = __values_array( method, args, value: value, criteria: criteria )
+          end
+        end
+
+        @defaults_assigned[ method ] = false
+        @values[ name ] = value 
+      else
+        super
+      end
+    end
+
+    def respond_to?( method, include_private = false )
+      @schema.key?( method ) || self.class.instance_methods.include?( method ) 
+    end
+
+    def respond_to_missing?( method, include_private = false )
+      @schema.key?( method ) || self.class.instance_methods.include?( method ) 
+    end
+
+  protected 
+    
+    def __process_arguments( name, arguments, required_arguments:  )
+      count = arguments.count 
+      required_arguments = [ required_arguments ].flatten if required_arguments
+      required_count = required_arguments&.length || 0
+      ::Kernel.raise ::ArgumentError, 
+          "The attribute '#{name}' requires #{required_count} arguments " \
+          "(#{required_arguments.join(', ')}) but #{count} was given." \
+        if count < required_count 
+      ::Kernel.raise ::ArgumentError, 
+          "The attribute '#{name}' should have at most #{required_count + 1} arguments but " \
+          "#{count} was given." \
+        if count > required_count + 1
+      result = {}
+      required_arguments&.each_with_index do | name, index  |
+        result[ name.to_sym ] = arguments[ index ]
+      end
+      
+      last = arguments.last
+      case last 
+      when ::Hash 
+        result.merge( last )
+      when ::Array 
+        last.map { | v | result.merge( v ) }
+      else
+        result
+      end
+    end
+
+    def __coerce_value( types, value )
+      return value unless types && !value.nil?
+
+      types = ::Kernel.method( :Array ).call( types ) 
+      result = nil
+
+      if value.respond_to?( :is_a? )
+        types.each do | type |
+          result = value.is_a?( type ) ? value : nil 
+          break unless result.nil?
+        end
+      end
+
+      if result.nil?
+        types.each do | type |
+          result = @converters[ type ].call( value ) rescue nil
+          break unless result.nil?
+        end
+      end
+
+      result
+    end
+
+    def __value( method, arguments, value:, criteria: )
+      value = arguments.first
+      new_value = criteria[ :type ] ? __coerce_value( criteria[ :type ], value ) : value
+      new_value.nil? ? value : new_value
+    end
+
+    def __values_array( method, arguments, value:, criteria: )
+      values = [ arguments.first ].flatten
+      if type = criteria[ :type ]
+        values = values.map do | v | 
+          new_value = __coerce_value( type, v )
+          new_value.nil? ? v : new_value
+        end 
+      end
+      value.concat( values )
+    end 
+
+    def __object( method, arguments, value:, criteria:, &block )
+      attributes = __process_arguments( 
+        method, arguments, 
+        required_arguments: criteria[ :arguments ] 
+      )
+      if value.nil? || attributes&.any?  
+        value = 
+          Receiver.new( 
+            attributes,
+            converters: @converters, 
+            schema: criteria[ :schema ] ||= criteria[ :resolver ].schema 
+          )
+      end
+      value.instance_eval( &block ) if block
+      value 
+    end
+
+    def __object_array( method, arguments, value:, criteria:, &block )
+      attributes = __process_arguments( 
+        method, arguments, 
+        required_arguments: criteria[ :arguments ] 
+      )
+      value.concat( [ attributes ].flatten.map { | a |
+        receiver = Receiver.new( 
+          a,
+          converters: @converters, 
+          schema: criteria[ :schema ] ||= criteria[ :resolver ].schema 
+        )
+        receiver.instance_eval( &block ) if block
+        receiver
+      } )
+    end
+
+  end
+end    

data/lib/dynamic_schema/resolver.rb

@@ -0,0 +1,126 @@
+require_relative 'receiver'
+
+module DynamicSchema
+  class Resolver < BasicObject
+    
+    def initialize( schema = nil, resolved_blocks: nil )
+      @schema = schema || {}
+      
+      @block = nil 
+      @resolved = false 
+      @resolved_blocks = resolved_blocks || []
+    end
+
+    def resolve( &block )
+      @block = block 
+      @resolved = false 
+      unless @resolved_blocks.include?( @block )
+        @resolved_blocks << @block
+        self.instance_eval( &@block )
+        @resolved = true 
+      end
+      self
+    end
+        
+    def schema 
+      if !@resolved && @block 
+        @resolved_blocks << @block unless @resolved_blocks.include?( @block )
+        self.instance_eval( &@block ) 
+        @resolved = true
+      end
+      @schema 
+    end
+
+    def method_missing( method, *args, &block )
+      first = args.first
+      options = nil
+      if args.empty?
+        options = {}
+      # when called with just options:              name as: :streams
+      elsif first.is_a?( ::Hash )
+        options = first 
+      # when called with just type:                 name String 
+      #                                             name [ TrueClass, FalseClass ] 
+      elsif args.length == 1 && 
+            ( first.is_a?( ::Class ) || first.is_a?( ::Module ) || first.is_a?( ::Array ) )
+        options = { type: first }
+      # when called with just type and options:     name String, default: 'the default'
+      elsif args.length == 2 && 
+            ( first.is_a?( ::Class ) || first.is_a?( ::Module ) || first.is_a?( ::Array ) ) && 
+            args[ 1 ].is_a?( ::Hash )
+        options = args[ 1 ]
+        options[ :type ] = args[ 0 ]
+      else
+        ::Kernel.raise \
+          ::ArgumentError, 
+          "A schema definition may only include the type (Class or Module) followed by options (Hash). "
+      end
+
+      type = options[ :type ]
+      if type == ::Object || type.nil? && block 
+        _append_object( method, options, &block )
+      else 
+        _append_value( method, options )
+      end
+    
+    end
+
+    def to_s
+      inspect
+    end
+
+    def inspect
+      { schema: @schema }.inspect 
+    end
+
+    def class
+      ::DynamicSchema::Schema::Resolver
+    end
+
+    def is_a?( klass )
+      klass == ::DynamicSchema::Resolver || klass == ::BasicObject
+    end
+
+    alias :kind_of? :is_a?
+
+    if defined?( ::PP )
+      include ::PP::ObjectMixin 
+      def pretty_print( pp )
+        pp.pp( { schema: @schema } )
+      end
+    end      
+  
+  private
+
+    def _append_value( name, options )
+      ::Kernel.raise ::NameError, "The name '#{name}' is reserved and cannot be used for parameters." \
+        if ::DynamicSchema::Receiver.instance_methods.include?( name )
+  
+      _validate_in!( name, options[ :type ], options[ :in ] ) if options[ :in ] 
+      
+      @schema[ name ] = options
+      self
+    end
+
+    def _append_object( name, options = {}, &block )
+      ::Kernel.raise ::NameError, "The name '#{name}' is reserved and cannot be used for parameters." \
+        if ::DynamicSchema::Receiver.instance_methods.include?( name )
+
+      @schema[ name ] = options.merge( {
+        type: ::Object,
+        resolver: Resolver.new( resolved_blocks: @resolved_blocks ).resolve( &block )
+      } )    
+      self
+    end
+
+    def _validate_in!( name, type, in_option )
+      ::Kernel.raise ::TypeError,
+            "The parameter '#{name}' includes the :in option but it does not respond to 'include?'." \
+        unless in_option.respond_to?( :include? )
+    end
+
+  end
+end
+
+
+

data/lib/dynamic_schema.rb

@@ -0,0 +1,9 @@
+require_relative 'dynamic_schema/errors'
+require_relative 'dynamic_schema/builder'
+require_relative 'dynamic_schema/definition'
+
+module DynamicSchema  
+  def self.define( schema = {}, &block )
+    Builder.new( schema ).define( &block )
+  end
+end

metadata

@@ -0,0 +1,92 @@
+--- !ruby/object:Gem::Specification
+name: dynamicschema
+version: !ruby/object:Gem::Version
+  version: 1.0.0.beta01
+platform: ruby
+authors:
+- Kristoph Cichocki-Romanov
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-10-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: debug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+description: "The DynamicSchema gem provides a elegant and expressive way to define
+  a domain-specific  language (DSL) schemas, making it effortless to build and validate
+  complex Ruby hashes. \n\nThis is particularly useful when dealing with intricate
+  configurations or  interfacing with external APIs, where data structures need to
+  adhere to specific formats  and validations. By allowing default values, type constraints,
+  nested schemas, and  transformations, DynamicSchema ensures that your data structures
+  are both robust and  flexible."
+email:
+- rubygems.org@kristoph.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- dynamicschema.gemspec
+- lib/dynamic_schema.rb
+- lib/dynamic_schema/builder.rb
+- lib/dynamic_schema/builder_methods/conversion.rb
+- lib/dynamic_schema/builder_methods/validation.rb
+- lib/dynamic_schema/definition.rb
+- lib/dynamic_schema/errors.rb
+- lib/dynamic_schema/receiver.rb
+- lib/dynamic_schema/resolver.rb
+homepage: https://github.com/EndlessInternational/dynamic_schema
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/EndlessInternational/dynamic_schema
+  bug_tracker_uri: https://github.com/EndlessInternational/dynamic_schema/issues
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.19
+signing_key:
+specification_version: 4
+summary: DynamicSchema is a lightweight and simple yet powerful gem that enables flexible
+  semantic   schema definitions for constructing and validating complex configurations
+  and other similar  payloads.
+test_files: []