verquest 0.6.3 → 0.6.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f02a2f54e2736694e9f26f4c4b2fd2d2939fb246b3bd9031733e6bf606fac3f0
-  data.tar.gz: 0ca7bd1d066426f72a8507cb25dcda7f45df491dedfd8ee4b0be9e425df5c528
+  metadata.gz: 5be764c988f4ea26a04112ed68684fcc7d292e25c37c6c2105f1c62ba7c92bc8
+  data.tar.gz: 15cead4ea24fc972317e15157fd14194098f2f543ae7d2402ae81a443ad198d9
 SHA512:
-  metadata.gz: 68bb809fe32619ff5bf02f43787cee0d36f6462c1fb84114b246e8165c6c8725d1fd05048cd788d5c9eb97d89b60cc9dc91c008b81ad1240d80dd3dc62cf1843
-  data.tar.gz: 59471fdfdfb8aaca008467e772d925520fd1b491ce9e303b987bc96f4c2d119f37517cc819c5506de17b2839c3f386827fc5408cfa9fa694b4250642dbd1d6a2
+  metadata.gz: 898d20e10c9ea20ccacd10fb8711778444f7cc096c09152e6ba48a167e363a19e60a2d8ed481205d2331b3b5a076ccc888a279ba44121342e698ade944ff9c8b
+  data.tar.gz: 23dba503f13f33a571f65008eaa13f2f94347dd974cfa45e9e8bb2f76e9e2599e0ab19fed299b2ea43144641e642c54a30d636ffe0d332967cb7ec84c521f3d6

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 ## [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

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/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
 

data/lib/verquest/gem_version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Verquest
-  GEM_VERSION = "0.6.3"
+  GEM_VERSION = "0.6.4"
 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
@@ -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/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,9 +30,7 @@ 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
 

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

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
 

data/lib/verquest/properties/one_of.rb

@@ -31,9 +31,6 @@ module Verquest
     #   one_of = Verquest::Properties::OneOf.new(name: :value)
     #   # Validates that exactly one schema matches
     class OneOf < Base
-      # JSON Schema for null type, used when nullable is true
-      NULL_TYPE_SCHEMA = {"type" => "null"}.freeze
-
       # @return [String, nil] The discriminator property name for schema selection
       attr_reader :discriminator
 
@@ -75,7 +72,7 @@ module Verquest
       # @return [Hash] The schema definition with oneOf array and optional discriminator
       def to_schema
         freeze_schemas
-        wrap_schema(build_schema_with_refs)
+        wrap_schema(nullable_schema(build_schema_with_refs))
       end
 
       # Generate validation schema for this oneOf property
@@ -87,7 +84,7 @@ module Verquest
       # @return [Hash] The validation schema with inline schema definitions
       def to_validation_schema(version: nil)
         freeze_schemas
-        wrap_schema(build_validation_schema(version: version))
+        wrap_schema(nullable_schema(build_validation_schema(version: version)))
       end
 
       # Create mapping for this oneOf property
@@ -386,9 +383,7 @@ module Verquest
       #
       # @return [Array<Hash>] Array of schema references
       def collect_schema_refs
-        refs = schemas.values.map { |schema| schema.to_schema[schema.name] }
-        refs << NULL_TYPE_SCHEMA if nullable
-        refs
+        schemas.values.map { |schema| schema.to_schema[schema.name] }
       end
 
       # Collects inline schema definitions for all variants
@@ -396,9 +391,7 @@ module Verquest
       # @param version [String, nil] The version for schema resolution
       # @return [Array<Hash>] Array of inline schema definitions
       def collect_inline_schemas(version)
-        inline_schemas = schemas.values.map { |schema| schema.to_validation_schema(version: version)[schema.name] }
-        inline_schemas << NULL_TYPE_SCHEMA if nullable
-        inline_schemas
+        schemas.values.map { |schema| schema.to_validation_schema(version: version)[schema.name] }
       end
 
       # Adds discriminator information to the schema if present

data/lib/verquest/properties/reference.rb

@@ -42,20 +42,7 @@ module Verquest
       #
       # @return [Hash] The schema definition with a $ref pointer
       def to_schema
-        if nullable
-          {
-            name => {
-              "oneOf" => [
-                {"$ref" => from.to_ref(property: property)},
-                {"type" => "null"}
-              ]
-            }
-          }
-        else
-          {
-            name => {"$ref" => from.to_ref(property: property)}
-          }
-        end
+        {name => nullable_schema({"$ref" => from.to_ref(property: property)})}
       end
 
       # Generate validation schema for this reference property
@@ -65,13 +52,7 @@ module Verquest
       def to_validation_schema(version: nil)
         schema = from.to_validation_schema(version:, property: property).dup
 
-        if nullable
-          schema["type"] = [schema["type"], "null"] unless schema["type"].include?("null")
-        end
-
-        {
-          name => schema
-        }
+        {name => nullable_schema(schema)}
       end
 
       # Create mapping for this reference property

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: verquest
 version: !ruby/object:Gem::Version
-  version: 0.6.3
+  version: 0.6.4
 platform: ruby
 authors:
 - Petr Hlavicka
@@ -98,7 +98,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Verquest is a Ruby gem that offers an elegant solution for versioning API
   requests