verquest 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0ccc6bfd2d16a987d2ed8ae6c04a9fbfd72a0ed58f00699221193ef76e764cd0
-  data.tar.gz: '0026964f349c5d17f41b18cd7f32431519c46f1530fe92a535488abcd202a86e'
+  metadata.gz: b9349b2773c4a03024805d78257b1e763ffb87b87f27726620e343395c683aa0
+  data.tar.gz: ec2b70a4a10c3314ca27283776138f85b53b245d88869de39e450ca2eb2064de
 SHA512:
-  metadata.gz: dba0dc768c80d2f51cfb74a9c93483218c8d3f28fffffe01b41d250e78f0d2e504ba64af6ea2dd723de22640170b2151f860424bcdc5ad05b29d24fa694a5081
-  data.tar.gz: 662c43fb095decd144c50afece842467ff96705bbe4a51f27a347a2fdf6041a0bc98895274f280a1441ca88f445a1820d519fc280f9304bc26826f44ea9fcb23
+  metadata.gz: 0d0042f959285f4253c7802166ab64d53b7013d765bfe954fd68a8ab46bb59f162512a285aca11c77e86a8e6b5ce36445f47e4e9530fcaa0010e8c6cadcefdf2
+  data.tar.gz: 06bbfceb1c989e1e3eabb20e495790ac35934e1cb4687e71960315c3e64d3a30b42b345c03d19d32be921b75550a6fef002d8ba44018ded8f7c9a3af73d920f0

data/CHANGELOG.md

@@ -1,5 +1,28 @@
 ## [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.
+
+### New Features
+- Add support for custom field types.
+
+### Fixed
+- Loading the gem in another project with `zeitwerk` now works correctly.
+- Fix schema validation after `json_schemer` refactoring.
+
 ## [0.3.0] - 2025-06-25
 
 ### Breaking Changes

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.2"
+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",
@@ -174,7 +174,8 @@ Output:
       }
     }
   },
-  "additionalProperties" => false}
+  "additionalProperties" => false
+}
 ```
 
 ### JSON schema for validation
@@ -249,7 +250,8 @@ Output:
 You can also validate it to ensure it meets the JSON Schema standards:
 
 ```ruby
-UserCreateRequest.validate_schema(version: "2025-06") # => true/false
+UserCreateRequest.valid_schema?(version: "2025-06") # => true/false
+UserCreateRequest.validate_schema(version: "2025-06") # => Array of errors or empty array if valid
 ```
 
 ## Core Features
@@ -274,6 +276,156 @@ 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.
+
+```ruby
+Verquest.configure do |config|
+  config.custom_field_types = {
+    email: {
+      type: "string",
+      schema_options: {format: "email"}
+    },
+    uuid: {
+      type: "string",
+      schema_options: {format: "uuid"}
+    }
+  }
+end
+```
+
+Then you can use it in your request:
+```ruby
+class EmailRequest < Verquest::Base
+  description "User Create Request"
+  schema_options additional_properties: false
+
+  version "2025-06" do
+    field :email, type: :email
+    array :uuids, type: :uuid
+  end
+end
+```
+
+`EmailRequest.to_schema(version: "2025-06")` will then generate the following JSON Schema:
+```ruby
+{
+  "type" => "object",
+  "description" => "User Create Request",
+  "required" => ["email"],
+  "properties" => {
+    "email" => {
+      "type" => "string", 
+      "format" => "email"
+    },
+    "uuids" => {
+      "type" => "array", 
+      "items" => {
+        "type" => "string",
+        "format" => "uuid"
+      }
+    }
+  },
+  "additionalProperties" => false
+}
+```
+
 ### Versioning
 
 Verquest allows you to define multiple versions of your API requests, making it easy to evolve your API over time:
@@ -416,7 +568,7 @@ Verquest.configure do |config|
   config.current_version = -> { Current.api_version }
   
   # Set the JSON Schema version
-  config.json_schema_version = :draft6 # default
+  config.json_schema_version = :draft2020_12 # default
   
   # Set the error handling strategy for processing params
   config.validation_error_handling = :raise # default, can be set also to :result
@@ -426,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).
+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/base/public_class_methods.rb

@@ -70,6 +70,19 @@ module Verquest
     #
     # @param version [String, nil] Specific version to use, defaults to configuration setting
     # @return [Boolean] True if schema is valid
+    def valid_schema?(version: nil)
+      resolve(version).valid_schema?
+    end
+
+    # Validates the schema against the metaschema and returns detailed validation errors
+    #
+    # This method validates the schema against the configured JSON Schema metaschema
+    # and returns detailed validation errors if any are found. It's useful for debugging
+    # schema issues during development and testing.
+    #
+    # @param version [String, nil] Specific version to use, defaults to configuration setting
+    # @return [Array<Hash>] An array of validation error details, empty if schema is valid
+    # @see #valid_schema?
     def validate_schema(version: nil)
       resolve(version).validate_schema
     end

data/lib/verquest/configuration.rb

@@ -11,6 +11,18 @@ module Verquest
   #     config.current_version = -> { Current.api_version }
   #   end
   class Configuration
+    include Base::HelperClassMethods
+
+    # Mapping of supported JSON Schema versions to their implementation classes
+    #
+    # This constant maps the symbolic names of JSON Schema versions to their
+    # corresponding JSONSchemer implementation classes. These are used for schema
+    # validation and generation based on the configured schema version.
+    #
+    # @example Accessing a schema implementation
+    #   schema_class = Verquest::Configuration::SCHEMAS[:draft2020_12]
+    #
+    # @return [Hash<Symbol, Class>] A frozen hash mapping schema version names to implementation classes
     SCHEMAS = {
       draft4: JSONSchemer::Draft4,
       draft6: JSONSchemer::Draft6,
@@ -40,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
@@ -49,7 +66,11 @@ module Verquest
     # @!attribute [r] version_resolver
     #   The resolver used to map version strings/identifiers to version objects
     #   @return [#call] An object that responds to `call` for resolving versions
-    attr_reader :current_version, :version_resolver
+    #
+    # @!attribute [r] custom_field_types
+    #   Custom field types to extend the standard set of field types
+    #   @return [Hash<Symbol, Hash>] Hash mapping field type names to their configuration
+    attr_reader :current_version, :version_resolver, :custom_field_types
 
     # Initialize a new Configuration with default values
     #
@@ -57,10 +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
@@ -85,6 +108,39 @@ module Verquest
       @version_resolver = version_resolver
     end
 
+    # Sets the custom field types
+    #
+    # This method allows defining custom field types beyond the default ones.
+    # Custom field types can be used to extend validation with specific formats
+    # or patterns. Each custom field type should include a base type and optional
+    # schema validation options.
+    #
+    # @example Adding a phone number field type
+    #   config.custom_field_types = {
+    #     email: {
+    #       type: "string",
+    #       schema_options: {format: "email", pattern: /\A[^@\s]+@[^@.\s]+(\.[^@.\s]+)+\z/}
+    #     },
+    #     uuid: {
+    #       type: "string",
+    #       schema_options: {format: "uuid", pattern: /[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}/}
+    #     }
+    #   }
+    #
+    # @param custom_field_types [Hash] A hash mapping field type names to their configuration
+    # @raise [ArgumentError] If the provided value isn't a Hash
+    # @return [Hash<Symbol, Hash>] The processed custom field types hash with symbolized keys
+    def custom_field_types=(custom_field_types)
+      raise ArgumentError, "Custom field types must be a Hash" unless custom_field_types.is_a?(Hash)
+
+      custom_field_types.delete_if { |k, _| Properties::Field::DEFAULT_TYPES.include?(k.to_s) }
+      custom_field_types.each do |_, value|
+        value[:schema_options] = camelize(value[:schema_options]) if value[:schema_options]
+      end
+
+      @custom_field_types = custom_field_types.transform_keys(&:to_sym)
+    end
+
     # Gets the JSON Schema class based on the configured version
     #
     # @return [Class] The JSON Schema class matching the configured version

data/lib/verquest/gem_version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Verquest
-  GEM_VERSION = "0.3.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

@@ -6,6 +6,7 @@ module Verquest
     #
     # Represents an array data structure in the schema with specified item type.
     # Used to define arrays of scalar types (string, number, integer, boolean).
+    # Supports both default item types and custom field types defined in the configuration.
     #
     # @example Define an array of strings
     #   array = Verquest::Properties::Array.new(
@@ -17,19 +18,41 @@ module Verquest
       # Initialize a new Array property
       #
       # @param name [String, Symbol] The name of the property
-      # @param type [String, Symbol] The type of items in the array
+      # @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 schema_options [Hash] Additional JSON schema options for this property
+      # @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, **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])
+          @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
+          @item_type = type.to_s
+          @item_schema_options = item_schema_options.transform_keys(&:to_s)
+        end
+
         @name = name.to_s
-        @type = type.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
@@ -38,8 +61,8 @@ module Verquest
       def to_schema
         {
           name => {
-            "type" => "array",
-            "items" => {"type" => type}
+            "type" => type,
+            "items" => {"type" => item_type}.merge(item_schema_options)
           }.merge(schema_options)
         }
       end
@@ -57,7 +80,14 @@ module Verquest
 
       private
 
-      attr_reader :type, :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
+      #
+      # @return [Array<String>] Array of allowed item type names
+      def allowed_types
+        Verquest::Properties::Field::DEFAULT_TYPES + Verquest.configuration.custom_field_types.keys.map(&:to_s)
+      end
     end
   end
 end

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

@@ -6,6 +6,7 @@ module Verquest
     #
     # Represents simple scalar types (string, number, integer, boolean) in the schema.
     # Used for defining basic data fields without nesting.
+    # Supports both default types and custom field types defined in the configuration.
     #
     # @example Define a required string field
     #   field = Verquest::Properties::Field.new(
@@ -15,35 +16,54 @@ module Verquest
     #     format: "email"
     #   )
     class Field < Base
-      # List of allowed field types
+      # List of default field types
       # @return [Array<Symbol>]
-      ALLOWED_TYPES = %w[string number integer boolean].freeze
+      DEFAULT_TYPES = %w[string number integer boolean].freeze
 
       # Initialize a new Field property
       #
       # @param name [String, Symbol] The name of the property
-      # @param type [String, Symbol] The data type for this field, must be one of ALLOWED_TYPES
-      # @param required [Boolean] Whether this property is required
+      # @param type [String, Symbol] The data type for this field, can be a default type or a custom field type
+      # @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
-      # @raise [ArgumentError] If type is not one of the allowed types
+      # @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)
-        raise ArgumentError, "Type must be one of #{ALLOWED_TYPES.join(", ")}" unless ALLOWED_TYPES.include?(type.to_s)
+      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 == "/"
 
+        if (custom_type = Verquest.configuration.custom_field_types[type.to_sym])
+          @type = custom_type[:type].to_s
+          @required = custom_type.key?(:required) ? custom_type[:required] : required
+          @schema_options = if custom_type.key?(:schema_options)
+            custom_type[:schema_options].merge(schema_options).transform_keys(&:to_s)
+          else
+            schema_options.transform_keys(&:to_s)
+          end
+        else
+          @type = type.to_s
+          @required = required
+          @schema_options = schema_options&.transform_keys(&:to_s)
+        end
+
         @name = name.to_s
-        @type = type.to_s
-        @required = required
+        @nullable = nullable
         @map = map
-        @schema_options = schema_options&.transform_keys(&:to_s)
+
+        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
@@ -60,6 +80,13 @@ module Verquest
       private
 
       attr_reader :type, :schema_options
+
+      # Gets the list of allowed field types, including both default and custom types
+      #
+      # @return [Array<String>] Array of allowed field type names
+      def allowed_types
+        DEFAULT_TYPES + Verquest.configuration.custom_field_types.keys.map(&:to_s)
+      end
     end
   end
 end

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
@@ -113,11 +121,33 @@ module Verquest
     # Validate the schema against the metaschema
     #
     # @return [Boolean] true if the schema is valid, false otherwise
+    def valid_schema?
+      JSONSchemer.valid_schema?(
+        validation_schema,
+        meta_schema: Verquest.configuration.json_schema_uri
+      )
+    end
+
+    # Validate the schema against the metaschema and return detailed errors
+    #
+    # This method validates the schema against the configured JSON Schema metaschema
+    # and returns detailed validation errors if any are found. It uses the JSONSchemer
+    # library with the schema version specified in the configuration.
+    #
+    # @return [Array<Hash>] An array of validation error details, empty if schema is valid
+    # @see #valid_schema?
     def validate_schema
       JSONSchemer.validate_schema(
         validation_schema,
         meta_schema: Verquest.configuration.json_schema_uri
-      )
+      ).map do |error|
+        {
+          pointer: error["data_pointer"],
+          type: error["type"],
+          message: error["error"],
+          details: error["details"]
+        }
+      end
     end
 
     # Validate request parameters against the version's validation schema
@@ -175,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
@@ -190,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

data/lib/verquest.rb

@@ -3,8 +3,11 @@
 require "zeitwerk"
 require "json_schemer"
 
+require_relative "verquest/gem_version"
+
 loader = Zeitwerk::Loader.new
 loader.tag = File.basename(__FILE__, ".rb")
+loader.ignore("#{File.dirname(__FILE__)}/verquest/gem_version.rb")
 loader.push_dir(File.dirname(__FILE__))
 loader.setup
 

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: verquest
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Petr Hlavicka
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-06-25 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