verquest 0.6.2 → 0.6.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a4868bbd147183e51c6f9221695daf82a9bcafb6a8622b723b67fe79bc3b72c3
-  data.tar.gz: d80029b08f825959f68fe88e94c323a0f334c0279b360ca1489b3b9bd4d169f8
+  metadata.gz: 5be764c988f4ea26a04112ed68684fcc7d292e25c37c6c2105f1c62ba7c92bc8
+  data.tar.gz: 15cead4ea24fc972317e15157fd14194098f2f543ae7d2402ae81a443ad198d9
 SHA512:
-  metadata.gz: 0037ac0f502c551f6a76328c8d53ea9fbc7e78ea57598c3eec1e2e387f475ef5a0c3b46e1f058034ce246f5d7b6ff54395e98ca963d7058cc4a338b1e8709d42
-  data.tar.gz: 8da38ed81e49880c62b998967dce5d7c4caf863ff83e08e6eba2de5a182d9257ef24e1a5aa1c0d65f074c95ae94a997dc4198badcb210df5452241aba176ae7b
+  metadata.gz: 898d20e10c9ea20ccacd10fb8711778444f7cc096c09152e6ba48a167e363a19e60a2d8ed481205d2331b3b5a076ccc888a279ba44121342e698ade944ff9c8b
+  data.tar.gz: 23dba503f13f33a571f65008eaa13f2f94347dd974cfa45e9e8bb2f76e9e2599e0ab19fed299b2ea43144641e642c54a30d636ffe0d332967cb7ec84c521f3d6

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 ## [Unreleased]
 
+## [0.6.3] - 2026-09-23
+
+### Fixed
+- Handling `nullable: true` ([#18](https://github.com/verquest/verquest/pull/18), [@CiTroNaK](https://github.com/CiTroNaK))
+
+## [0.6.3] - 2026-03-17
+
+### Fixed
+- Transformer fixes: fix null propagation, unknown discriminator, and null variant path.
+
 ## [0.6.2] - 2025-12-09
 
 ### Fixed

data/README.md

@@ -319,6 +319,20 @@ Will produce this validation schema:
 
 You can define nullable properties in your request schema by setting the `nullable` option to `true`. This feature is based on the latest JSON Schema specification, which is also used in OpenAPI 3.1.
 
+Nullable enums include Ruby `nil` in their allowed values, which exports as JSON `null`, not the string `"null"`. This also applies to fields with an `enum:` constraint (including custom field types). The supplied values array is not modified.
+
+```ruby
+enum :role, values: %w[member admin], nullable: true
+# => {"role" => {"enum" => ["member", "admin", nil]}}
+
+const :kind, value: "user", nullable: true
+# => {"kind" => {"anyOf" => [{"const" => "user"}, {"type" => "null"}]}}
+```
+
+Nullable constants and references use `anyOf` with a null alternative in both exported and validation schemas. Nullable `one_of` uses an outer `anyOf` around the original `oneOf` and the null alternative. This allows null even when a referenced schema or multiple variants already accept it, while preserving all restrictions on non-null values. A discriminator, when present, stays alongside the inner `oneOf`.
+
+`required: true` still requires the key to be present; `nullable: true` only permits its value to be null. Defaults stay on the outer nullable schema so missing properties still receive them when default insertion is enabled. Explicit null values are not replaced by defaults.
+
 ```ruby
 class NullableRequest < Verquest::Base
   description "This is a simple request with nullable properties for testing purposes."
@@ -365,13 +379,18 @@ Will produce this validation schema:
       "additionalProperties" => false
     },
     "referenced_object" => {
-      "type" => %w[object null],
-      "description" => "This is an another example for testing purposes.",
-      "required" => %w[simple_field nested],
-      "properties" => {"simple_field" => {"type" => "string", "description" => "The simple field"}, "nested" => {"type" => "object", "required" => %w[nested_field_1 nested_field_2], "properties" => {"nested_field_1" => {"type" => "string", "description" => "This is a nested field"}, "nested_field_2" => {"type" => "string", "description" => "This is another nested field"}}, "additionalProperties" => false}},
-      "additionalProperties" => false
+      "anyOf" => [
+        {
+          "type" => "object",
+          "description" => "This is an another example for testing purposes.",
+          "required" => %w[simple_field nested],
+          "properties" => {"simple_field" => {"type" => "string", "description" => "The simple field"}, "nested" => {"type" => "object", "required" => %w[nested_field_1 nested_field_2], "properties" => {"nested_field_1" => {"type" => "string", "description" => "This is a nested field"}, "nested_field_2" => {"type" => "string", "description" => "This is another nested field"}}, "additionalProperties" => false}},
+          "additionalProperties" => false
+        },
+        {"type" => "null"}
+      ]
     },
-    "referenced_field" => {"type" => %w[string null], "description" => "The simple field"}
+    "referenced_field" => {"anyOf" => [{"type" => "string", "description" => "The simple field"}, {"type" => "null"}]}
   },
   "additionalProperties" => false
 }

data/Rakefile

@@ -1,12 +1,35 @@
 # frozen_string_literal: true
 
 require "bundler/gem_tasks"
-require "minitest/test_task"
+require "rake/testtask"
 
-Minitest::TestTask.create
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.warning = true
+end
 
 require "rubocop/rake_task"
 
 RuboCop::RakeTask.new
 
-task default: %i[test rubocop]
+desc "Check YARD documentation coverage (must be 100%)"
+task :yard do
+  require "yard"
+
+  # Capture the stats output
+  stats = YARD::CLI::Stats.new
+  stats.run("--list-undoc")
+
+  # Check if there are any undocumented objects
+  undocumented = stats.instance_variable_get(:@undoc_list) || []
+
+  unless undocumented.empty?
+    abort "\nYARD documentation check failed: #{undocumented.size} undocumented objects found."
+  end
+
+  puts "\nYARD documentation: 100% documented"
+end
+
+task default: %i[test rubocop yard]

data/lib/verquest/base/private_class_methods.rb

@@ -164,13 +164,15 @@ module Verquest
     # @param value [Object] The value of the constant
     # @param map [String, nil] An optional mapping to another constant
     # @param required [Boolean, Array<Symbol>] Whether the constant is required
+    # @param nullable [Boolean] Whether the constant can be null
     # @param schema_options [Hash] Additional schema options for the constant
     # @return [void]
-    def const(name, value:, map: nil, required: nil, **schema_options)
+    def const(name, value:, map: nil, required: nil, nullable: nil, **schema_options)
       camelize(schema_options)
       required = default_options.fetch(:required, false) if required.nil?
+      nullable = default_options.fetch(:nullable, false) if nullable.nil?
 
-      const = Properties::Const.new(name:, value:, map:, required:, **schema_options)
+      const = Properties::Const.new(name:, value:, map:, required:, nullable:, **schema_options)
       current_scope.add(const)
     end
 
@@ -280,6 +282,36 @@ module Verquest
       current_scope.add(array)
     end
 
+    # Defines a oneOf property for polymorphic schemas
+    #
+    # Creates a JSON Schema oneOf structure where exactly one of the defined
+    # schemas must match. When used at the root level (without a name), it creates
+    # a "combination schema" where the entire request body matches one of the options.
+    #
+    # @param name [Symbol, nil] The property name, or nil for root-level oneOf
+    # @param discriminator [Symbol, nil] The property used to discriminate between schemas
+    # @param required [Boolean, Array<Symbol>, nil] Whether this property is required
+    # @param nullable [Boolean] Whether this property can be null
+    # @param map [String, nil] An optional mapping to another property
+    # @yield Block defining the schema options using reference declarations
+    # @return [void]
+    def one_of(name: nil, discriminator: nil, required: nil, nullable: nil, map: nil, &block)
+      required = default_options.fetch(:required, false) if required.nil?
+      nullable = default_options.fetch(:nullable, false) if nullable.nil?
+
+      one_of = Properties::OneOf.new(name:, discriminator:, required:, nullable:, map:)
+      current_scope.add(one_of)
+
+      if block_given?
+        previous_scope = current_scope
+        @current_scope = one_of
+
+        instance_exec(&block)
+      end
+    ensure
+      @current_scope = previous_scope if block_given?
+    end
+
     # Excludes specified properties from the current scope by removing them
     # from the version's property set
     #

data/lib/verquest/base/public_class_methods.rb

@@ -12,7 +12,7 @@ module Verquest
     # @param version [String, nil] Specific version to use, defaults to configuration setting
     # @param validate [Boolean, nil] Whether to validate the params, defaults to configuration setting
     # @param remove_extra_root_keys [Boolean, nil] Whether to remove extra keys at the root level, defaults to configuration setting
-    # @return [Verquest::Result, Hash, Exception] When validation_error_handling is :result, returns a Success result with mapped params or Failure result with validation errors.
+    # @return [Verquest::Result, Hash] When validation_error_handling is :result, returns a Success result with mapped params or Failure result with validation errors.
     #   When validation_error_handling is :raise, returns mapped params directly or raises InvalidParamsError with validation errors.
     def process(params, version: nil, validate: nil, remove_extra_root_keys: nil)
       validate = Verquest.configuration.validate_params if validate.nil?
@@ -22,7 +22,7 @@ module Verquest
 
       params = params.dup
       params = params.to_unsafe_h if params.respond_to?(:to_unsafe_h)
-      params = params.slice(*version_class.properties.keys) if remove_extra_root_keys
+      params = params.slice(*version_class.properties.keys) if remove_extra_root_keys && !version_class.combination?
 
       if validate && (validation_result = version_class.validate_params(params: params)) && validation_result.any?
         case Verquest.configuration.validation_error_handling
@@ -32,13 +32,22 @@ module Verquest
           Result.failure(validation_result)
         end
       else
-        mapped_params = version_class.map_params(params)
-
-        case Verquest.configuration.validation_error_handling
-        when :raise
-          mapped_params
-        when :result
-          Result.success(mapped_params)
+        begin
+          mapped_params = version_class.map_params(params)
+
+          case Verquest.configuration.validation_error_handling
+          when :raise
+            mapped_params
+          when :result
+            Result.success(mapped_params)
+          end
+        rescue MappingError => e
+          case Verquest.configuration.validation_error_handling
+          when :raise
+            raise
+          when :result
+            Result.failure([{message: e.message, type: "mapping_error"}])
+          end
         end
       end
     end

data/lib/verquest/configuration.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Verquest
   # Configuration for the Verquest gem
   #

data/lib/verquest/gem_version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Verquest
-  GEM_VERSION = "0.6.2"
+  GEM_VERSION = "0.6.4"
 end

data/lib/verquest/helper_methods/required_properties.rb

@@ -20,7 +20,7 @@ module Verquest
       # by selecting those with their required attribute set to true (boolean).
       # Results are memoized to avoid recalculating on subsequent calls.
       #
-      # @return [Array<Symbol>] Names of properties marked as unconditionally required (required == true)
+      # @return [Array<String>] Names of properties marked as unconditionally required (required == true)
       def required_properties
         @_required_properties ||= properties.values.select { _1.required == true }.map(&:name)
       end

data/lib/verquest/properties/array.rb

@@ -72,8 +72,8 @@ module Verquest
       # @param key_prefix [Array<String>] Prefix for the source key
       # @param value_prefix [Array<String>] Prefix for the target value
       # @param mapping [Hash] The mapping hash to be updated
-      # @param version [String, nil] The version to create mapping for, defaults to configuration setting
-      # @return [Hash] The updated mapping hash
+      # @param version [String, nil] The version to create mapping for
+      # @return [void]
       def mapping(key_prefix:, value_prefix:, mapping:, version: nil)
         mapping[(key_prefix + [name]).join("/")] = mapping_value_key(value_prefix:)
       end

data/lib/verquest/properties/base.rb

@@ -12,6 +12,9 @@ module Verquest
     class Base
       include HelperMethods::RequiredProperties
 
+      # JSON Schema for null type, used when nullable is true
+      NULL_TYPE_SCHEMA = {"type" => "null"}.freeze
+
       # @!attribute [rw] name
       #   @return [String] The name of the property
       # @!attribute [rw] required
@@ -49,7 +52,7 @@ module Verquest
       # @param value_prefix [Array<String>] Prefix for the target value
       # @param mapping [Hash] The mapping hash to be updated
       # @param version [String, nil] The version to create mapping for
-      # @return [Hash] The updated mapping hash
+      # @return [void]
       # @raise [NoMethodError] This is an abstract method that must be overridden
       def mapping(key_prefix:, value_prefix:, mapping:, version:)
         raise NoMethodError
@@ -61,6 +64,15 @@ module Verquest
       #   @return [Boolean] Whether this property can be null
       attr_reader :nullable
 
+      # Allows null without weakening constraints, keeping defaults available for insertion
+      # @param schema [Hash] The original property schema
+      # @return [Hash] The schema, optionally wrapped in a nullable union
+      def nullable_schema(schema)
+        return schema unless nullable
+
+        schema.slice("default").merge("anyOf" => [schema.except("default"), NULL_TYPE_SCHEMA])
+      end
+
       # Determines the mapping target key based on mapping configuration
       # @param value_prefix [Array<String>] Prefix for the target value
       # @param collection [Boolean] Whether this is a collection mapping

data/lib/verquest/properties/collection.rb

@@ -61,6 +61,22 @@ module Verquest
         !item.nil?
       end
 
+      # Check if this collection contains a oneOf property as its item type
+      #
+      # @return [Boolean] True if the collection contains a oneOf property
+      def has_one_of?
+        properties.values.size == 1 && properties.values.first.is_a?(Verquest::Properties::OneOf)
+      end
+
+      # Returns the oneOf property if this collection contains one
+      #
+      # @return [Verquest::Properties::OneOf, nil] The oneOf property or nil
+      def one_of_property
+        return nil unless has_one_of?
+
+        properties.values.first
+      end
+
       # Generate JSON schema definition for this collection property
       #
       # @return [Hash] The schema definition for this collection property
@@ -74,6 +90,13 @@ module Verquest
               }
             }.merge(schema_options)
           }
+        elsif has_one_of?
+          {
+            name => {
+              "type" => type,
+              "items" => one_of_property.to_schema[one_of_property.name] || one_of_property.to_schema
+            }.merge(schema_options)
+          }
         else
           {
             name => {
@@ -103,6 +126,14 @@ module Verquest
               "items" => item.to_validation_schema(version: version)
             }.merge(schema_options)
           }
+        elsif has_one_of?
+          one_of_schema = one_of_property.to_validation_schema(version: version)
+          {
+            name => {
+              "type" => type,
+              "items" => one_of_schema[one_of_property.name] || one_of_schema
+            }.merge(schema_options)
+          }
         else
           {
             name => {
@@ -122,13 +153,17 @@ module Verquest
 
       # Create mapping for this collection property and all its children
       #
-      # This method handles two different scenarios:
+      # This method handles three different scenarios:
       # 1. When the collection references an external item schema (`has_item?` returns true)
       #    - Creates mappings by transforming keys from the referenced item schema
       #    - Adds array notation ([]) to indicate this is a collection
       #    - Prefixes all keys and values with the appropriate paths
       #
-      # 2. When the collection has inline item properties
+      # 2. When the collection contains a oneOf property (`has_one_of?` returns true)
+      #    - Creates variant-keyed mappings for discriminator-less oneOf support
+      #    - Each variant gets array notation applied to its paths
+      #
+      # 3. When the collection has inline item properties
       #    - Creates mappings for each property in the collection items
       #    - Each property gets mapped with array notation and appropriate prefixes
       #
@@ -136,16 +171,20 @@ module Verquest
       # @param value_prefix [Array<String>] Prefix for the target value
       # @param mapping [Hash] The mapping hash to be updated
       # @param version [String, nil] The version to create mapping for
-      # @return [Hash] The updated mapping hash
+      # @return [void]
       def mapping(key_prefix:, value_prefix:, mapping:, version:)
         if has_item?
           value_key_prefix = mapping_value_key(value_prefix: value_prefix, collection: true)
 
           reference_mapping = item.mapping(version:).dup
-          reference_mapping.transform_keys! { "#{(key_prefix + [name]).join("/")}[]/#{_1}" }
-          reference_mapping.transform_values! { "#{value_key_prefix}/#{_1}" }
+          reference_mapping.transform_keys! { |k| "#{(key_prefix + [name]).join("/")}[]/#{k}" }
+          reference_mapping.transform_values! { |v| "#{value_key_prefix}/#{v}" }
 
           mapping.merge!(reference_mapping)
+        elsif has_one_of?
+          one_of_mapping = {}
+          one_of_property.mapping(key_prefix: key_prefix + ["#{name}[]"], value_prefix: mapping_value_prefix(value_prefix: value_prefix, collection: true), mapping: one_of_mapping, version:)
+          mapping.merge!(one_of_mapping)
         else
           properties.values.each do |property|
             property.mapping(key_prefix: key_prefix + ["#{name}[]"], value_prefix: mapping_value_prefix(value_prefix: value_prefix, collection: true), mapping:, version:)

data/lib/verquest/properties/const.rb

@@ -14,12 +14,14 @@ module Verquest
       # @param value [Object] The fixed value of the constant (can be any scalar value)
       # @param map [Object, nil] Optional mapping information
       # @param required [Boolean, Array<Symbol>] Whether this property is required, or array of dependency names (can be overridden by custom type)
+      # @param nullable [Boolean] Whether this property can be null
       # @param schema_options [Hash] Additional JSON schema options for this property
-      def initialize(name:, value:, map: nil, required: false, **schema_options)
+      def initialize(name:, value:, map: nil, required: false, nullable: false, **schema_options)
         @name = name.to_s
         @value = value
         @map = map
         @required = required
+        @nullable = nullable
         @schema_options = schema_options&.transform_keys(&:to_s)
       end
 
@@ -28,19 +30,17 @@ module Verquest
       # @return [Hash] The schema definition for this constant
       def to_schema
         {
-          name => {
-            "const" => value
-          }.merge(schema_options)
+          name => nullable_schema({"const" => value}.merge(schema_options))
         }
       end
 
       # Create mapping for this const property
       #
-      # @param key_prefix [Array<Symbol>] Prefix for the source key
+      # @param key_prefix [Array<String>] Prefix for the source key
       # @param value_prefix [Array<String>] Prefix for the target value
       # @param mapping [Hash] The mapping hash to be updated
       # @param version [String, nil] The version to create mapping for
-      # @return [Hash] The updated mapping hash
+      # @return [void]
       def mapping(key_prefix:, value_prefix:, mapping:, version: nil)
         mapping[(key_prefix + [name]).join("/")] = mapping_value_key(value_prefix:)
       end

data/lib/verquest/properties/enum.rb

@@ -26,15 +26,11 @@ module Verquest
         raise ArgumentError, "Use const for a single value" if values.length == 1
 
         @name = name.to_s
-        @values = values
+        @values = nullable ? values | [nil] : values
         @required = required
         @nullable = nullable
         @map = map
         @schema_options = schema_options&.transform_keys(&:to_s)
-
-        if nullable && !values.include?("null")
-          values << "null"
-        end
       end
 
       # Generate JSON schema definition for this enum
@@ -48,11 +44,11 @@ module Verquest
 
       # Create mapping for this enum property
       #
-      # @param key_prefix [Array<Symbol>] Prefix for the source key
+      # @param key_prefix [Array<String>] Prefix for the source key
       # @param value_prefix [Array<String>] Prefix for the target value
       # @param mapping [Hash] The mapping hash to be updated
       # @param version [String, nil] The version to create mapping for
-      # @return [Hash] The updated mapping hash
+      # @return [void]
       def mapping(key_prefix:, value_prefix:, mapping:, version: nil)
         mapping[(key_prefix + [name]).join("/")] = mapping_value_key(value_prefix:)
       end

data/lib/verquest/properties/field.rb

@@ -54,6 +54,7 @@ module Verquest
 
         if nullable
           @type = [@type, "null"]
+          @schema_options["enum"] = @schema_options["enum"] | [nil] if @schema_options.key?("enum")
         end
       end
 
@@ -68,11 +69,11 @@ module Verquest
 
       # Create mapping for this field property
       #
-      # @param key_prefix [Array<Symbol>] Prefix for the source key
+      # @param key_prefix [Array<String>] Prefix for the source key
       # @param value_prefix [Array<String>] Prefix for the target value
       # @param mapping [Hash] The mapping hash to be updated
       # @param version [String, nil] The version to create mapping for
-      # @return [Hash] The updated mapping hash
+      # @return [void]
       def mapping(key_prefix:, value_prefix:, mapping:, version: nil)
         mapping[(key_prefix + [name]).join("/")] = mapping_value_key(value_prefix:)
       end

data/lib/verquest/properties/object.rb

@@ -84,7 +84,7 @@ module Verquest
       # @param value_prefix [Array<String>] Prefix for the target value
       # @param mapping [Hash] The mapping hash to be updated
       # @param version [String, nil] The version to create mapping for
-      # @return [Hash] The updated mapping hash
+      # @return [void]
       def mapping(key_prefix:, value_prefix:, mapping:, version: nil)
         properties.values.each do |property|
           property.mapping(key_prefix: key_prefix + [name], value_prefix: mapping_value_prefix(value_prefix:), mapping:, version:)