verquest 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 725838444df6f3861ab842c88b430aa7bbc81023637595b4a0a8a909df5a2fbe
-  data.tar.gz: 88041a5f8bc888f90894975b5fb371ac8184877bb75b74e2e099ce57997b331a
+  metadata.gz: b9349b2773c4a03024805d78257b1e763ffb87b87f27726620e343395c683aa0
+  data.tar.gz: ec2b70a4a10c3314ca27283776138f85b53b245d88869de39e450ca2eb2064de
 SHA512:
-  metadata.gz: 3991e8ff96b436e82a6edce43d591f35f669cbab9ef99b01bc26192bef94e3f48afe59595d8ae5d3d605bd96c0150bfdb557e555f1d20e79d74cbe4343d99c49
-  data.tar.gz: dcc10eeadec0f32073569db402893bb3f1ab5629da79eee32d605c476bbcf05f637f5b348f83478863bf7d28fc1d0b3d2cd9b54c38f356f3bfa53d51d3ac50bb
+  metadata.gz: 0d0042f959285f4253c7802166ab64d53b7013d765bfe954fd68a8ab46bb59f162512a285aca11c77e86a8e6b5ce36445f47e4e9530fcaa0010e8c6cadcefdf2
+  data.tar.gz: 06bbfceb1c989e1e3eabb20e495790ac35934e1cb4687e71960315c3e64d3a30b42b345c03d19d32be921b75550a6fef002d8ba44018ded8f7c9a3af73d920f0

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 ## [Unreleased]
 
+## [0.5.0] - 2025-07-01
+
+### Fixed
+- Handling `with_options` defaults like required and nullable.
+
+### New Features
+- Add `default_additional_properties` option to configuration.
+- Add support for nullable properties (`nullable: true`) based on the latest JSON Schema specification, which is also used in OpenAPI 3.1.
+- Add support for `dependentRequired` (see https://json-schema.org/understanding-json-schema/reference/conditionals#dependentRequired).
+
+## [0.4.0] - 2025-06-28
+
 ### Breaking Changes
 - **BREAKING:** Renaming validation method from `validate_schema` to `valid_schema?` to better reflect its purpose.
 - **BREAKING:** The `validate_schema` now returns an array of errors instead of a boolean value, allowing for more detailed error reporting.

data/README.md

@@ -19,7 +19,7 @@ Verquest is a Ruby gem that offers an elegant solution for versioning API reques
 Add this line to your application's Gemfile:
 
 ```ruby
-gem "verquest", "~> 0.3"
+gem "verquest", "~> 0.5"
 ```
 
 And then execute:
@@ -62,7 +62,7 @@ class UserCreateRequest < Verquest::Base
       field :email, format: "email", description: "The email address of the user"
     end
     
-    field :birth_date, type: :string, format: "date", description: "The birth date of the user"
+    field :birth_date, type: :string, nullable: true, format: "date", description: "The birth date of the user"
 
     reference :address, from: AddressCreateRequest, required: true
 
@@ -135,7 +135,7 @@ Output:
     "first_name" => {"type" => "string", "description" => "The first name of the user", "maxLength" => 50},
     "last_name" => {"type" => "string", "description" => "The last name of the user", "maxLength" => 50},
     "email" => {"type" => "string", "format" => "email", "description" => "The email address of the user"},
-    "birth_date" => {"type" => "string", "format" => "date", "description" => "The birth date of the user"},
+    "birth_date" => {"type" => ["string", "null"], "format" => "date", "description" => "The birth date of the user"},
     "address" => {"$ref" => "#/components/schemas/AddressCreateRequest"},
     "permissions" => {
       "type" => "array",
@@ -276,6 +276,101 @@ The JSON schema can be used for both validation of incoming parameters and for g
 - `schema_options`: Allows you to set additional options for the JSON Schema, such as `additional_properties` for request or per version. All fields (except `reference`) can be defined with options like `required`, `format`, `min_lenght`, `max_length`, etc. all in snake case.
 - `with_options`: Allows you to define multiple fields with the same options, reducing repetition.
 
+### Required properties
+
+You can define required properties in your request schema by setting the `required` option to `true`, or provide a list of dependent required properties. This feature is based on the latest [JSON Schema specification](https://json-schema.org/understanding-json-schema/reference/conditionals#dependentRequired), which is also used in OpenAPI 3.1.
+
+```ruby
+class DependentRequiredRequest < Verquest::Base
+  description "This is a simple request with nullable properties for testing purposes."
+
+  version "2025-06" do
+    field :name, type: :string, required: true
+    field :credit_card, type: :number, required: %i[billing_address]
+    field :billing_address, type: :string
+  end
+end
+```
+
+Will produce this validation schema:
+
+```ruby
+{
+  "type" => "object",
+  "description" => "This is a simple request with nullable properties for testing purposes.",
+  "required" => ["name"],
+  "dependentRequired" => {"credit_card" => ["billing_address"]},
+  "properties" => {
+    "name" => {"type" => "string"},
+    "credit_card" => {"type" => "number"},
+    "billing_address" => {"type" => "string"}
+  },
+  "additionalProperties" => false
+}
+```
+
+#### Nullable properties
+
+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.
+
+```ruby
+class NullableRequest < Verquest::Base
+  description "This is a simple request with nullable properties for testing purposes."
+
+  version "2025-06" do
+    with_options nullable: true do
+      array :array, type: :string
+      collection :collection_with_item, item: ReferencedRequest
+      collection :collection_with_object do
+        field :field, type: :string, nullable: false
+      end
+
+      field :field, type: :string
+
+      object :object do
+        field :field, type: :string, nullable: false
+      end
+
+      reference :referenced_object, from: ReferencedRequest
+      reference :referenced_field, from: ReferencedRequest, property: :simple_field
+    end
+  end
+end
+```
+
+Will produce this validation schema:
+
+```ruby
+{
+  "type" => "object",
+  "description" => "This is a simple request with nullable properties for testing purposes.",
+  "required" => [],
+  "properties" => {
+    "array" => {"type" => %w[array null], "items" => {"type" => "string"}},
+    "collection_with_item" => {"type" => %w[array null], "items" => {"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}},
+    "collection_with_object" => {"type" => %w[array null], "items" => {"type" => "object", "required" => [], "properties" => {"field" => {"type" => "string"}}, "additionalProperties" => false}},
+    "field" => {"type" => %w[string null]},
+    "object" => {
+      "type" => %w[object null],
+      "required" => [],
+      "properties" => {
+        "field" => {"type" => "string"}
+      },
+      "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
+    },
+    "referenced_field" => {"type" => %w[string null], "description" => "The simple field"}
+  },
+  "additionalProperties" => false
+}
+```
+
 #### Custom Field Types
 
 You can define custom field types that can be used in `field` and `array` in the configuration.
@@ -483,12 +578,15 @@ Verquest.configure do |config|
   
   # Set custom version resolver
   config.version_resolver = CustomeVersionResolver # default is `Verquest::VersionResolver`
+  
+  # Set default value for additional properties
+  config.default_additional_properties = false # default
 end
 ```
 
 ## Documentation
 
-For detailed documentation, please visit the [YARD documentation](https://www.rubydoc.info/gems/verquest/0.4.0/).
+For detailed documentation, please visit the [YARD documentation](https://www.rubydoc.info/gems/verquest/0.5.0/).
 
 ## Development
 

data/lib/verquest/base/private_class_methods.rb

@@ -92,9 +92,9 @@ module Verquest
       camelize(schema_options)
 
       if current_scope.nil?
-        versions.schema_options = schema_options
+        versions.schema_options.merge!(schema_options)
       elsif current_scope.is_a?(Version)
-        current_scope.schema_options = schema_options
+        current_scope.schema_options.merge!(schema_options)
       else
         raise "Additional properties can only be set within a version scope or globally"
       end
@@ -122,17 +122,19 @@ module Verquest
     # @param name [Symbol] The name of the field
     # @param type [Symbol] The data type of the field
     # @param map [String, nil] An optional mapping to another field
-    # @param required [Boolean] Whether the field is required
+    # @param required [Boolean, Array<Symbol>] Whether the field is required
+    # @param nullable [Boolean] Whether the field can be null
     # @param schema_options [Hash] Additional schema options for the field
     # @return [void]
-    def field(name, type: nil, map: nil, required: false, **schema_options)
+    def field(name, type: nil, map: nil, required: nil, nullable: nil, **schema_options)
       camelize(schema_options)
 
       type = default_options.fetch(:type, type)
-      required = default_options.fetch(:required, required)
-      schema_options = default_options.except(:type, :required).merge(schema_options)
+      required = default_options.fetch(:required, false) if required.nil?
+      nullable = default_options.fetch(:nullable, false) if nullable.nil?
+      schema_options = default_options.except(:type, :required, :nullable).merge(schema_options)
 
-      field = Properties::Field.new(name:, type:, map:, required:, **schema_options)
+      field = Properties::Field.new(name:, type:, map:, required:, nullable:, **schema_options)
       current_scope.add(field)
     end
 
@@ -140,20 +142,22 @@ module Verquest
     #
     # @param name [Symbol] The name of the object
     # @param map [String, nil] An optional mapping to another object
-    # @param required [Boolean] Whether the object is required
+    # @param required [Boolean, Array<Symbol>] Whether the object is required
+    # @param nullable [Boolean] Whether the object can be null
     # @param schema_options [Hash] Additional schema options for the object
     # @yield Block executed in the context of the new object definition
     # @return [void]
-    def object(name, map: nil, required: false, **schema_options, &block)
+    def object(name, map: nil, required: nil, nullable: nil, **schema_options, &block)
       unless block_given?
         raise ArgumentError, "a block must be given to define the object"
       end
 
       camelize(schema_options)
-      required = default_options.fetch(:required, required)
-      schema_options = default_options.except(:type, :required).merge(schema_options)
+      required = default_options.fetch(:required, false) if required.nil?
+      nullable = default_options.fetch(:nullable, false) if nullable.nil?
+      schema_options = default_options.except(:type, :required, :nullable).merge(schema_options)
 
-      object = Properties::Object.new(name:, map:, required:, **schema_options)
+      object = Properties::Object.new(name:, map:, required:, nullable:, **schema_options)
       current_scope.add(object)
 
       if block_given?
@@ -170,12 +174,13 @@ module Verquest
     #
     # @param name [Symbol] The name of the collection
     # @param item [Class, nil] The item type in the collection
-    # @param required [Boolean] Whether the collection is required
+    # @param required [Boolean, Array<Symbol>] Whether the collection is required
+    # @param nullable [Boolean] Whether the collection can be null
     # @param map [String, nil] An optional mapping to another collection
     # @param schema_options [Hash] Additional schema options for the collection
     # @yield Block executed in the context of the new collection definition
     # @return [void]
-    def collection(name, item: nil, required: false, map: nil, **schema_options, &block)
+    def collection(name, item: nil, required: nil, nullable: nil, map: nil, **schema_options, &block)
       if item.nil? && !block_given?
         raise ArgumentError, "item must be provided or a block must be given to define the collection"
       elsif !item.nil? && !block_given? && !(item <= Verquest::Base)
@@ -183,10 +188,11 @@ module Verquest
       end
 
       camelize(schema_options)
-      required = default_options.fetch(:required, required)
-      schema_options = default_options.except(:required).merge(schema_options)
+      required = default_options.fetch(:required, false) if required.nil?
+      nullable = default_options.fetch(:nullable, false) if nullable.nil?
+      schema_options = default_options.except(:required, :nullable).merge(schema_options)
 
-      collection = Properties::Collection.new(name:, item:, required:, map:, **schema_options)
+      collection = Properties::Collection.new(name:, item:, required:, nullable:, map:, **schema_options)
       current_scope.add(collection)
 
       if block_given?
@@ -205,31 +211,35 @@ module Verquest
     # @param from [Verquest::Base] The source of the reference
     # @param property [Symbol, nil] An optional specific property to reference
     # @param map [String, nil] An optional mapping to another reference
-    # @param required [Boolean] Whether the reference is required
+    # @param required [Boolean, Array<Symbol>] Whether the reference is required
+    # @param nullable [Boolean] Whether this reference can be null
     # @return [void]
-    def reference(name, from:, property: nil, map: nil, required: false)
-      required = default_options.fetch(:required, required)
+    def reference(name, from:, property: nil, map: nil, required: nil, nullable: nil)
+      required = default_options.fetch(:required, false) if required.nil?
+      nullable = default_options.fetch(:nullable, false) if nullable.nil?
 
-      reference = Properties::Reference.new(name:, from:, property:, map:, required:)
+      reference = Properties::Reference.new(name:, from:, property:, map:, required:, nullable:)
       current_scope.add(reference)
     end
 
     # Defines a new array property for the current version scope
     #
     # @param name [Symbol] The name of the array property
-    # @param type [String] The data type of the array elements
-    # @param required [Boolean] Whether the array property is required
+    # @param type [Symbol] The data type of the array elements
+    # @param required [Boolean, Array<Symbol>] Whether the array property is required
+    # @param nullable [Boolean] Whether this array can be null
     # @param map [String, nil] An optional mapping to another array property
     # @param schema_options [Hash] Additional schema options for the array property
     # @return [void]
-    def array(name, type:, required: false, map: nil, **schema_options)
+    def array(name, type:, required: nil, nullable: nil, map: nil, **schema_options)
       camelize(schema_options)
 
       type = default_options.fetch(:type, type)
-      required = default_options.fetch(:required, required)
-      schema_options = default_options.except(:type, :required).merge(schema_options)
+      required = default_options.fetch(:required, false) if required.nil?
+      nullable = default_options.fetch(:nullable, false) if nullable.nil?
+      schema_options = default_options.except(:type, :required, :nullable).merge(schema_options)
 
-      array = Properties::Array.new(name:, type:, required:, map:, **schema_options)
+      array = Properties::Array.new(name:, type:, required:, nullable:, map:, **schema_options)
       current_scope.add(array)
     end
 

data/lib/verquest/configuration.rb

@@ -52,7 +52,12 @@ module Verquest
     # @!attribute [rw] insert_property_defaults
     #   Controls whether default values defined in property schemas should be inserted when not provided during validation
     #   @return [Boolean] true if default values should be inserted, false otherwise
-    attr_accessor :validate_params, :json_schema_version, :validation_error_handling, :remove_extra_root_keys, :insert_property_defaults
+    #
+    # @!attribute [rw] default_additional_properties
+    #   Controls the default behavior for handling properties not defined in the schema
+    #   @return [Boolean] false to disallow additional properties (default), true to allow them
+    attr_accessor :validate_params, :json_schema_version, :validation_error_handling,
+      :remove_extra_root_keys, :insert_property_defaults, :default_additional_properties
 
     # @!attribute [r] current_version
     #   A callable object that returns the current API version to use when not explicitly specified
@@ -73,11 +78,12 @@ module Verquest
     def initialize
       @validate_params = true
       @json_schema_version = :draft2020_12
-      @validation_error_handling = :raise # or :result
+      @validation_error_handling = :raise
       @remove_extra_root_keys = true
       @version_resolver = VersionResolver
       @insert_property_defaults = true
       @custom_field_types = {}
+      @default_additional_properties = false
     end
 
     # Sets the current version strategy using a callable object

data/lib/verquest/gem_version.rb

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

data/lib/verquest/helper_methods/required_properties.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Verquest
+  # HelperMethods module provides utility methods for Verquest
+  module HelperMethods
+    # Module that provides methods for working with required properties in schemas
+    #
+    # This module offers functionality to identify and categorize properties based on
+    # their required status within schema definitions. It distinguishes between
+    # unconditionally required properties (those marked with `required: true`) and
+    # conditionally required properties (those with dependencies expressed as arrays).
+    #
+    # When included in classes that manage properties (like Version or Base property classes),
+    # it provides methods to extract both types of required properties which can be used
+    # for schema validation, documentation generation, or UI rendering.
+    module RequiredProperties
+      # Returns all properties that are unconditionally required
+      #
+      # This method identifies properties that must always be present in valid data,
+      # 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)
+      def required_properties
+        @_required_properties ||= properties.values.select { _1.required == true }.map(&:name)
+      end
+
+      # Returns properties that are conditionally required based on other properties
+      #
+      # This method identifies properties that are required only when certain other
+      # properties are present. These are properties where the required attribute
+      # is an array of dependency names rather than a boolean.
+      # Results are memoized to avoid recalculating on subsequent calls.
+      #
+      # @return [Hash<String, Array<String>>] Hash mapping property names to their dependency arrays
+      # @example Return value format:
+      #   {
+      #     "property_name1": ["dependency1", "dependency2"],
+      #     "property_name2": ["dependency3"]
+      #   }
+      def dependent_required_properties
+        @_dependent_required_properties ||= properties.values.select { _1.required.is_a?(Array) }.each_with_object({}) do |property, hash|
+          hash[property.name] = property.required.map(&:to_s)
+        end
+      end
+    end
+  end
+end

data/lib/verquest/properties/array.rb

@@ -20,31 +20,39 @@ module Verquest
       # @param name [String, Symbol] The name of the property
       # @param type [String, Symbol] The type of items in the array, can be a default type or a custom field type
       # @param map [String, nil] The mapping path for this property (nil for no explicit mapping)
-      # @param required [Boolean] Whether this property is required
+      # @param required [Boolean, Array<Symbol>] Whether this property is required, or array of dependency names
+      # @param nullable [Boolean] Whether this property can be null
       # @param item_schema_options [Hash] Additional JSON schema options for the array items (merged with custom type options)
       # @param schema_options [Hash] Additional JSON schema options for the array property itself
       # @raise [ArgumentError] If type is not one of the allowed types (default or custom)
       # @raise [ArgumentError] If attempting to map an array to the root
-      def initialize(name:, type:, map: nil, required: false, item_schema_options: {}, **schema_options)
+      def initialize(name:, type:, map: nil, required: false, nullable: false, item_schema_options: {}, **schema_options)
         raise ArgumentError, "Type must be one of #{allowed_types.join(", ")}" unless allowed_types.include?(type.to_s)
         raise ArgumentError, "You can not map array to the root" if map == "/"
 
         if (custom_type = Verquest.configuration.custom_field_types[type.to_sym])
-          @type = custom_type[:type].to_s
+          @item_type = custom_type[:type].to_s
           @item_schema_options = if custom_type.key?(:schema_options)
             custom_type[:schema_options].merge(item_schema_options).transform_keys(&:to_s)
           else
             item_schema_options.transform_keys(&:to_s)
           end
         else
-          @type = type.to_s
+          @item_type = type.to_s
           @item_schema_options = item_schema_options.transform_keys(&:to_s)
         end
 
         @name = name.to_s
         @map = map
         @required = required
+        @nullable = nullable
         @schema_options = schema_options&.transform_keys(&:to_s)
+
+        @type = if nullable
+          %w[array null]
+        else
+          "array"
+        end
       end
 
       # Generate JSON schema definition for this array property
@@ -53,8 +61,8 @@ module Verquest
       def to_schema
         {
           name => {
-            "type" => "array",
-            "items" => {"type" => type}.merge(item_schema_options)
+            "type" => type,
+            "items" => {"type" => item_type}.merge(item_schema_options)
           }.merge(schema_options)
         }
       end
@@ -72,7 +80,7 @@ module Verquest
 
       private
 
-      attr_reader :type, :schema_options, :item_schema_options
+      attr_reader :type, :item_type, :schema_options, :item_schema_options
 
       # Gets the list of allowed item types, including both default and custom types
       #

data/lib/verquest/properties/base.rb

@@ -10,6 +10,8 @@ module Verquest
     #
     # @abstract Subclass and override {#to_schema}, {#mapping} to implement
     class Base
+      include HelperMethods::RequiredProperties
+
       # @!attribute [rw] name
       #   @return [String] The name of the property
       # @!attribute [rw] required
@@ -55,6 +57,10 @@ module Verquest
 
       private
 
+      # @!attribute [r] nullable
+      #   @return [Boolean] Whether this property can be null
+      attr_reader :nullable
+
       # 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

@@ -22,11 +22,12 @@ module Verquest
       #
       # @param name [String, Symbol] The name of the property
       # @param item [Verquest::Base, nil] Optional reference to an external schema class
-      # @param required [Boolean] Whether this property is required
+      # @param required [Boolean, Array<Symbol>] Whether this property is required, or array of dependency names
+      # @param nullable [Boolean] Whether this property can be null
       # @param map [String, nil] The mapping path for this property
       # @param schema_options [Hash] Additional JSON schema options for this property
       # @raise [ArgumentError] If attempting to map a collection to the root
-      def initialize(name:, item: nil, required: false, map: nil, **schema_options)
+      def initialize(name:, item: nil, required: false, nullable: false, map: nil, **schema_options)
         raise ArgumentError, "You can not map collection to the root" if map == "/"
 
         @properties = {}
@@ -34,8 +35,15 @@ module Verquest
         @name = name.to_s
         @item = item
         @required = required
+        @nullable = nullable
         @map = map
         @schema_options = schema_options&.transform_keys(&:to_s)
+
+        @type = if nullable
+          %w[array null]
+        else
+          "array"
+        end
       end
 
       # Add a child property to this collection's item definition
@@ -60,7 +68,7 @@ module Verquest
         if has_item?
           {
             name => {
-              "type" => "array",
+              "type" => type,
               "items" => {
                 "$ref" => item.to_ref
               }
@@ -69,12 +77,15 @@ module Verquest
         else
           {
             name => {
-              "type" => "array",
+              "type" => type,
               "items" => {
                 "type" => "object",
-                "required" => properties.values.select(&:required).map(&:name),
-                "properties" => properties.transform_values { |property| property.to_schema[property.name] }
-              }
+                "required" => required_properties,
+                "properties" => properties.transform_values { |property| property.to_schema[property.name] },
+                "additionalProperties" => Verquest.configuration.default_additional_properties
+              }.tap do |schema|
+                schema["dependentRequired"] = dependent_required_properties if dependent_required_properties.any?
+              end
             }.merge(schema_options)
           }
         end
@@ -88,19 +99,22 @@ module Verquest
         if has_item?
           {
             name => {
-              "type" => "array",
+              "type" => type,
               "items" => item.to_validation_schema(version: version)
             }.merge(schema_options)
           }
         else
           {
             name => {
-              "type" => "array",
+              "type" => type,
               "items" => {
                 "type" => "object",
-                "required" => properties.values.select(&:required).map(&:name),
-                "properties" => properties.transform_values { |property| property.to_validation_schema(version: version)[property.name] }
-              }
+                "required" => required_properties,
+                "properties" => properties.transform_values { |property| property.to_validation_schema(version: version)[property.name] },
+                "additionalProperties" => Verquest.configuration.default_additional_properties
+              }.tap do |schema|
+                schema["dependentRequired"] = dependent_required_properties if dependent_required_properties.any?
+              end
             }.merge(schema_options)
           }
         end
@@ -141,7 +155,7 @@ module Verquest
 
       private
 
-      attr_reader :item, :schema_options, :properties
+      attr_reader :item, :schema_options, :properties, :type
     end
   end
 end

data/lib/verquest/properties/field.rb

@@ -24,12 +24,13 @@ module Verquest
       #
       # @param name [String, Symbol] The name of the property
       # @param type [String, Symbol] The data type for this field, can be a default type or a custom field type
-      # @param required [Boolean] Whether this property is required (overridden by custom type if it defines required)
+      # @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 map [String, nil] The mapping path for this property
       # @param schema_options [Hash] Additional JSON schema options for this property (merged with custom type options)
       # @raise [ArgumentError] If type is not one of the allowed types (default or custom)
       # @raise [ArgumentError] If attempting to map a field to root without a name
-      def initialize(name:, type:, required: false, map: nil, **schema_options)
+      def initialize(name:, type:, required: false, nullable: false, map: nil, **schema_options)
         raise ArgumentError, "Type must be one of #{allowed_types.join(", ")}" unless allowed_types.include?(type.to_s)
         raise ArgumentError, "You can not map fields to the root without a name" if map == "/"
 
@@ -48,14 +49,21 @@ module Verquest
         end
 
         @name = name.to_s
+        @nullable = nullable
         @map = map
+
+        if nullable
+          @type = [@type, "null"]
+        end
       end
 
       # Generate JSON schema definition for this field
       #
       # @return [Hash] The schema definition for this field
       def to_schema
-        {name => {"type" => type}.merge(schema_options)}
+        {
+          name => {"type" => type}.merge(schema_options)
+        }
       end
 
       # Create mapping for this field property

data/lib/verquest/properties/object.rb

@@ -15,16 +15,28 @@ module Verquest
       # Initialize a new Object property
       #
       # @param name [String, Symbol] The name of the property
-      # @param required [Boolean] Whether this property is required
+      # @param required [Boolean, Array<Symbol>] Whether this property is required, or array of dependency names
+      # @param nullable [Boolean] Whether this property can be null
       # @param map [String, nil] The mapping path for this property
       # @param schema_options [Hash] Additional JSON schema options for this property
-      def initialize(name:, required: false, map: nil, **schema_options)
+      def initialize(name:, required: false, nullable: false, map: nil, **schema_options)
         @properties = {}
 
         @name = name.to_s
         @required = required
+        @nullable = nullable
         @map = map
-        @schema_options = schema_options&.transform_keys(&:to_s)
+        @schema_options = {
+          additionalProperties: Verquest.configuration.default_additional_properties
+        }.merge(schema_options)
+          .delete_if { |_, v| v.nil? }
+          .transform_keys(&:to_s)
+
+        @type = if nullable
+          %w[object null]
+        else
+          "object"
+        end
       end
 
       # Add a child property to this object
@@ -41,10 +53,12 @@ module Verquest
       def to_schema
         {
           name => {
-            "type" => "object",
-            "required" => properties.values.select(&:required).map(&:name),
+            "type" => type,
+            "required" => required_properties,
             "properties" => properties.transform_values { |property| property.to_schema[property.name] }
-          }.merge(schema_options)
+          }.merge(schema_options).tap do |schema|
+            schema["dependentRequired"] = dependent_required_properties if dependent_required_properties.any?
+          end
         }
       end
 
@@ -55,10 +69,12 @@ module Verquest
       def to_validation_schema(version: nil)
         {
           name => {
-            "type" => "object",
-            "required" => properties.values.select(&:required).map(&:name),
+            "type" => type,
+            "required" => required_properties,
             "properties" => properties.transform_values { |property| property.to_validation_schema(version: version)[property.name] }
-          }.merge(schema_options)
+          }.merge(schema_options).tap do |schema|
+            schema["dependentRequired"] = dependent_required_properties if dependent_required_properties.any?
+          end
         }
       end
 

data/lib/verquest/properties/reference.rb

@@ -26,12 +26,14 @@ module Verquest
       # @param name [String, Symbol] The name of the property
       # @param from [Class] The schema class to reference
       # @param property [Symbol, nil] Optional specific property to reference
+      # @param nullable [Boolean] Whether this property can be null
       # @param map [String, nil] The mapping path for this property
-      # @param required [Boolean] Whether this property is required
-      def initialize(name:, from:, property: nil, map: nil, required: false)
+      # @param required [Boolean, Array<Symbol>] Whether this property is required, or array of dependency names
+      def initialize(name:, from:, property: nil, nullable: false, map: nil, required: false)
         @name = name.to_s
         @from = from
         @property = property
+        @nullable = nullable
         @map = map
         @required = required
       end
@@ -40,9 +42,20 @@ module Verquest
       #
       # @return [Hash] The schema definition with a $ref pointer
       def to_schema
-        {
-          name => {"$ref" => from.to_ref(property: property)}
-        }
+        if nullable
+          {
+            name => {
+              "oneOf" => [
+                {"$ref" => from.to_ref(property: property)},
+                {"type" => "null"}
+              ]
+            }
+          }
+        else
+          {
+            name => {"$ref" => from.to_ref(property: property)}
+          }
+        end
       end
 
       # Generate validation schema for this reference property
@@ -50,8 +63,14 @@ module Verquest
       # @param version [String, nil] The version to generate validation schema for
       # @return [Hash] The validation schema for this reference
       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 => from.to_validation_schema(version:, property: property)
+          name => schema
         }
       end
 

data/lib/verquest/version.rb

@@ -19,6 +19,8 @@ module Verquest
   #   # Get mapping
   #   mapping = version.mapping
   class Version
+    include HelperMethods::RequiredProperties
+
     # @!attribute [r] name
     #   @return [String] The name/identifier of the version (e.g., "2023-01")
     #
@@ -102,6 +104,12 @@ module Verquest
     def prepare
       return if frozen?
 
+      unless schema_options.key?("additionalProperties")
+        schema_options["additionalProperties"] = Verquest.configuration.default_additional_properties
+      end
+
+      schema_options.delete_if { |_, v| v.nil? }
+
       prepare_schema
       prepare_validation_schema
       prepare_mapping
@@ -197,9 +205,11 @@ module Verquest
       @schema = {
         "type" => "object",
         "description" => description,
-        "required" => properties.values.select(&:required).map(&:name),
+        "required" => required_properties,
         "properties" => properties.transform_values { |property| property.to_schema[property.name] }
-      }.merge(schema_options).freeze
+      }.merge(schema_options).tap do |schema|
+        schema["dependentRequired"] = dependent_required_properties if dependent_required_properties.any?
+      end.freeze
     end
 
     # Generates the validation schema for this version
@@ -212,9 +222,11 @@ module Verquest
       @validation_schema = {
         "type" => "object",
         "description" => description,
-        "required" => properties.values.select(&:required).map(&:name),
+        "required" => required_properties,
         "properties" => properties.transform_values { |property| property.to_validation_schema(version: name)[property.name] }
-      }.merge(schema_options).freeze
+      }.merge(schema_options).tap do |schema|
+        schema["dependentRequired"] = dependent_required_properties if dependent_required_properties.any?
+      end.freeze
     end
 
     # Prepares the parameter mapping for this version

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: verquest
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Petr Hlavicka
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-06-28 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: zeitwerk
@@ -62,6 +61,7 @@ files:
 - lib/verquest/base/public_class_methods.rb
 - lib/verquest/configuration.rb
 - lib/verquest/gem_version.rb
+- lib/verquest/helper_methods/required_properties.rb
 - lib/verquest/properties.rb
 - lib/verquest/properties/array.rb
 - lib/verquest/properties/base.rb
@@ -81,7 +81,6 @@ metadata:
   homepage_uri: https://github.com/CiTroNaK/verquest
   source_code_uri: https://github.com/CiTroNaK/verquest
   changelog_uri: https://github.com/CiTroNaK/verquest/blob/main/CHANGELOG.md
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -96,8 +95,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Verquest is a Ruby gem that offers an elegant solution for versioning API
   requests