verquest 0.4.0 → 0.6.0

data/lib/verquest/properties/array.rb

@@ -20,31 +20,39 @@ module Verquest
       # @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 required [Boolean, Array<Symbol>] Whether this property is required, or array of dependency names
+      # @param nullable [Boolean] Whether this property can be null
       # @param item_schema_options [Hash] Additional JSON schema options for the array items (merged with custom type options)
       # @param schema_options [Hash] Additional JSON schema options for the array property itself
       # @raise [ArgumentError] If type is not one of the allowed types (default or custom)
       # @raise [ArgumentError] If attempting to map an array to the root
-      def initialize(name:, type:, map: nil, required: false, item_schema_options: {}, **schema_options)
+      def initialize(name:, type:, map: nil, required: false, nullable: false, item_schema_options: {}, **schema_options)
         raise ArgumentError, "Type must be one of #{allowed_types.join(", ")}" unless allowed_types.include?(type.to_s)
         raise ArgumentError, "You can not map array to the root" if map == "/"
 
         if (custom_type = Verquest.configuration.custom_field_types[type.to_sym])
-          @type = custom_type[:type].to_s
+          @item_type = custom_type[:type].to_s
           @item_schema_options = if custom_type.key?(:schema_options)
             custom_type[:schema_options].merge(item_schema_options).transform_keys(&:to_s)
           else
             item_schema_options.transform_keys(&:to_s)
           end
         else
-          @type = type.to_s
+          @item_type = type.to_s
           @item_schema_options = item_schema_options.transform_keys(&:to_s)
         end
 
         @name = name.to_s
         @map = map
         @required = required
+        @nullable = nullable
         @schema_options = schema_options&.transform_keys(&:to_s)
+
+        @type = if nullable
+          %w[array null]
+        else
+          "array"
+        end
       end
 
       # Generate JSON schema definition for this array property
@@ -53,8 +61,8 @@ module Verquest
       def to_schema
         {
           name => {
-            "type" => "array",
-            "items" => {"type" => type}.merge(item_schema_options)
+            "type" => type,
+            "items" => {"type" => item_type}.merge(item_schema_options)
           }.merge(schema_options)
         }
       end
@@ -67,12 +75,12 @@ 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
 
-      attr_reader :type, :schema_options, :item_schema_options
+      attr_reader :type, :item_type, :schema_options, :item_schema_options
 
       # Gets the list of allowed item types, including both default and custom types
       #

data/lib/verquest/properties/base.rb

@@ -10,6 +10,8 @@ module Verquest
     #
     # @abstract Subclass and override {#to_schema}, {#mapping} to implement
     class Base
+      include HelperMethods::RequiredProperties
+
       # @!attribute [rw] name
       #   @return [String] The name of the property
       # @!attribute [rw] required
@@ -55,19 +57,23 @@ module Verquest
 
       private
 
+      # @!attribute [r] nullable
+      #   @return [Boolean] Whether this property can be null
+      attr_reader :nullable
+
       # Determines the mapping target key based on mapping configuration
       # @param value_prefix [Array<String>] Prefix for the target value
       # @param collection [Boolean] Whether this is a collection mapping
       # @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
@@ -87,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

@@ -22,11 +22,12 @@ module Verquest
       #
       # @param name [String, Symbol] The name of the property
       # @param item [Verquest::Base, nil] Optional reference to an external schema class
-      # @param required [Boolean] Whether this property is required
+      # @param required [Boolean, Array<Symbol>] Whether this property is required, or array of dependency names
+      # @param nullable [Boolean] Whether this property can be null
       # @param map [String, nil] The mapping path for this property
       # @param schema_options [Hash] Additional JSON schema options for this property
       # @raise [ArgumentError] If attempting to map a collection to the root
-      def initialize(name:, item: nil, required: false, map: nil, **schema_options)
+      def initialize(name:, item: nil, required: false, nullable: false, map: nil, **schema_options)
         raise ArgumentError, "You can not map collection to the root" if map == "/"
 
         @properties = {}
@@ -34,8 +35,15 @@ module Verquest
         @name = name.to_s
         @item = item
         @required = required
+        @nullable = nullable
         @map = map
         @schema_options = schema_options&.transform_keys(&:to_s)
+
+        @type = if nullable
+          %w[array null]
+        else
+          "array"
+        end
       end
 
       # Add a child property to this collection's item definition
@@ -60,7 +68,7 @@ module Verquest
         if has_item?
           {
             name => {
-              "type" => "array",
+              "type" => type,
               "items" => {
                 "$ref" => item.to_ref
               }
@@ -69,12 +77,15 @@ module Verquest
         else
           {
             name => {
-              "type" => "array",
+              "type" => type,
               "items" => {
                 "type" => "object",
-                "required" => properties.values.select(&:required).map(&:name),
-                "properties" => properties.transform_values { |property| property.to_schema[property.name] }
-              }
+                "required" => required_properties,
+                "properties" => properties.transform_values { |property| property.to_schema[property.name] },
+                "additionalProperties" => Verquest.configuration.default_additional_properties
+              }.tap do |schema|
+                schema["dependentRequired"] = dependent_required_properties if dependent_required_properties.any?
+              end
             }.merge(schema_options)
           }
         end
@@ -88,19 +99,22 @@ module Verquest
         if has_item?
           {
             name => {
-              "type" => "array",
+              "type" => type,
               "items" => item.to_validation_schema(version: version)
             }.merge(schema_options)
           }
         else
           {
             name => {
-              "type" => "array",
+              "type" => type,
               "items" => {
                 "type" => "object",
-                "required" => properties.values.select(&:required).map(&:name),
-                "properties" => properties.transform_values { |property| property.to_validation_schema(version: version)[property.name] }
-              }
+                "required" => required_properties,
+                "properties" => properties.transform_values { |property| property.to_validation_schema(version: version)[property.name] },
+                "additionalProperties" => Verquest.configuration.default_additional_properties
+              }.tap do |schema|
+                schema["dependentRequired"] = dependent_required_properties if dependent_required_properties.any?
+              end
             }.merge(schema_options)
           }
         end
@@ -128,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
@@ -141,7 +155,7 @@ module Verquest
 
       private
 
-      attr_reader :item, :schema_options, :properties
+      attr_reader :item, :schema_options, :properties, :type
     end
   end
 end

data/lib/verquest/properties/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

@@ -24,12 +24,13 @@ module Verquest
       #
       # @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 required [Boolean, Array<Symbol>] Whether this property is required, or array of dependency names (can be overridden by custom type)
+      # @param nullable [Boolean] Whether this property can be null
       # @param map [String, nil] The mapping path for this property
       # @param schema_options [Hash] Additional JSON schema options for this property (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)
+      def initialize(name:, type:, required: false, nullable: false, map: nil, **schema_options)
         raise ArgumentError, "Type must be one of #{allowed_types.join(", ")}" unless allowed_types.include?(type.to_s)
         raise ArgumentError, "You can not map fields to the root without a name" if map == "/"
 
@@ -48,14 +49,21 @@ module Verquest
         end
 
         @name = name.to_s
+        @nullable = nullable
         @map = map
+
+        if nullable
+          @type = [@type, "null"]
+        end
       end
 
       # Generate JSON schema definition for this field
       #
       # @return [Hash] The schema definition for this field
       def to_schema
-        {name => {"type" => type}.merge(schema_options)}
+        {
+          name => {"type" => type}.merge(schema_options)
+        }
       end
 
       # Create mapping for this field property
@@ -66,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/object.rb

@@ -15,16 +15,28 @@ module Verquest
       # Initialize a new Object property
       #
       # @param name [String, Symbol] The name of the property
-      # @param required [Boolean] Whether this property is required
+      # @param required [Boolean, Array<Symbol>] Whether this property is required, or array of dependency names
+      # @param nullable [Boolean] Whether this property can be null
       # @param map [String, nil] The mapping path for this property
       # @param schema_options [Hash] Additional JSON schema options for this property
-      def initialize(name:, required: false, map: nil, **schema_options)
+      def initialize(name:, required: false, nullable: false, map: nil, **schema_options)
         @properties = {}
 
         @name = name.to_s
         @required = required
+        @nullable = nullable
         @map = map
-        @schema_options = schema_options&.transform_keys(&:to_s)
+        @schema_options = {
+          additionalProperties: Verquest.configuration.default_additional_properties
+        }.merge(schema_options)
+          .delete_if { |_, v| v.nil? }
+          .transform_keys(&:to_s)
+
+        @type = if nullable
+          %w[object null]
+        else
+          "object"
+        end
       end
 
       # Add a child property to this object
@@ -41,10 +53,12 @@ module Verquest
       def to_schema
         {
           name => {
-            "type" => "object",
-            "required" => properties.values.select(&:required).map(&:name),
+            "type" => type,
+            "required" => required_properties,
             "properties" => properties.transform_values { |property| property.to_schema[property.name] }
-          }.merge(schema_options)
+          }.merge(schema_options).tap do |schema|
+            schema["dependentRequired"] = dependent_required_properties if dependent_required_properties.any?
+          end
         }
       end
 
@@ -55,10 +69,12 @@ module Verquest
       def to_validation_schema(version: nil)
         {
           name => {
-            "type" => "object",
-            "required" => properties.values.select(&:required).map(&:name),
+            "type" => type,
+            "required" => required_properties,
             "properties" => properties.transform_values { |property| property.to_validation_schema(version: version)[property.name] }
-          }.merge(schema_options)
+          }.merge(schema_options).tap do |schema|
+            schema["dependentRequired"] = dependent_required_properties if dependent_required_properties.any?
+          end
         }
       end
 

data/lib/verquest/properties/reference.rb

@@ -26,12 +26,14 @@ module Verquest
       # @param name [String, Symbol] The name of the property
       # @param from [Class] The schema class to reference
       # @param property [Symbol, nil] Optional specific property to reference
+      # @param nullable [Boolean] Whether this property can be null
       # @param map [String, nil] The mapping path for this property
-      # @param required [Boolean] Whether this property is required
-      def initialize(name:, from:, property: nil, map: nil, required: false)
+      # @param required [Boolean, Array<Symbol>] Whether this property is required, or array of dependency names
+      def initialize(name:, from:, property: nil, nullable: false, map: nil, required: false)
         @name = name.to_s
         @from = from
         @property = property
+        @nullable = nullable
         @map = map
         @required = required
       end
@@ -40,9 +42,20 @@ module Verquest
       #
       # @return [Hash] The schema definition with a $ref pointer
       def to_schema
-        {
-          name => {"$ref" => from.to_ref(property: property)}
-        }
+        if nullable
+          {
+            name => {
+              "oneOf" => [
+                {"$ref" => from.to_ref(property: property)},
+                {"type" => "null"}
+              ]
+            }
+          }
+        else
+          {
+            name => {"$ref" => from.to_ref(property: property)}
+          }
+        end
       end
 
       # Generate validation schema for this reference property
@@ -50,8 +63,14 @@ module Verquest
       # @param version [String, nil] The version to generate validation schema for
       # @return [Hash] The validation schema for this reference
       def to_validation_schema(version: nil)
+        schema = from.to_validation_schema(version:, property: property).dup
+
+        if nullable
+          schema["type"] = [schema["type"], "null"] unless schema["type"].include?("null")
+        end
+
         {
-          name => from.to_validation_schema(version:, property: property)
+          name => schema
         }
       end
 
@@ -68,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

@@ -19,6 +19,8 @@ module Verquest
   #   # Get mapping
   #   mapping = version.mapping
   class Version
+    include HelperMethods::RequiredProperties
+
     # @!attribute [r] name
     #   @return [String] The name/identifier of the version (e.g., "2023-01")
     #
@@ -36,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
@@ -102,9 +107,16 @@ module Verquest
     def prepare
       return if frozen?
 
+      unless schema_options.key?("additionalProperties")
+        schema_options["additionalProperties"] = Verquest.configuration.default_additional_properties
+      end
+
+      schema_options.delete_if { |_, v| v.nil? }
+
       prepare_schema
       prepare_validation_schema
       prepare_mapping
+      prepare_external_mapping
       @transformer = Transformer.new(mapping: mapping)
 
       freeze
@@ -197,9 +209,11 @@ module Verquest
       @schema = {
         "type" => "object",
         "description" => description,
-        "required" => properties.values.select(&:required).map(&:name),
+        "required" => required_properties,
         "properties" => properties.transform_values { |property| property.to_schema[property.name] }
-      }.merge(schema_options).freeze
+      }.merge(schema_options).tap do |schema|
+        schema["dependentRequired"] = dependent_required_properties if dependent_required_properties.any?
+      end.freeze
     end
 
     # Generates the validation schema for this version
@@ -212,9 +226,11 @@ module Verquest
       @validation_schema = {
         "type" => "object",
         "description" => description,
-        "required" => properties.values.select(&:required).map(&:name),
+        "required" => required_properties,
         "properties" => properties.transform_values { |property| property.to_validation_schema(version: name)[property.name] }
-      }.merge(schema_options).freeze
+      }.merge(schema_options).tap do |schema|
+        schema["dependentRequired"] = dependent_required_properties if dependent_required_properties.any?
+      end.freeze
     end
 
     # Prepares the parameter mapping for this version
@@ -233,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