verquest 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 725838444df6f3861ab842c88b430aa7bbc81023637595b4a0a8a909df5a2fbe
-  data.tar.gz: 88041a5f8bc888f90894975b5fb371ac8184877bb75b74e2e099ce57997b331a
+  metadata.gz: 92e6047d9812ae82cf55b5d0512c459a61306c7b2cc78c9cd224e2b52b4b716c
+  data.tar.gz: db8943d346e30972f3b6b516d9365d7ef37dedf89fa7f4a09c5db4cb1adbe545
 SHA512:
-  metadata.gz: 3991e8ff96b436e82a6edce43d591f35f669cbab9ef99b01bc26192bef94e3f48afe59595d8ae5d3d605bd96c0150bfdb557e555f1d20e79d74cbe4343d99c49
-  data.tar.gz: dcc10eeadec0f32073569db402893bb3f1ab5629da79eee32d605c476bbcf05f637f5b348f83478863bf7d28fc1d0b3d2cd9b54c38f356f3bfa53d51d3ac50bb
+  metadata.gz: 0163416a3ea0f4d5cb5619b74e31ca7f2999ddccba55091d8fa8f10244a36eeb59dadd1b6d9eae6bd22d1f49e5ea7213aeb42218731f248be69d54c2127bb216
+  data.tar.gz: ee7adc256954aafa194a3175f50649479a8f45292d8bed51cf076f17c1d0693fbe7099e64675d249448c1e66cb9b1dce4749da71e76f36fc2d976b7387f23382

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 ## [Unreleased]
 
+## [0.6.0] - 2025-07-18
+
+### Breaking Changes
+- **BREAKING:** Switching to slash notation for mapping to improve consistency with how properties are referenced in JSON Schema. Before: `example.nested.property`, now: `example/nested/property`. ([#12](https://github.com/CiTroNaK/verquest/pull/12), [@CiTroNaK](https://github.com/CiTroNaK))
+
+### New Features
+- Add support for `enum` properties. ([#13](https://github.com/CiTroNaK/verquest/pull/13), [@CiTroNaK](https://github.com/CiTroNaK))
+- Add support for inverted mapping, that can be used to map internal structure to external representation (e.g., for errors). ([#10](https://github.com/CiTroNaK/verquest/pull/10), [@CiTroNaK](https://github.com/CiTroNaK))
+- Add support for constants in the schema, allowing to define fixed values for properties. ([#11](https://github.com/CiTroNaK/verquest/pull/11), [@CiTroNaK](https://github.com/CiTroNaK))
+
+## [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

@@ -8,18 +8,18 @@ Verquest is a Ruby gem that offers an elegant solution for versioning API reques
 - Defining versioned request structures
 - Gracefully handling API versioning
 - Mapping between external and internal parameter structures
-- Validating parameters against [JSON Schema](https://json-schema.org/learn)
+- Validating parameters against [JSON Schema](https://json-schema.org/)
 - Generating components for OpenAPI documentation
-- Mapping error keys back to the external API structure (planned feature)
+- Mapping error keys back to the external API structure
 
-> The gem is still in development. Until version 1.0, the API may change. There are some features like `oneOf`, `anyOf`, `allOf` that are not implemented yet.
+> The gem is still in development. Until version 1.0, the API may change. There are some features like `oneOf`, `anyOf`, `allOf` that are not implemented yet. See open [issues](https://github.com/CiTroNaK/verquest/issues?q=sort:updated-desc%20is:issue%20is:open%20label:enhancement).
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem "verquest", "~> 0.3"
+gem "verquest", "~> 0.6"
 ```
 
 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
 
@@ -75,7 +75,7 @@ class UserCreateRequest < Verquest::Base
       end
     end
     
-    field :role, type: :string, description: "Role of the user", enum: %w[member manager], default: "member"
+    enum :role, values: %w[member manager], default: "member", description: "Role of the user", required: true
     
     object :profile_details do
       field :bio, type: :string, description: "Short biography of the user"
@@ -89,6 +89,8 @@ class UserCreateRequest < Verquest::Base
         end
       end
     end
+    
+    const :company, value: "Awesome Inc."
   end
 end
 ```
@@ -130,12 +132,12 @@ Output:
 {
   "type" => "object",
   "description" => "User Create Request",
-  "required" => ["first_name", "last_name", "email", "address"],
+  "required" => ["first_name", "last_name", "email", "address", "role"],
   "properties" => {
     "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",
@@ -151,10 +153,9 @@ Output:
       "description" => "Permissions associated with the user"
     },
     "role" => {
-      "type" => "string",
-      "description" => "Role of the user",
-      "enum" => ["member", "manager"],
-      "default" => "member"
+      "enum" => ["member", "manager"], 
+      "default" => "member", 
+      "description" => "Role of the user"
     },
     "profile_details" => {
       "type" => "object",
@@ -172,7 +173,8 @@ Output:
           "description" => "Some social networks"
         }
       }
-    }
+    },
+    "company" => {"const" => "Awesome Inc."}
   },
   "additionalProperties" => false
 }
@@ -191,7 +193,7 @@ Output:
 {
   "type" => "object",
   "description" => "User Create Request",
-  "required" => ["first_name", "last_name", "email", "address"],
+  "required" => ["first_name", "last_name", "email", "address", "role"],
   "properties" => {
     "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},
@@ -222,10 +224,9 @@ Output:
       "description" => "Permissions associated with the user"
     },
     "role" => {
-      "type" => "string",
-      "description" => "Role of the user",
       "enum" => ["member", "manager"],
-      "default" => "member"
+      "default" => "member",
+      "description" => "Role of the user"
     },
     "profile_details" => {"type" => "object",
       "required" => [],
@@ -240,7 +241,8 @@ Output:
             "mastodon" => {"type" => "string", "format" => "uri", "description" => "Mastodon profile URL"}
           }, 
           "description" => "Some social networks"}
-      }
+      },
+      "company" => {"const" => "Awesome Inc."}
     }
   },
   "additionalProperties" => false
@@ -265,10 +267,12 @@ The JSON schema can be used for both validation of incoming parameters and for g
 #### Component types
 
 - `field`: Represents a scalar value (string, integer, boolean, etc.).
+- `enum`: Represents a property with a limited set of values (enumeration).
 - `object`: Represents a JSON object with properties.
 - `array`: Represents a JSON array with scalar items.
 - `collection`: Represents a array of objects defined manually or by a reference to another request.
 - `reference`: Represents a reference to another request, allowing you to reuse existing request structures.
+- `const`: Represents a [constant](https://json-schema.org/understanding-json-schema/reference/const#constant-values) value that is always present in the request.
 
 #### Helper methods
 
@@ -276,6 +280,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.
@@ -443,9 +542,28 @@ Will be transformed to:
 
 What you can use:
 - `/` to reference the root of the request structure
-- `nested.structure` use dot notation to reference nested structures
+- `nested/structure` use slash notation to reference nested structures
 - if the `map` is not set, the field name will be used as the key in the internal structure
 
+To get the mapping to map the request structure back to the external API structure, you can use the `external_mapping` method:
+
+```ruby
+UserCreateRequest.external_mapping(version: "2025-06")
+```
+
+Will produce the following mapping:
+
+```ruby
+{
+  "name" => "full_name",
+  "email" => "email",
+  "phone" => "phone",
+  "address_street" => "address/street",
+  "address_city" => "address/city",
+  "address_zip" => "address/postal_code"
+}
+```
+
 There are some limitations and the implementation can be improved, but it should works for most common use cases.
 
 See the mapping test (in `test/verquest/base_test.rb`) for more examples of mapping.
@@ -483,12 +601,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.6.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,38 +122,78 @@ 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
 
+    # Defines a new enum property for the current version scope
+    #
+    # @param name [Symbol] The name of the enum
+    # @param values [Array] The possible values for the enum
+    # @param map [String, nil] An optional mapping to another property
+    # @param required [Boolean, Array<Symbol>] Whether the enum is required
+    # @param nullable [Boolean] Whether the enum can be null
+    # @param schema_options [Hash] Additional schema options for the enum
+    # @return [void]
+    def enum(name, values:, 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?
+      schema_options = default_options.except(:required, :nullable).merge(schema_options)
+
+      enum_property = Properties::Enum.new(name:, values:, map:, required:, nullable:, **schema_options)
+      current_scope.add(enum_property)
+    end
+
+    # Defines a new constant property for the current version scope
+    #
+    # @param name [Symbol] The name of the constant
+    # @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 schema_options [Hash] Additional schema options for the constant
+    # @return [void]
+    def const(name, value:, map: nil, required: nil, **schema_options)
+      camelize(schema_options)
+      required = default_options.fetch(:required, false) if required.nil?
+
+      const = Properties::Const.new(name:, value:, map:, required:, **schema_options)
+      current_scope.add(const)
+    end
+
     # Defines a new object for the current version scope
     #
     # @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 +210,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 +224,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 +247,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

@@ -102,6 +102,18 @@ module Verquest
       end
     end
 
+    # Returns the external mapping for a specific version
+    #
+    # This method returns a mapping hash that translates from internal attribute names back to external parameter names.
+    #
+    # @param version [String, nil] Specific version to use, defaults to configuration setting
+    # @return [Hash] The inverted mapping configuration where keys are internal names and values are external names
+    # @see #mapping
+    def external_mapping(version: nil)
+      version = resolve(version)
+      version.external_mapping
+    end
+
     # Returns the JSON reference for the request or a specific property
     #
     # @param property [String, Symbol, nil] Specific property to retrieve reference for

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.6.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