verse-schema 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b980154b603e6ac267ee886cbbbdf68914f98ce3a327ea15d1a1b0fb28d50f25
-  data.tar.gz: 5d8b23b022cc019c28fb9b4c6576bcae32fa33d747b804ea721076f9198df230
+  metadata.gz: 63618ff4cf11b43ec35e8bb88adaffdf8d15ac3a49a461427fbdc3cd8908299a
+  data.tar.gz: 2ab22e1cd477e2b4f0e4cd070f50e2fd56e89b1c323795f4ca3cbfa1944e271d
 SHA512:
-  metadata.gz: b246be324304a3c3d0b61323fcea9bcfa1abd4dbe496d9fa0915f4a8d421663a44560bdfebc068c0e8f51899a8fba375b2ce51276d20055626b9e9ffa90c8c3b
-  data.tar.gz: 95e3babf47e78975c5e6c044e7544b2ae0bed61dd2b8b589eab4bce2ee9db2fb24cd3fdd72fc2921d07b531fbdeec7cb3bb51665c7a2719a04dd78cded49c616
+  metadata.gz: d7c5cb3e34919f47de38726ea146aa1d3d3ffe77b26d999c18da1d5e441ca06fcba4d8827c42d3b515ea7c7abd73177e7627352e1c2714ef82c0e2e196b9d01a
+  data.tar.gz: 4b60874afb6bcf4b7721396b9fe799b38b1b21fe4fb31c9b8fd467b835ded25ff72f8df8a2ff7bb4cddd1dca322937aa8ad1f879bcc13e7d9e012cf027cc4f63

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+## 1.1
+
+- Add `strict` mode to `validate` which will raise an error if the input has
+extra fields (in case of schema with extra_fields: false)
+- Fix issue with query params by allowing coercion of String `'null'` into `nil` for `NilClass` field type
+
+## 1.0
+
+- First release of the Gem

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    verse-schema (1.0.0)
+    verse-schema (1.1.0)
       attr_chainable (~> 1.0)
 
 GEM

data/README.md

@@ -64,6 +64,8 @@ These examples are extracted directly from the gem's specs, ensuring they are ac
   
   - [Open Hash](#open-hash)
   
+  - [Strict Validation Mode](#strict-validation-mode)
+  
 
 - [2. Complex Structures](#2-complex-structures)
   
@@ -118,6 +120,8 @@ These examples are extracted directly from the gem's specs, ensuring they are ac
   
   - [Complex Example](#complex-example)
   
+  - [Polymorphic Schema](#polymorphic-schema)
+  
 
 
 
@@ -434,6 +438,54 @@ end
 ```
 
 
+### Strict Validation Mode
+
+
+```ruby
+it "demonstrates strict validation for extra fields during validation" do
+  # By default, schemas ignore fields not defined in the schema unless `extra_fields` is used.
+  # You can enforce strict validation by passing `strict: true` to the `validate` method.
+  # This will cause validation to fail if extra fields are provided and the schema
+  # does not explicitly allow them via `extra_fields`.
+
+  # Please note: `strict` mode is propagated to the children schemas, when you have
+  # nested structures.
+
+  # Define a standard schema (extra_fields is false by default)
+  schema = Verse::Schema.define do
+    field(:name, String)
+  end
+
+  # Default validation (strict: false) ignores extra fields
+  result_default = schema.validate({ name: "John", age: 30 })
+  expect(result_default.success?).to be true
+  expect(result_default.value).to eq({ name: "John" }) # 'age' is ignored
+
+  # Strict validation (strict: true) fails with extra fields
+  result_strict_fail = schema.validate({ name: "John", age: 30 }, strict: true)
+  expect(result_strict_fail.success?).to be false
+  expect(result_strict_fail.errors).to eq({ age: ["is not allowed"] }) # Error on extra field 'age'
+
+  # Strict validation succeeds if no extra fields are provided
+  result_strict_ok = schema.validate({ name: "John" }, strict: true)
+  expect(result_strict_ok.success?).to be true
+  expect(result_strict_ok.value).to eq({ name: "John" })
+
+  # Now, define a schema that explicitly allows extra fields
+  schema_with_extra = Verse::Schema.define do
+    field(:name, String)
+    extra_fields # Explicitly allow extra fields
+  end
+
+  # Strict validation has no effect if `extra_fields` is enabled in the schema definition
+  result_strict_extra_ok = schema_with_extra.validate({ name: "John", age: 30 }, strict: true)
+  expect(result_strict_extra_ok.success?).to be true
+  expect(result_strict_extra_ok.value).to eq({ name: "John", age: 30 }) # Extra field 'age' is allowed and included
+end
+
+```
+
+
 
 ## 2. Complex Structures
 
@@ -1584,7 +1636,142 @@ end
 ```
 
 
+### Polymorphic Schema
+
+
+```ruby
+it "demonstrates a polymorphic schema" do
+  # Polymorphism without selector model can be achieved using a builder
+  # virtual object which will convert the input schema to the correct
+  # schema based on the type of the input.
+  #
+  # Here is an example on how to do:
+  #
+  # 1. Define the base schema for the polymorphic structure:
+  base_schema = Verse::Schema.define do
+    field(:type, Symbol)
+  end
+
+  # 2. Define the specific schemas for each type:
+  facebook_schema = Verse::Schema.define(base_schema) do
+    field(:url, String)
+    field(:title, String)
+  end
+
+  google_schema = Verse::Schema.define(base_schema) do
+    field(:search, String)
+    field(:location, String)
+  end
+
+  # 3. Define a builder schema. The best way to do this is to use the
+  # scalar type:
+  builder_schema = Verse::Schema.scalar(Hash).transform do |input, error_builder|
+
+    type = input[:type]
+
+    if type.respond_to?(:to_sym)
+      type = type.to_sym
+    else
+      error_builder.add(:type, "invalid type")
+      stop
+    end
+
+    schema = case type
+              when :facebook
+                facebook_schema
+              when :google
+                google_schema
+              else
+                error_builder.add(:type, "invalid type")
+                stop
+              end
+
+    # Validate the input against the selected schema
+    result = schema.validate(input, error_builder:)
+
+    result.value if result.success?
+  end
+
+  # 4. Now, you can use the builder schema as placeholder for your
+  # polymorphic schema:
+  schema = Verse::Schema.define do
+    field(:events, Array, of: builder_schema)
+  end
+
+  # 5. Create a complex data structure to validate
+  data = {
+    events: [
+      {
+        type: "facebook",
+        url: "https://facebook.com/event/123",
+        title: "Facebook Event"
+      },
+      {
+        type: "google",
+        search: "conference 2023",
+        location: "New York"
+      }
+    ]
+  }
+
+  # 6. Validate the complex data
+  result = schema.validate(data)
+  # The validation succeeds
+  expect(result.success?).to be true
+  # The output maintains the structure with coerced values
+  expect(result.value[:events][0][:type]).to eq(:facebook)
+  expect(result.value[:events][0][:url]).to eq("https://facebook.com/event/123")
+  expect(result.value[:events][0][:title]).to eq("Facebook Event")
+
+  expect(result.value[:events][1][:type]).to eq(:google)
+  expect(result.value[:events][1][:search]).to eq("conference 2023")
+  expect(result.value[:events][1][:location]).to eq("New York")
+
+  # 6.1 Invalid data
+  invalid_data = {
+    events: [
+      {
+        type: "facebook",
+        # missing required url field
+        title: "Facebook Event"
+      },
+      {
+        type: "google",
+        search: "conference 2023",
+        # missing required location field
+      },
+      {
+        type: "invalid",
+        url: "https://invalid.com/event/123",
+        title: "Invalid Event"
+      }
+    ]
+  }
+  # Validate the invalid data
+  invalid_result = schema.validate(invalid_data)
+  # The validation fails
+  expect(invalid_result.success?).to be false
+  # The errors are collected
+  expect(invalid_result.errors).to eq({
+    :"events.0.url" => ["is required"],
+    :"events.1.location" => ["is required"],
+    :"events.2.type" => ["invalid type"]
+  })
+end
+
+```
+
+
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Sponsorship
 
+This gem was made possible thanks to the support of [Ingedata](https://ingedata.ai).
+In Ingedata, we build expert teams to support and enhance delivery of your data projects.
 
 ## Contributing
 

data/lib/verse/schema/base.rb

@@ -61,7 +61,7 @@ module Verse
 
       def valid?(input) = validate(input).success?
 
-      def validate(input, error_builder: nil, locals: {}) = raise NotImplementedError
+      def validate(input, error_builder: nil, locals: {}, strict: false) = raise NotImplementedError
 
       def new(arg)
         result = validate(arg)

data/lib/verse/schema/coalescer/register.rb

@@ -107,7 +107,7 @@ module Verse
       end
 
       register(nil, NilClass) do |value|
-        next nil if value.nil? || value == ""
+        next nil if value.nil? || value == "" || value == "null"
 
         raise Coalescer::Error, "must be nil"
       end

data/lib/verse/schema/coalescer.rb

@@ -8,13 +8,9 @@ module Verse
       @mapping = {}
 
       DEFAULT_MAPPER = lambda do |type|
-        if type == Base
-          proc do |value, opts, locals:|
-            opts[:schema].validate(value, locals:)
-          end
-        elsif type.is_a?(Base)
-          proc do |value, _opts, locals:|
-            type.validate(value, locals:)
+        if type.is_a?(Base)
+          proc do |value, _opts, locals:, strict:|
+            type.validate(value, locals:,  strict:)
           end
         elsif type.is_a?(Class)
           proc do |value|
@@ -36,7 +32,7 @@ module Verse
           end
         end
 
-        def transform(value, type, opts = {}, locals: {})
+        def transform(value, type, opts = {}, locals: {}, strict: false)
           if type.is_a?(Array)
             # fast-path for when the type match already
             type.each do |t|
@@ -52,7 +48,7 @@ module Verse
             type.each do |t|
               converted = @mapping.fetch(t) do
                 DEFAULT_MAPPER.call(t)
-              end.call(value, opts, locals:)
+              end.call(value, opts, locals:, strict:)
 
               if !converted.is_a?(Result) ||
                  (converted.is_a?(Result) && converted.success?)
@@ -70,7 +66,7 @@ module Verse
           else
             @mapping.fetch(type) do
               DEFAULT_MAPPER.call(type)
-            end.call(value, opts, locals:)
+            end.call(value, opts, locals:, strict:)
           end
         end
       end

data/lib/verse/schema/collection.rb

@@ -21,7 +21,7 @@ module Verse
         @values = values
       end
 
-      def validate(input, error_builder: nil, locals: {})
+      def validate(input, error_builder: nil, locals: {}, strict: false)
         locals = locals.dup # Ensure they are not modified
 
         error_builder = \
@@ -34,7 +34,7 @@ module Verse
             ErrorBuilder.new
           end
 
-        validate_array(input, error_builder, locals)
+        validate_array(input, error_builder, locals, strict)
       end
 
       def dup
@@ -130,7 +130,7 @@ module Verse
 
       protected
 
-      def validate_array(input, error_builder, locals)
+      def validate_array(input, error_builder, locals, strict)
         locals[:__path__] ||= []
 
         output = []
@@ -148,7 +148,8 @@ module Verse
               value,
               @values,
               @opts,
-              locals:
+              locals:,
+              strict:
             )
 
           if coalesced_value.is_a?(Result)

data/lib/verse/schema/dictionary.rb

@@ -17,7 +17,7 @@ module Verse
         @values    = values
       end
 
-      def validate(input, error_builder: nil, locals: {})
+      def validate(input, error_builder: nil, locals: {}, strict: false)
         locals = locals.dup # Ensure they are not modified
 
         error_builder = \
@@ -32,7 +32,7 @@ module Verse
 
         locals[:__path__] ||= []
 
-        validate_dictionary(input, error_builder, locals)
+        validate_dictionary(input, error_builder, locals, strict)
       end
 
       def dup
@@ -117,7 +117,7 @@ module Verse
 
       protected
 
-      def validate_dictionary(input, error_builder, locals)
+      def validate_dictionary(input, error_builder, locals, strict)
         output = {}
 
         unless input.is_a?(Hash)
@@ -134,7 +134,8 @@ module Verse
               value,
               @values,
               @opts,
-              locals:
+              locals:,
+              strict:
             )
 
           if coalesced_value.is_a?(Result)

data/lib/verse/schema/field.rb

@@ -347,12 +347,12 @@ module Verse
       alias_method :<, :inherit?
 
       # :nodoc:
-      def apply(value, output, error_builder, locals)
+      def apply(value, output, error_builder, locals, strict)
         locals[:__path__].push(@name)
 
         if @type.is_a?(Base)
           error_builder.context(@name) do |error_builder|
-            result = @type.validate(value, error_builder:, locals:)
+            result = @type.validate(value, error_builder:, locals:, strict:)
 
             # Apply field-level post-processors to the result of the nested schema validation
             output[@name] = if @post_processors && error_builder.errors.empty?
@@ -365,7 +365,7 @@ module Verse
           end
         else
           coalesced_value =
-            Coalescer.transform(value, @type, @opts, locals:)
+            Coalescer.transform(value, @type, @opts, locals:, strict:)
 
           if coalesced_value.is_a?(Result)
             error_builder.combine(@name, coalesced_value.errors)

data/lib/verse/schema/scalar.rb

@@ -21,7 +21,7 @@ module Verse
         @values = values
       end
 
-      def validate(input, error_builder: nil, locals: {})
+      def validate(input, error_builder: nil, locals: {}, strict: false)
         locals = locals.dup # Ensure they are not modified
 
         error_builder = \
@@ -34,7 +34,7 @@ module Verse
             ErrorBuilder.new
           end
 
-        validate_scalar(input, error_builder, locals)
+        validate_scalar(input, error_builder, locals, strict)
       end
 
       def dup
@@ -122,7 +122,7 @@ module Verse
 
       protected
 
-      def validate_scalar(input, error_builder, locals)
+      def validate_scalar(input, error_builder, locals, strict)
         coalesced_value = nil
 
         begin
@@ -131,7 +131,8 @@ module Verse
               input,
               @values,
               nil,
-              locals:
+              locals:,
+              strict:
             )
 
           if coalesced_value.is_a?(Result)

data/lib/verse/schema/selector.rb

@@ -20,7 +20,7 @@ module Verse
         @values = values.transform_values{ |v| v.is_a?(Array) ? v : [v] }
       end
 
-      def validate(input, error_builder: nil, locals: {})
+      def validate(input, error_builder: nil, locals: {}, strict: false)
         locals = locals.dup # Ensure they are not modified
 
         error_builder = \
@@ -35,7 +35,7 @@ module Verse
 
         locals[:__path__] ||= []
 
-        validate_selector(input, error_builder, locals)
+        validate_selector(input, error_builder, locals, strict)
       end
 
       def dup
@@ -123,7 +123,7 @@ module Verse
 
       protected
 
-      def validate_selector(input, error_builder, locals)
+      def validate_selector(input, error_builder, locals, strict)
         output = {}
 
         selector = locals.fetch(:selector) do
@@ -154,7 +154,8 @@ module Verse
               input,
               fetched_values,
               nil,
-              locals:
+              locals:,
+              strict:
             )
 
           if coalesced_value.is_a?(Result)

data/lib/verse/schema/struct.rb

@@ -69,7 +69,7 @@ module Verse
 
       def valid?(input) = validate(input).success?
 
-      def validate(input, error_builder: nil, locals: {})
+      def validate(input, error_builder: nil, locals: {}, strict: false)
         error_builder = \
           case error_builder
           when String
@@ -87,7 +87,7 @@ module Verse
 
         locals = locals.dup # Ensure they are not modified
 
-        validate_hash(input, error_builder, locals)
+        validate_hash(input, error_builder, locals, strict)
       end
 
       def dup
@@ -276,7 +276,7 @@ module Verse
 
       protected
 
-      def validate_hash(input, error_builder, locals)
+      def validate_hash(input, error_builder, locals, strict)
         locals[:__path__] ||= []
 
         input = input.transform_keys(&:to_sym)
@@ -295,14 +295,25 @@ module Verse
           end
 
           if exists
-            field.apply(value, output, error_builder, locals)
+            field.apply(value, output, error_builder, locals, strict)
           elsif field.default?
-            field.apply(field.default, output, error_builder, locals)
+            field.apply(field.default, output, error_builder, locals, strict)
           elsif field.required?
             error_builder.add(field.key, "is required")
           end
         end
 
+        # If strict mode is enabled, check for extra fields
+        # that are not defined in the schema.
+        if !@extra_fields && strict
+          extra_keys = input.keys - @cache_field_name
+          if extra_keys.any?
+            extra_keys.each do |key|
+              error_builder.add(key, "is not allowed")
+            end
+          end
+        end
+
         if @post_processors && error_builder.errors.empty?
           output = @post_processors.call(output, nil, error_builder, **locals)
         end

data/lib/verse/schema/version.rb

@@ -2,6 +2,6 @@
 
 module Verse
   module Schema
-    VERSION = "1.0.0"
+    VERSION = "1.1.0"
   end
 end

data/templates/README.md.erb

@@ -68,6 +68,15 @@ These examples are extracted directly from the gem's specs, ensuring they are ac
 <% end %>
 <% end %>
 
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Sponsorship
+
+This gem was made possible thanks to the support of [Ingedata](https://ingedata.ai).
+In Ingedata, we build expert teams to support and enhance delivery of your data projects.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/verse-rb/verse-schema.

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: verse-schema
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Yacine Petitprez
 bindir: exe
 cert_chain: []
-date: 2025-04-16 00:00:00.000000000 Z
+date: 2025-04-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: attr_chainable
@@ -33,6 +33,7 @@ files:
 - ".rspec"
 - ".rubocop-https---relaxed-ruby-style-rubocop-yml"
 - ".rubocop.yml"
+- CHANGELOG.md
 - Gemfile
 - Gemfile.lock
 - README.md