verquest 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b9349b2773c4a03024805d78257b1e763ffb87b87f27726620e343395c683aa0
-  data.tar.gz: ec2b70a4a10c3314ca27283776138f85b53b245d88869de39e450ca2eb2064de
+  metadata.gz: 92e6047d9812ae82cf55b5d0512c459a61306c7b2cc78c9cd224e2b52b4b716c
+  data.tar.gz: db8943d346e30972f3b6b516d9365d7ef37dedf89fa7f4a09c5db4cb1adbe545
 SHA512:
-  metadata.gz: 0d0042f959285f4253c7802166ab64d53b7013d765bfe954fd68a8ab46bb59f162512a285aca11c77e86a8e6b5ce36445f47e4e9530fcaa0010e8c6cadcefdf2
-  data.tar.gz: 06bbfceb1c989e1e3eabb20e495790ac35934e1cb4687e71960315c3e64d3a30b42b345c03d19d32be921b75550a6fef002d8ba44018ded8f7c9a3af73d920f0
+  metadata.gz: 0163416a3ea0f4d5cb5619b74e31ca7f2999ddccba55091d8fa8f10244a36eeb59dadd1b6d9eae6bd22d1f49e5ea7213aeb42218731f248be69d54c2127bb216
+  data.tar.gz: ee7adc256954aafa194a3175f50649479a8f45292d8bed51cf076f17c1d0693fbe7099e64675d249448c1e66cb9b1dce4749da71e76f36fc2d976b7387f23382

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 ## [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

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.5"
+gem "verquest", "~> 0.6"
 ```
 
 And then execute:
@@ -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,7 +132,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},
@@ -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,7 +280,7 @@ 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
+#### 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.
 
@@ -538,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.
@@ -586,7 +609,7 @@ end
 
 ## Documentation
 
-For detailed documentation, please visit the [YARD documentation](https://www.rubydoc.info/gems/verquest/0.5.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

@@ -138,6 +138,42 @@ module Verquest
       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

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/gem_version.rb

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

data/lib/verquest/properties/array.rb

@@ -75,7 +75,7 @@ module Verquest
       # @param version [String, nil] The version to create mapping for, defaults to configuration setting
       # @return [Hash] The updated mapping hash
       def mapping(key_prefix:, value_prefix:, mapping:, version: nil)
-        mapping[(key_prefix + [name]).join(".")] = mapping_value_key(value_prefix:)
+        mapping[(key_prefix + [name]).join("/")] = mapping_value_key(value_prefix:)
       end
 
       private

data/lib/verquest/properties/base.rb

@@ -67,13 +67,13 @@ module Verquest
       # @return [String] The target mapping key
       def mapping_value_key(value_prefix:, collection: false)
         value_key = if map.nil?
-          (value_prefix + [name]).join(".")
+          (value_prefix + [name]).join("/")
         elsif map == "/"
           ""
         elsif map.start_with?("/")
           map.gsub(%r{^/}, "")
         else
-          (value_prefix + map.split(".")).join(".")
+          (value_prefix + map.split("/")).join("/")
         end
 
         if collection
@@ -93,9 +93,9 @@ module Verquest
         elsif map == "/"
           []
         elsif map.start_with?("/")
-          map.gsub(%r{^/}, "").split(".")
+          map.gsub(%r{^/}, "").split("/")
         else
-          value_prefix + map.split(".")
+          value_prefix + map.split("/")
         end
 
         if collection && value_prefix.any?

data/lib/verquest/properties/collection.rb

@@ -142,8 +142,8 @@ module Verquest
           value_key_prefix = mapping_value_key(value_prefix: value_prefix, collection: true)
 
           reference_mapping = item.mapping(version:).dup
-          reference_mapping.transform_keys! { "#{(key_prefix + [name]).join(".")}[].#{_1}" }
-          reference_mapping.transform_values! { "#{value_key_prefix}.#{_1}" }
+          reference_mapping.transform_keys! { "#{(key_prefix + [name]).join("/")}[]/#{_1}" }
+          reference_mapping.transform_values! { "#{value_key_prefix}/#{_1}" }
 
           mapping.merge!(reference_mapping)
         else

data/lib/verquest/properties/const.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Verquest
+  module Properties
+    # The Const class represents a constant property with a fixed value in a JSON schema.
+    # It's used for properties that must have a specific, immutable value.
+    #
+    # @example
+    #   const = Const.new(name: "type", value: "user")
+    class Const < Base
+      # Initialize a new constant property
+      #
+      # @param name [String, Symbol] The name of the constant property
+      # @param value [Object] The fixed value of the constant (can be any scalar value)
+      # @param map [Object, nil] Optional mapping information
+      # @param required [Boolean, Array<Symbol>] Whether this property is required, or array of dependency names (can be overridden by custom type)
+      # @param schema_options [Hash] Additional JSON schema options for this property
+      def initialize(name:, value:, map: nil, required: false, **schema_options)
+        @name = name.to_s
+        @value = value
+        @map = map
+        @required = required
+        @schema_options = schema_options&.transform_keys(&:to_s)
+      end
+
+      # Generate JSON schema definition for this constant
+      #
+      # @return [Hash] The schema definition for this constant
+      def to_schema
+        {
+          name => {
+            "const" => value
+          }.merge(schema_options)
+        }
+      end
+
+      # Create mapping for this const property
+      #
+      # @param key_prefix [Array<Symbol>] 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
+      # @return [Hash] The updated mapping hash
+      def mapping(key_prefix:, value_prefix:, mapping:, version: nil)
+        mapping[(key_prefix + [name]).join("/")] = mapping_value_key(value_prefix:)
+      end
+
+      private
+
+      attr_reader :value, :schema_options
+    end
+  end
+end

data/lib/verquest/properties/enum.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Verquest
+  module Properties
+    # The Enum class represents a enum property with a list of possible values in a JSON schema.
+    #
+    # @example
+    #   enum = Enum.new(name: "type", values: ["member", "admin"])
+    class Enum < Base
+      # Initialize a new Enum property
+      #
+      # @param name [String, Symbol] The name of the property
+      # @param values [Array] The enum values for this property
+      # @param required [Boolean, Array<Symbol>] Whether this property is required, or array of dependency names
+      # @param nullable [Boolean] Whether this property can be null
+      # @param map [String, nil] The mapping path for this property
+      # @param schema_options [Hash] Additional JSON schema options for this property
+      # @raise [ArgumentError] If attempting to map an enum to root without a name
+      # @raise [ArgumentError] If values is empty
+      # @raise [ArgumentError] If values are not unique
+      # @raise [ArgumentError] If only one value is provided (should use const instead)
+      def initialize(name:, values:, required: false, nullable: false, map: nil, **schema_options)
+        raise ArgumentError, "You can not map enums to the root without a name" if map == "/"
+        raise ArgumentError, "Values must not be empty" if values.empty?
+        raise ArgumentError, "Values must be unique" if values.uniq.length != values.length
+        raise ArgumentError, "Use const for a single value" if values.length == 1
+
+        @name = name.to_s
+        @values = values
+        @required = required
+        @nullable = nullable
+        @map = map
+        @schema_options = schema_options&.transform_keys(&:to_s)
+
+        if nullable && !values.include?("null")
+          values << "null"
+        end
+      end
+
+      # Generate JSON schema definition for this enum
+      #
+      # @return [Hash] The schema definition for this enum
+      def to_schema
+        {
+          name => {"enum" => values}.merge(schema_options)
+        }
+      end
+
+      # Create mapping for this enum property
+      #
+      # @param key_prefix [Array<Symbol>] 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
+      # @return [Hash] The updated mapping hash
+      def mapping(key_prefix:, value_prefix:, mapping:, version: nil)
+        mapping[(key_prefix + [name]).join("/")] = mapping_value_key(value_prefix:)
+      end
+
+      private
+
+      attr_reader :values, :schema_options
+    end
+  end
+end

data/lib/verquest/properties/field.rb

@@ -74,7 +74,7 @@ module Verquest
       # @param version [String, nil] The version to create mapping for
       # @return [Hash] The updated mapping hash
       def mapping(key_prefix:, value_prefix:, mapping:, version: nil)
-        mapping[(key_prefix + [name]).join(".")] = mapping_value_key(value_prefix:)
+        mapping[(key_prefix + [name]).join("/")] = mapping_value_key(value_prefix:)
       end
 
       private

data/lib/verquest/properties/reference.rb

@@ -87,16 +87,16 @@ module Verquest
         value_key_prefix = mapping_value_key(value_prefix:)
 
         # Single field mapping
-        if property && reference_mapping.size == 1 && !reference_mapping.keys.first.include?(".")
+        if property && reference_mapping.size == 1 && !reference_mapping.keys.first.include?("/")
           reference_mapping = {
-            (key_prefix + [name]).join(".") => value_key_prefix
+            (key_prefix + [name]).join("/") => value_key_prefix
           }
         else
-          if value_key_prefix != "" && !value_key_prefix.end_with?(".")
-            value_key_prefix = "#{value_key_prefix}."
+          if value_key_prefix != "" && !value_key_prefix.end_with?("/")
+            value_key_prefix = "#{value_key_prefix}/"
           end
 
-          reference_mapping.transform_keys! { "#{(key_prefix + [name]).join(".")}.#{_1}" }
+          reference_mapping.transform_keys! { "#{(key_prefix + [name]).join("/")}/#{_1}" }
           reference_mapping.transform_values! { "#{value_key_prefix}#{_1}" }
         end
 

data/lib/verquest/transformer.rb

@@ -3,13 +3,13 @@ module Verquest
   #
   # The Transformer class handles the conversion of parameter structures based on
   # a mapping of source paths to target paths. It supports deep nested structures,
-  # array notations, and complex path expressions using dot notation.
+  # array notations, and complex path expressions using slash notation.
   #
   # @example Basic transformation
   #   mapping = {
-  #     "user.firstName" => "user.first_name",
-  #     "user.lastName" => "user.last_name",
-  #     "addresses[].zip" => "addresses[].postal_code"
+  #     "user/firstName" => "user/first_name",
+  #     "user/lastName" => "user/last_name",
+  #     "addresses[]/zip" => "addresses[]/postal_code"
   #   }
   #
   #   transformer = Verquest::Transformer.new(mapping: mapping)
@@ -84,13 +84,13 @@ module Verquest
       end
     end
 
-    # Parses a dot-notation path into structured path parts
+    # Parses a slash-notation path into structured path parts
     # Uses memoization for performance optimization
     #
-    # @param path [String] The dot-notation path (e.g., "user.address.street")
+    # @param path [String] The slash-notation path (e.g., "user/address/street")
     # @return [Array<Hash>] Array of path parts with :key and :array attributes
     def parse_path(path)
-      path_cache[path] ||= path.split(".").map do |part|
+      path_cache[path] ||= path.split("/").map do |part|
         if part.end_with?("[]")
           {key: part[0...-2], array: true}
         else

data/lib/verquest/version.rb

@@ -38,7 +38,10 @@ module Verquest
     #
     # @!attribute [r] transformer
     #   @return [Verquest::Transformer] The transformer that applies the mapping
-    attr_reader :name, :properties, :schema, :validation_schema, :mapping, :transformer
+    #
+    # @!attribute [r] external_mapping
+    #   @return [Hash] The mapping from internal attribute paths back to external paths
+    attr_reader :name, :properties, :schema, :validation_schema, :mapping, :transformer, :external_mapping
 
     # @!attribute [rw] schema_options
     #   @return [Hash] Additional JSON schema options for this version
@@ -113,6 +116,7 @@ module Verquest
       prepare_schema
       prepare_validation_schema
       prepare_mapping
+      prepare_external_mapping
       @transformer = Transformer.new(mapping: mapping)
 
       freeze
@@ -245,5 +249,18 @@ module Verquest
         raise MappingError.new("Mapping must be unique. Found duplicates in version '#{name}': #{duplicates.join(", ")}")
       end
     end
+
+    # Prepares the inverted parameter mapping for this version
+    #
+    # Inverts the standard mapping to create a reverse lookup from internal
+    # attribute names back to external parameter names. This is useful when
+    # transforming internal data back to the external API representation.
+    #
+    # @return [Hash] The frozen inverted mapping where keys are internal attribute
+    #   paths and values are the corresponding external schema paths
+    # @see #prepare_mapping
+    def prepare_external_mapping
+      @external_mapping = mapping.invert.freeze
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: verquest
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Petr Hlavicka
@@ -66,6 +66,8 @@ files:
 - lib/verquest/properties/array.rb
 - lib/verquest/properties/base.rb
 - lib/verquest/properties/collection.rb
+- lib/verquest/properties/const.rb
+- lib/verquest/properties/enum.rb
 - lib/verquest/properties/field.rb
 - lib/verquest/properties/object.rb
 - lib/verquest/properties/reference.rb
@@ -95,7 +97,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.6.7
 specification_version: 4
 summary: Verquest is a Ruby gem that offers an elegant solution for versioning API
   requests