verquest 0.2.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3937cd4b94f0a041133b0f36400e377afade0d8cc3c15bbc4b4f8ef601b8cf91
-  data.tar.gz: c8e2ae6eea78d6840cc23c6ee461322fe2a7e79292e8c4cacf7ad0153a9bf215
+  metadata.gz: 725838444df6f3861ab842c88b430aa7bbc81023637595b4a0a8a909df5a2fbe
+  data.tar.gz: 88041a5f8bc888f90894975b5fb371ac8184877bb75b74e2e099ce57997b331a
 SHA512:
-  metadata.gz: c7f9d528de6b8b0f7344ed02b52873a99c2a432a6c1d058e2fd25633bdc192c8ab68cd074e561add9567146b427a40256ba43bada339065b8138b9be8f02c9c4
-  data.tar.gz: d94a551e3ba5804711630c54a33bd2717c711c8792565dfdaacdcfad902ca446a21a96d50fe03487fef7c4109d41efaf03db9b8a5c7cdb02699d8a5307144732
+  metadata.gz: 3991e8ff96b436e82a6edce43d591f35f669cbab9ef99b01bc26192bef94e3f48afe59595d8ae5d3d605bd96c0150bfdb557e555f1d20e79d74cbe4343d99c49
+  data.tar.gz: dcc10eeadec0f32073569db402893bb3f1ab5629da79eee32d605c476bbcf05f637f5b348f83478863bf7d28fc1d0b3d2cd9b54c38f356f3bfa53d51d3ac50bb

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 ## [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
+- **BREAKING:** Replace `json-schema` gem with `json_schemer` for support of newer JSON Schema specifications (set the lasest by default).
+- **BREAKING:** Schema and validation schema now uses string keys instead of symbols.
+
+### Added
+- Allow insert default values for properties when validation is used.
 
 ## [0.2.1] - 2025-06-22
 

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:
@@ -128,48 +128,53 @@ UserCreateRequest.to_schema(version: "2025-06")
 Output:
 ```ruby
 {
-  type: :object,
-  description: "User Create Request",
-  required: [:first_name, :last_name, :email, :address],
-  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"},
-    address: {"$ref": "#/components/schemas/AddressCreateRequest"},
-    permissions: {
-      type: :array, 
-      items: {
-        type: :object, 
-        required: [:name], 
-        properties: {
-          name: {type: :string, description: "Name of the permission"}, 
-          read: {type: :boolean, description: "Permission to read"}, 
-          write: {type: :boolean, description: "Permission to write"}
+  "type" => "object",
+  "description" => "User Create Request",
+  "required" => ["first_name", "last_name", "email", "address"],
+  "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"},
+    "address" => {"$ref" => "#/components/schemas/AddressCreateRequest"},
+    "permissions" => {
+      "type" => "array",
+      "items" => {
+        "type" => "object", 
+        "required" => ["name"], 
+        "properties" => {
+          "name" => {"type" => "string", "description" => "Name of the permission"}, 
+          "read" => {"type" => "boolean", "description" => "Permission to read"}, 
+          "write" => {"type" => "boolean", "description" => "Permission to write"}
         }
-      }, 
-      description: "Permissions associated with the user"
+      },
+      "description" => "Permissions associated with the user"
     },
-    role: {type: :string, description: "Role of the user", enum: ["member", "manager"], default: "member"},
-    profile_details: {
-      type: :object,
-      required: [],
-      properties: {
-        bio: {type: :string, description: "Short biography of the user"},
-        hobbies: {type: :array, items: {type: :string}, description: "Tags associated with the user"},
-        social_links: {
-          type: :object, 
-          required: [], 
-          properties: {
-            github: {type: :string, format: "uri", description: "GitHub profile URL"}, 
-            mastodon: {type: :string, format: "uri", description: "Mastodon profile URL"}
-          }, 
-          description: "Some social networks"
+    "role" => {
+      "type" => "string",
+      "description" => "Role of the user",
+      "enum" => ["member", "manager"],
+      "default" => "member"
+    },
+    "profile_details" => {
+      "type" => "object",
+      "required" => [],
+      "properties" => {
+        "bio" => {"type" => "string", "description" => "Short biography of the user"},
+        "hobbies" => {"type" => "array", "items" => {"type" => "string"}, "description" => "Tags associated with the user"},
+        "social_links" => {
+          "type" => "object",
+          "required" => [],
+          "properties" => {
+            "github" => {"type" => "string", "format" => "uri", "description" => "GitHub profile URL"},
+            "mastodon" => {"type" => "string", "format" => "uri", "description" => "Mastodon profile URL"}
+          },
+          "description" => "Some social networks"
         }
       }
     }
   },
-  additionalProperties: false
+  "additionalProperties" => false
 }
 ```
 
@@ -184,66 +189,69 @@ UserCreateRequest.to_validation_schema(version: "2025-06")
 Output:
 ```ruby
 {
-  type: :object,
-  description: "User Create Request",
-  required: [:first_name, :last_name, :email, :address],
-  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"},
-    address: { # from the AddressCreateRequest
-      type: :object,
-      description: "Address Create Request",
-      required: [:street, :city, :postal_code, :country],
-      properties: {
-        street: {type: :string, description: "Street address"}, 
-        city: {type: :string, description: "City of residence"}, 
-        postal_code: {type: :string, description: "Postal code"}, 
-        country: {type: :string, description: "Country of residence"}
+  "type" => "object",
+  "description" => "User Create Request",
+  "required" => ["first_name", "last_name", "email", "address"],
+  "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"},
+    "address" => { # from the AddressCreateRequest
+      "type" => "object",
+      "description" => "Address Create Request",
+      "required" => ["street", "city", "postal_code", "country"],
+      "properties" => {
+        "street" => {"type" => "string", "description" => "Street address"},
+        "city" => {"type" => "string", "description" => "City of residence"},
+        "postal_code" => {"type" => "string", "description" => "Postal code"},
+        "country" => {"type" => "string", "description" => "Country of residence"}
       },
-      additionalProperties: false
+      "additionalProperties" => false
     },
-    permissions: {
-      type: :array,
-      items: {
-        type: :object,
-        required: [:name],
-        properties: {
-          name: {type: :string, description: "Name of the permission"},
-          read: {type: :boolean, description: "Permission to read"},
-          write: {type: :boolean, description: "Permission to write"}
+    "permissions" => {
+      "type" => "array",
+      "items" => {
+        "type" => "object", "required" => ["name"],
+        "properties" => {
+          "name" => {"type" => "string", "description" => "Name of the permission"},
+          "read" => {"type" => "boolean", "description" => "Permission to read"},
+          "write" => {"type" => "boolean", "description" => "Permission to write"}
         }
       },
-      description: "Permissions associated with the user"
+      "description" => "Permissions associated with the user"
     },
-    role: {type: :string, description: "Role of the user", enum: ["member", "manager"], default: "member"},
-    profile_details: {
-      type: :object,
-      required: [],
-      properties: {
-        bio: {type: :string, description: "Short biography of the user"},
-        hobbies: {type: :array, items: {type: :string}, description: "Tags associated with the user"},
-        social_links: {
-          type: :object,
-          required: [],
-          properties: {
-            github: {type: :string, format: "uri", description: "GitHub profile URL"},
-            mastodon: {type: :string, format: "uri", description: "Mastodon profile URL"}
-          },
-          description: "Some social networks"
-        }
+    "role" => {
+      "type" => "string",
+      "description" => "Role of the user",
+      "enum" => ["member", "manager"],
+      "default" => "member"
+    },
+    "profile_details" => {"type" => "object",
+      "required" => [],
+      "properties" => {
+        "bio" => {"type" => "string", "description" => "Short biography of the user"},
+        "hobbies" => {"type" => "array", "items" => {"type" => "string"}, "description" => "Tags associated with the user"},
+        "social_links" => {
+          "type" => "object", 
+          "required" => [], 
+          "properties" => {
+            "github" => {"type" => "string", "format" => "uri", "description" => "GitHub profile URL"}, 
+            "mastodon" => {"type" => "string", "format" => "uri", "description" => "Mastodon profile URL"}
+          }, 
+          "description" => "Some social networks"}
       }
     }
   },
-  additionalProperties: false
+  "additionalProperties" => false
 }
 ```
 
 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
@@ -268,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:
@@ -410,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
@@ -425,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/private_class_methods.rb

@@ -64,7 +64,7 @@ module Verquest
       instance_exec(&block)
     ensure
       version.description ||= versions.description
-      version.schema_options = versions.schema_options.merge(version.schema_options)
+      version.schema_options = versions.schema_options.merge(version.schema_options).transform_keys(&:to_s)
       version.prepare
     end
 

data/lib/verquest/base/public_class_methods.rb

@@ -12,7 +12,8 @@ module Verquest
     # @param version [String, nil] Specific version to use, defaults to configuration setting
     # @param validate [Boolean, nil] Whether to validate the params, defaults to configuration setting
     # @param remove_extra_root_keys [Boolean, nil] Whether to remove extra keys at the root level, defaults to configuration setting
-    # @return [Verquest::Result] Success result with mapped params or failure result with validation errors
+    # @return [Verquest::Result, Hash, Exception] When validation_error_handling is :result, returns a Success result with mapped params or Failure result with validation errors.
+    #   When validation_error_handling is :raise, returns mapped params directly or raises InvalidParamsError with validation errors.
     def process(params, version: nil, validate: nil, remove_extra_root_keys: nil)
       validate = Verquest.configuration.validate_params if validate.nil?
       remove_extra_root_keys = Verquest.configuration.remove_extra_root_keys if remove_extra_root_keys.nil?
@@ -23,7 +24,7 @@ module Verquest
       params = params.to_unsafe_h if params.respond_to?(:to_unsafe_h)
       params = params.slice(*version_class.properties.keys) if remove_extra_root_keys
 
-      if validate && (validation_result = version_class.validate_params(params: params, component_reference: to_ref, remove_extra_root_keys: remove_extra_root_keys)) && validation_result.any?
+      if validate && (validation_result = version_class.validate_params(params: params)) && validation_result.any?
         case Verquest.configuration.validation_error_handling
         when :raise
           raise InvalidParamsError.new("Validation failed", errors: validation_result)
@@ -59,7 +60,7 @@ module Verquest
       version = resolve(version)
 
       if property
-        version.validation_schema[:properties][property]
+        version.validation_schema["properties"][property.to_s]
       else
         version.validation_schema
       end
@@ -69,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
@@ -76,7 +90,7 @@ module Verquest
     # Returns the mapping for a specific version or property
     #
     # @param version [String, nil] Specific version to use, defaults to configuration setting
-    # @param property [Symbol, nil] Specific property to retrieve mapping for
+    # @param property [String, Symbol, nil] Specific property to retrieve mapping for
     # @return [Hash] The mapping configuration
     def mapping(version: nil, property: nil)
       version = resolve(version)
@@ -90,7 +104,7 @@ module Verquest
 
     # Returns the JSON reference for the request or a specific property
     #
-    # @param property [Symbol, nil] Specific property to retrieve reference for
+    # @param property [String, Symbol, nil] Specific property to retrieve reference for
     # @return [String] The JSON reference for the request or property
     def to_ref(property: nil)
       base = "#/components/schemas/#{component_name}"

data/lib/verquest/configuration.rb

@@ -11,13 +11,35 @@ 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,
+      draft7: JSONSchemer::Draft7,
+      draft2019_09: JSONSchemer::Draft201909,
+      draft2020_12: JSONSchemer::Draft202012,
+      openapi30: JSONSchemer::OpenAPI30,
+      openapi31: JSONSchemer::OpenAPI31
+    }.freeze
+
     # @!attribute [rw] validate_params
     #   Controls whether parameters are automatically validated against the schema
     #   @return [Boolean] true if validation is enabled, false otherwise
     #
     # @!attribute [rw] json_schema_version
-    #   The JSON Schema draft version to use for validation and schema generation (see the json-schema gem)
-    #   @return [Symbol] The JSON Schema version (e.g., :draft4, :draft5)
+    #   The JSON Schema draft version to use for validation and schema generation (see Configuration::SCHEMAS)
+    #   @return [Symbol] The JSON Schema version (e.g., :draft2020_12, :draft2019_09, :draft7)
     #
     # @!attribute [rw] validation_error_handling
     #   Controls how errors during parameter processing are handled
@@ -26,7 +48,11 @@ module Verquest
     # @!attribute [rw] remove_extra_root_keys
     #   Controls if extra root keys not defined in the schema should be removed from the parameters
     #   @return [Boolean] true if extra keys should be removed, false otherwise
-    attr_accessor :validate_params, :json_schema_version, :validation_error_handling, :remove_extra_root_keys
+    #
+    # @!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 [r] current_version
     #   A callable object that returns the current API version to use when not explicitly specified
@@ -35,17 +61,23 @@ 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
     #
     # @return [Configuration] A new configuration instance with default settings
     def initialize
       @validate_params = true
-      @json_schema_version = :draft6
+      @json_schema_version = :draft2020_12
       @validation_error_handling = :raise # or :result
       @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
@@ -69,5 +101,53 @@ 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
+    # @raise [ArgumentError] If the configured json_schema_version is not supported
+    def json_schema
+      SCHEMAS[json_schema_version] || raise(ArgumentError, "Unsupported JSON Schema version: #{json_schema_version}")
+    end
+
+    # Gets the JSON Schema URI for the configured schema version
+    #
+    # @return [String] The base URI for the configured JSON Schema version
+    def json_schema_uri
+      json_schema::BASE_URI.to_s
+    end
   end
 end

data/lib/verquest/gem_version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Verquest
-  GEM_VERSION = "0.2.1"
+  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(
@@ -16,20 +17,34 @@ module Verquest
     class Array < Base
       # Initialize a new Array property
       #
-      # @param name [Symbol] The name of the property
-      # @param type [Symbol] The type of items in the array
+      # @param name [String, Symbol] The name of the property
+      # @param type [String, Symbol] The type of items in the array, can be a default type or a custom field type
       # @param map [String, nil] The mapping path for this property (nil for no explicit mapping)
       # @param required [Boolean] Whether this property is required
-      # @param 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 == "/"
 
-        @name = name
-        @type = type
+        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
         @map = map
         @required = required
-        @schema_options = schema_options
+        @schema_options = schema_options&.transform_keys(&:to_s)
       end
 
       # Generate JSON schema definition for this array property
@@ -38,16 +53,16 @@ module Verquest
       def to_schema
         {
           name => {
-            type: :array,
-            items: {type: type}
+            "type" => "array",
+            "items" => {"type" => type}.merge(item_schema_options)
           }.merge(schema_options)
         }
       end
 
       # Create mapping for this array property
       #
-      # @param key_prefix [Array<Symbol>] Prefix for the source key
-      # @param value_prefix [Array<Symbol>] Prefix for the target value
+      # @param key_prefix [Array<String>] Prefix for the source key
+      # @param value_prefix [Array<String>] Prefix for the target value
       # @param mapping [Hash] The mapping hash to be updated
       # @param version [String, nil] The version to create mapping for, defaults to configuration setting
       # @return [Hash] The updated mapping hash
@@ -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/base.rb

@@ -11,7 +11,7 @@ module Verquest
     # @abstract Subclass and override {#to_schema}, {#mapping} to implement
     class Base
       # @!attribute [rw] name
-      #   @return [Symbol] The name of the property
+      #   @return [String] The name of the property
       # @!attribute [rw] required
       #   @return [Boolean] Whether this property is required
       # @!attribute [rw] map
@@ -43,7 +43,7 @@ module Verquest
 
       # Creates mapping for this property
       # @abstract
-      # @param key_prefix [Array<Symbol>] Prefix for the source key
+      # @param key_prefix [Array<String>] Prefix for the source key
       # @param value_prefix [Array<String>] Prefix for the target value
       # @param mapping [Hash] The mapping hash to be updated
       # @param version [String, nil] The version to create mapping for

data/lib/verquest/properties/collection.rb

@@ -20,7 +20,7 @@ module Verquest
     class Collection < Base
       # Initialize a new Collection property
       #
-      # @param name [Symbol] The name of the property
+      # @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 map [String, nil] The mapping path for this property
@@ -31,11 +31,11 @@ module Verquest
 
         @properties = {}
 
-        @name = name
+        @name = name.to_s
         @item = item
         @required = required
         @map = map
-        @schema_options = schema_options
+        @schema_options = schema_options&.transform_keys(&:to_s)
       end
 
       # Add a child property to this collection's item definition
@@ -60,20 +60,20 @@ module Verquest
         if has_item?
           {
             name => {
-              type: :array,
-              items: {
-                "$ref": item.to_ref
+              "type" => "array",
+              "items" => {
+                "$ref" => item.to_ref
               }
             }.merge(schema_options)
           }
         else
           {
             name => {
-              type: :array,
-              items: {
-                type: :object,
-                required: properties.values.select(&:required).map(&:name),
-                properties: properties.transform_values { |property| property.to_schema[property.name] }
+              "type" => "array",
+              "items" => {
+                "type" => "object",
+                "required" => properties.values.select(&:required).map(&:name),
+                "properties" => properties.transform_values { |property| property.to_schema[property.name] }
               }
             }.merge(schema_options)
           }
@@ -88,18 +88,18 @@ module Verquest
         if has_item?
           {
             name => {
-              type: :array,
-              items: item.to_validation_schema(version: version)
+              "type" => "array",
+              "items" => item.to_validation_schema(version: version)
             }.merge(schema_options)
           }
         else
           {
             name => {
-              type: :array,
-              items: {
-                type: :object,
-                required: properties.values.select(&:required).map(&:name),
-                properties: properties.transform_values { |property| property.to_validation_schema(version: version)[property.name] }
+              "type" => "array",
+              "items" => {
+                "type" => "object",
+                "required" => properties.values.select(&:required).map(&:name),
+                "properties" => properties.transform_values { |property| property.to_validation_schema(version: version)[property.name] }
               }
             }.merge(schema_options)
           }
@@ -118,7 +118,7 @@ module Verquest
       #    - Creates mappings for each property in the collection items
       #    - Each property gets mapped with array notation and appropriate prefixes
       #
-      # @param key_prefix [Array<Symbol>] Prefix for the source key
+      # @param key_prefix [Array<String>] Prefix for the source key
       # @param value_prefix [Array<String>] Prefix for the target value
       # @param mapping [Hash] The mapping hash to be updated
       # @param version [String, nil] The version to create mapping for

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,46 @@ module Verquest
     #     format: "email"
     #   )
     class Field < Base
-      # List of allowed field types
+      # List of default field types
       # @return [Array<Symbol>]
-      ALLOWED_TYPES = %i[string number integer boolean].freeze
+      DEFAULT_TYPES = %w[string number integer boolean].freeze
 
       # Initialize a new Field property
       #
-      # @param name [Symbol] The name of the property
-      # @param type [Symbol] The data type for this field, must be one of ALLOWED_TYPES
-      # @param required [Boolean] Whether this property is required
+      # @param name [String, Symbol] The name of the property
+      # @param type [String, Symbol] The data type for this field, can be a default type or a custom field type
+      # @param required [Boolean] Whether this property is required (overridden by custom type if it defines required)
       # @param 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)
+        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 == "/"
 
-        @name = name
-        @type = type
-        @required = required
+        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
         @map = map
-        @schema_options = schema_options
       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 +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/properties/object.rb

@@ -14,17 +14,17 @@ module Verquest
     class Object < Base
       # Initialize a new Object property
       #
-      # @param name [String] The name of the property
+      # @param name [String, Symbol] The name of the property
       # @param required [Boolean] Whether this property is required
       # @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)
         @properties = {}
 
-        @name = name
+        @name = name.to_s
         @required = required
         @map = map
-        @schema_options = schema_options
+        @schema_options = schema_options&.transform_keys(&:to_s)
       end
 
       # Add a child property to this object
@@ -32,7 +32,7 @@ module Verquest
       # @param property [Verquest::Properties::Base] The property to add to this object
       # @return [Verquest::Properties::Base] The added property
       def add(property)
-        properties[property.name] = property
+        properties[property.name.to_s] = property
       end
 
       # Generate JSON schema definition for this object property
@@ -41,9 +41,9 @@ module Verquest
       def to_schema
         {
           name => {
-            type: :object,
-            required: properties.values.select(&:required).map(&:name),
-            properties: properties.transform_values { |property| property.to_schema[property.name] }
+            "type" => "object",
+            "required" => properties.values.select(&:required).map(&:name),
+            "properties" => properties.transform_values { |property| property.to_schema[property.name] }
           }.merge(schema_options)
         }
       end
@@ -55,16 +55,16 @@ module Verquest
       def to_validation_schema(version: nil)
         {
           name => {
-            type: :object,
-            required: properties.values.select(&:required).map(&:name),
-            properties: properties.transform_values { |property| property.to_validation_schema(version:)[property.name] }
+            "type" => "object",
+            "required" => properties.values.select(&:required).map(&:name),
+            "properties" => properties.transform_values { |property| property.to_validation_schema(version: version)[property.name] }
           }.merge(schema_options)
         }
       end
 
       # Create mapping for this object property and all its children
       #
-      # @param key_prefix [Array<Symbol>] Prefix for the source key
+      # @param key_prefix [Array<String>] Prefix for the source key
       # @param value_prefix [Array<String>] Prefix for the target value
       # @param mapping [Hash] The mapping hash to be updated
       # @param version [String, nil] The version to create mapping for

data/lib/verquest/properties/reference.rb

@@ -23,13 +23,13 @@ module Verquest
     class Reference < Base
       # Initialize a new Reference property
       #
-      # @param name [String] The name of the property
+      # @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 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)
-        @name = name
+        @name = name.to_s
         @from = from
         @property = property
         @map = map
@@ -41,7 +41,7 @@ module Verquest
       # @return [Hash] The schema definition with a $ref pointer
       def to_schema
         {
-          name => {"$ref": from.to_ref(property:)}
+          name => {"$ref" => from.to_ref(property: property)}
         }
       end
 
@@ -58,7 +58,7 @@ module Verquest
       # Create mapping for this reference property
       # This delegates to the referenced schema's mapping with appropriate key prefixing
       #
-      # @param key_prefix [Array<Symbol>] Prefix for the source key
+      # @param key_prefix [Array<String>] Prefix for the source key
       # @param value_prefix [Array<String>] Prefix for the target value
       # @param mapping [Hash] The mapping hash to be updated
       # @param version [String, nil] The version to create mapping for

data/lib/verquest/transformer.rb

@@ -113,12 +113,11 @@ module Verquest
 
       case data
       when Hash
-        # Check if the key exists (as string or symbol)
-        return nil unless data.key?(key.to_s) || data.key?(key.to_sym)
+        # Only check for string keys
+        return nil unless data.key?(key.to_s)
 
-        # Determine the actual key type used in the hash
-        actual_key = data.key?(key.to_s) ? key.to_s : key.to_sym
-        value = data[actual_key]
+        # Always use string keys
+        value = data[key.to_s]
 
         if current_part[:array] && value.is_a?(Array)
           # Process array elements and filter out nil values
@@ -153,7 +152,7 @@ module Verquest
 
       current_part = path_parts.first
       remaining_path = path_parts[1..]
-      key = current_part[:key].to_sym # Convert key to symbol for consistent symbol keys
+      key = current_part[:key].to_s # Ensure key is a string for consistency
 
       if remaining_path.empty?
         # End of path, set the value directly

data/lib/verquest/version.rb

@@ -50,7 +50,7 @@ module Verquest
     # @param name [String] The name/identifier of the version
     # @return [Version] A new Version instance
     def initialize(name:)
-      @name = name
+      @name = name.to_s
       @schema_options = {}
       @properties = {}
     end
@@ -69,7 +69,7 @@ module Verquest
     # @return [Verquest::Properties::Base] The removed property
     # @raise [PropertyNotFoundError] If the property doesn't exist
     def remove(property_name)
-      properties.delete(property_name) || raise(PropertyNotFoundError.new("Property '#{property_name}' is not defined on '#{name}"))
+      properties.delete(property_name.to_s) || raise(PropertyNotFoundError.new("Property '#{property_name}' is not defined on '#{name}'"))
     end
 
     # Check if this version has a property with the given name
@@ -77,7 +77,7 @@ module Verquest
     # @param property_name [Symbol, String] The name of the property to check
     # @return [Boolean] true if the property exists, false otherwise
     def has?(property_name)
-      properties.key?(property_name)
+      properties.key?(property_name.to_s)
     end
 
     # Copy properties from another version
@@ -90,7 +90,7 @@ module Verquest
       raise ArgumentError, "Expected a Verquest::Version instance" unless version.is_a?(Version)
 
       version.properties.values.each do |property|
-        next if exclude_properties.include?(property.name)
+        next if exclude_properties.include?(property.name.to_sym)
 
         add(property)
       end
@@ -113,28 +113,53 @@ module Verquest
     # Validate the schema against the metaschema
     #
     # @return [Boolean] true if the schema is valid, false otherwise
-    def validate_schema
-      schema_name = Verquest.configuration.json_schema_version
+    def valid_schema?
+      JSONSchemer.valid_schema?(
+        validation_schema,
+        meta_schema: Verquest.configuration.json_schema_uri
+      )
+    end
 
-      metaschema = JSON::Validator.validator_for_name(schema_name).metaschema
-      JSON::Validator.validate(metaschema, validation_schema)
+    # 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
     #
     # @param params [Hash] The request parameters to validate
-    # @param component_reference [String] A reference string for components in the schema
-    # @param remove_extra_root_keys [Boolean] Whether to remove extra keys not in the schema
     # @return [Array<Hash>] An array of validation error details, or empty if valid
-    def validate_params(params:, component_reference:, remove_extra_root_keys:)
-      schema_name = Verquest.configuration.json_schema_version
-
-      result = JSON::Validator.fully_validate(validation_schema, params, version: schema_name, errors_as_objects: true)
-      return result if result.empty?
-
-      result.map do |error|
-        schema = error.delete(:schema)
-        error[:message].gsub!(schema.to_s, component_reference)
+    def validate_params(params:)
+      schemer = JSONSchemer.schema(
+        validation_schema,
+        meta_schema: Verquest.configuration.json_schema_uri,
+        insert_property_defaults: Verquest.configuration.insert_property_defaults
+      )
+
+      schemer.validate(params).map do |error|
+        {
+          pointer: error["data_pointer"],
+          type: error["type"],
+          message: error["error"],
+          details: error["details"]
+        }
       end
     end
 
@@ -147,7 +172,7 @@ module Verquest
       raise PropertyNotFoundError.new("Property '#{property}' is not defined on '#{name}'") unless has?(property)
 
       {}.tap do |mapping|
-        properties[property].mapping(key_prefix: [], value_prefix: [], mapping: mapping, version: name)
+        properties[property.to_s].mapping(key_prefix: [], value_prefix: [], mapping: mapping, version: name)
       end
     end
 
@@ -170,10 +195,10 @@ module Verquest
     # @return [Hash] The frozen schema hash
     def prepare_schema
       @schema = {
-        type: :object,
-        description: description,
-        required: properties.values.select(&:required).map(&:name),
-        properties: properties.transform_values { |property| property.to_schema[property.name] }
+        "type" => "object",
+        "description" => description,
+        "required" => properties.values.select(&:required).map(&:name),
+        "properties" => properties.transform_values { |property| property.to_schema[property.name] }
       }.merge(schema_options).freeze
     end
 
@@ -185,10 +210,10 @@ module Verquest
     # @return [Hash] The frozen validation schema hash
     def prepare_validation_schema
       @validation_schema = {
-        type: :object,
-        description: description,
-        required: properties.values.select(&:required).map(&:name),
-        properties: properties.transform_values { |property| property.to_validation_schema(version: name)[property.name] }
+        "type" => "object",
+        "description" => description,
+        "required" => properties.values.select(&:required).map(&:name),
+        "properties" => properties.transform_values { |property| property.to_validation_schema(version: name)[property.name] }
       }.merge(schema_options).freeze
     end
 

data/lib/verquest.rb

@@ -1,10 +1,13 @@
 # frozen_string_literal: true
 
 require "zeitwerk"
-require "json-schema"
+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.2.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Petr Hlavicka
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-06-22 00:00:00.000000000 Z
+date: 2025-06-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: zeitwerk
@@ -25,19 +25,19 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '2.7'
 - !ruby/object:Gem::Dependency
-  name: json-schema
+  name: json_schemer
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.0'
+        version: '2.4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.0'
+        version: '2.4'
 description: Verquest helps you version API requests, simplifying the management of
   changes, handling the mapping for internal versus external names and structures,
   validating parameters, and exporting your requests to JSON Schema components for