verquest 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0ccc6bfd2d16a987d2ed8ae6c04a9fbfd72a0ed58f00699221193ef76e764cd0
-  data.tar.gz: '0026964f349c5d17f41b18cd7f32431519c46f1530fe92a535488abcd202a86e'
+  metadata.gz: 725838444df6f3861ab842c88b430aa7bbc81023637595b4a0a8a909df5a2fbe
+  data.tar.gz: 88041a5f8bc888f90894975b5fb371ac8184877bb75b74e2e099ce57997b331a
 SHA512:
-  metadata.gz: dba0dc768c80d2f51cfb74a9c93483218c8d3f28fffffe01b41d250e78f0d2e504ba64af6ea2dd723de22640170b2151f860424bcdc5ad05b29d24fa694a5081
-  data.tar.gz: 662c43fb095decd144c50afece842467ff96705bbe4a51f27a347a2fdf6041a0bc98895274f280a1441ca88f445a1820d519fc280f9304bc26826f44ea9fcb23
+  metadata.gz: 3991e8ff96b436e82a6edce43d591f35f669cbab9ef99b01bc26192bef94e3f48afe59595d8ae5d3d605bd96c0150bfdb557e555f1d20e79d74cbe4343d99c49
+  data.tar.gz: dcc10eeadec0f32073569db402893bb3f1ab5629da79eee32d605c476bbcf05f637f5b348f83478863bf7d28fc1d0b3d2cd9b54c38f356f3bfa53d51d3ac50bb

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 ## [Unreleased]
 
+### 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.3"
 ```
 
 And then execute:
@@ -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,61 @@ 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.
 
+#### 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 +473,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
@@ -431,7 +488,7 @@ 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.4.0/).
 
 ## Development
 

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,
@@ -49,7 +61,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
     #
@@ -61,6 +77,7 @@ module Verquest
       @remove_extra_root_keys = true
       @version_resolver = VersionResolver
       @insert_property_defaults = true
+      @custom_field_types = {}
     end
 
     # Sets the current version strategy using a callable object
@@ -85,6 +102,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.4.0"
 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,16 +18,30 @@ 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 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, 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_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_schema_options = item_schema_options.transform_keys(&:to_s)
+        end
+
         @name = name.to_s
-        @type = type.to_s
         @map = map
         @required = required
         @schema_options = schema_options&.transform_keys(&:to_s)
@@ -39,7 +54,7 @@ module Verquest
         {
           name => {
             "type" => "array",
-            "items" => {"type" => type}
+            "items" => {"type" => type}.merge(item_schema_options)
           }.merge(schema_options)
         }
       end
@@ -57,7 +72,14 @@ module Verquest
 
       private
 
-      attr_reader :type, :schema_options
+      attr_reader :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/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,28 +16,39 @@ 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] Whether this property is required (overridden by custom type if it defines required)
       # @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)
+        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
         @map = map
-        @schema_options = schema_options&.transform_keys(&:to_s)
       end
 
       # Generate JSON schema definition for this field
@@ -60,6 +72,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/version.rb

@@ -113,11 +113,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

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,14 @@
 --- !ruby/object:Gem::Specification
 name: verquest
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Petr Hlavicka
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-06-25 00:00:00.000000000 Z
+date: 2025-06-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: zeitwerk