verquest 0.6.4 → 0.7.0

data/lib/verquest/conditions/rules/property_rule.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Verquest
+  module Conditions
+    module Rules
+      # Base class for rules that constrain the value of a single property
+      #
+      # Inside `given`, the rule also requires the property. Without that,
+      # `if: {properties: {kind: {const: "x"}}}` would match when `kind` is missing.
+      #
+      # @abstract Subclass and pass the property schema to {#initialize}
+      class PropertyRule
+        # Initialize a new property rule
+        #
+        # @param name [Symbol, String] The property the rule constrains
+        # @param schema [Hash] The schema the property value must match
+        def initialize(name, schema)
+          @name = name.to_s
+          @schema = schema
+        end
+
+        # Returns the names of the properties the rule uses
+        #
+        # @return [Array<String>] The constrained property name
+        def property_names
+          [name]
+        end
+
+        # Builds the schema fragment for this rule
+        #
+        # @param in_given [Boolean] Whether the rule is used inside `given`, which also requires the property
+        # @return [Hash] The schema fragment
+        def to_schema(in_given: false)
+          fragment = {"properties" => {name => schema}}
+          in_given ? {"required" => [name]}.merge(fragment) : fragment
+        end
+
+        private
+
+        # @!attribute [r] name
+        #   @return [String] The constrained property name
+        # @!attribute [r] schema
+        #   @return [Hash] The schema the property value must match
+        attr_reader :name, :schema
+      end
+    end
+  end
+end

data/lib/verquest/conditions/rules/satisfies.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Verquest
+  module Conditions
+    module Rules
+      # Requires a property to match arbitrary schema options
+      #
+      # @example
+      #   Satisfies.new(:age, {minimum: 18}).to_schema(in_given: false)
+      #   # => {"properties" => {"age" => {"minimum" => 18}}}
+      class Satisfies < PropertyRule
+        # Initialize a new Satisfies rule
+        #
+        # @param name [Symbol, String] The property the rule constrains
+        # @param schema_options [Hash] Schema options (already camelized) the property value must match
+        def initialize(name, schema_options)
+          super(name, schema_options.transform_keys(&:to_s))
+        end
+      end
+    end
+  end
+end

data/lib/verquest/conditions/rules/value_in.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Verquest
+  module Conditions
+    module Rules
+      # Requires a property to hold one of several values
+      #
+      # @example
+      #   ValueIn.new(:kind, %w[a b]).to_schema(in_given: false)
+      #   # => {"properties" => {"kind" => {"enum" => ["a", "b"]}}}
+      class ValueIn < PropertyRule
+        # Initialize a new ValueIn rule
+        #
+        # @param name [Symbol, String] The property the rule constrains
+        # @param values [Array] The values the property may hold
+        def initialize(name, values)
+          super(name, {"enum" => values})
+        end
+      end
+    end
+  end
+end

data/lib/verquest/conditions/rules.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Verquest
+  module Conditions
+    # Rules used inside `given`, `then_apply`, `else_apply` and `depends_on`
+    #
+    # Each rule names properties of the scope its condition belongs to and
+    # builds a JSON Schema fragment. Every rule responds to `#property_names`
+    # (used to catch unknown names) and `#to_schema(in_given:)`.
+    #
+    # @see Verquest::Conditions::RuleSet Combines the rules of one block
+    module Rules
+      # This module is a namespace for the rule classes
+      # Each rule is defined in its own file under lib/verquest/conditions/rules/
+    end
+  end
+end

data/lib/verquest/conditions.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Verquest
+  # Conditional schemas (`if` / `then` / `else`)
+  #
+  # A condition tests which keys a payload has and what values they hold, and
+  # applies one of two branches. Branches can declare properties and rules.
+  # Branch properties are listed at the scope level, next to the regular
+  # properties, and the branches only get rules (`required`, `name: false`, ...).
+  #
+  # @example Price adjustment with two variants
+  #   class PriceAdjustmentRequest < Verquest::Base
+  #     version "2025-09" do
+  #       field :effective_from, type: :string, required: true
+  #
+  #       condition :pricing do
+  #         given { present :percentages }
+  #         then_apply do
+  #           object :percentages, required: true do
+  #             field :unit_types, type: :number
+  #           end
+  #         end
+  #         else_apply do
+  #           field :percentage, type: :number, required: true
+  #         end
+  #       end
+  #     end
+  #   end
+  #
+  # @see Verquest::Conditions::Condition
+  # @see Verquest::HelperMethods::ConditionalProperties
+  module Conditions
+    # This module is a namespace for the condition classes
+    # Each class is defined in its own file under lib/verquest/conditions/
+  end
+end

data/lib/verquest/configuration.rb

@@ -15,6 +15,9 @@ module Verquest
   class Configuration
     include Base::HelperClassMethods
 
+    # JSON Schema versions without the `const` keyword
+    VERSIONS_WITHOUT_CONST = %i[draft4 openapi30].freeze
+
     # Mapping of supported JSON Schema versions to their implementation classes
     #
     # This constant maps the symbolic names of JSON Schema versions to their
@@ -58,8 +61,13 @@ module Verquest
     # @!attribute [rw] default_additional_properties
     #   Controls the default behavior for handling properties not defined in the schema
     #   @return [Boolean] false to disallow additional properties (default), true to allow them
+    #
+    # @!attribute [rw] query_array_explode
+    #   Default explode value of array properties in query requests (`location :query`)
+    #   @return [Boolean] true for repeated keys like `status[]=a&status[]=b` (default), false for comma-separated values like `status=a,b`
     attr_accessor :validate_params, :json_schema_version, :validation_error_handling,
-      :remove_extra_root_keys, :insert_property_defaults, :default_additional_properties
+      :remove_extra_root_keys, :insert_property_defaults, :default_additional_properties,
+      :query_array_explode
 
     # @!attribute [r] current_version
     #   A callable object that returns the current API version to use when not explicitly specified
@@ -86,6 +94,7 @@ module Verquest
       @insert_property_defaults = true
       @custom_field_types = {}
       @default_additional_properties = false
+      @query_array_explode = true
     end
 
     # Sets the current version strategy using a callable object
@@ -151,6 +160,15 @@ module Verquest
       SCHEMAS[json_schema_version] || raise(ArgumentError, "Unsupported JSON Schema version: #{json_schema_version}")
     end
 
+    # Checks whether the configured JSON Schema version has the `const` keyword
+    #
+    # Draft 4 and OpenAPI 3.0 don't, so a constant is written as a one-value `enum` there.
+    #
+    # @return [Boolean] False for draft 4 and OpenAPI 3.0
+    def const_keyword?
+      !VERSIONS_WITHOUT_CONST.include?(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

data/lib/verquest/gem_version.rb

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

data/lib/verquest/helper_methods/conditional_properties.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Verquest
+  module HelperMethods
+    # Module that adds conditions (`if` / `then` / `else`) to a scope
+    #
+    # Included in Version, Properties::Object and Properties::Collection (inline
+    # items). The including class must set `@conditions = []` and have a
+    # `properties` hash.
+    #
+    # The branch properties of all conditions are listed next to the regular
+    # properties ({#all_properties}), so `additionalProperties` keeps working and
+    # the mapping is the flat union of both. The scope schema gets the
+    # condition's `if` / `then` / `else` keywords, or one `allOf` entry per
+    # condition when there are several.
+    module ConditionalProperties
+      # Schema options that can't be combined with conditions
+      RESERVED_KEYWORDS = %w[if then else allOf].freeze
+
+      # JSON Schema versions that ignore `if` / `then` / `else` and would accept every payload
+      UNSUPPORTED_DIALECTS = %i[draft4 draft6 openapi30].freeze
+
+      # @!attribute [r] conditions
+      #   @return [Array<Verquest::Conditions::Condition>] The conditions in declaration order
+      attr_reader :conditions
+
+      # Add a condition to this scope
+      #
+      # A named condition can be declared only once per scope. To replace an
+      # inherited one, call `exclude_conditions` first.
+      #
+      # @param condition [Verquest::Conditions::Condition] The condition to add
+      # @return [Array<Verquest::Conditions::Condition>] The conditions
+      # @raise [ArgumentError] If a condition with the same name is already defined
+      def add_condition(condition)
+        raise ArgumentError, "Condition '#{condition.name}' is already defined" if condition.name && conditions.any? { |other| other.name == condition.name }
+
+        conditions << condition
+      end
+
+      # Remove a named condition from this scope
+      #
+      # @param name [Symbol, String] The condition name
+      # @return [Verquest::Conditions::Condition] The removed condition
+      # @raise [ArgumentError] If no condition has that name
+      def remove_condition(name)
+        condition = conditions.find { |candidate| candidate.name == name.to_s }
+        raise ArgumentError, "Condition '#{name}' is not defined" unless condition
+
+        conditions.delete(condition)
+      end
+
+      # Returns the regular properties followed by the branch properties
+      #
+      # Computed on every call, so it always reflects the current declarations.
+      #
+      # @return [Hash<String, Verquest::Properties::Base>] All properties listed in the scope schema
+      # @raise [ArgumentError] If a branch property clashes with another declaration
+      def all_properties
+        properties.merge(conditional_properties)
+      end
+
+      private
+
+      # Merges the branch properties of all conditions
+      #
+      # @return [Hash<String, Verquest::Properties::Base>] The branch properties
+      # @raise [ArgumentError] If a branch property clashes with another declaration
+      def conditional_properties
+        Conditions::PropertyMerge.call(conditions.map(&:properties)).tap { |branch_properties| check_property_clashes!(branch_properties) }
+      end
+
+      # Checks that no branch property is also declared on the scope
+      #
+      # @param branch_properties [Hash<String, Verquest::Properties::Base>] The branch properties
+      # @return [void]
+      # @raise [ArgumentError] If a branch property is also declared on the scope
+      def check_property_clashes!(branch_properties)
+        clash = branch_properties.keys.find { |name| properties.key?(name) }
+        raise ArgumentError, "Property '#{clash}' is declared both outside and inside a condition" if clash
+      end
+
+      # Adds the conditional keywords to a scope schema
+      #
+      # In documentation, a condition declared with `document_as: :one_of`
+      # replaces the schema with a oneOf of its branches instead.
+      #
+      # @param schema [Hash] The scope schema, changed in place
+      # @param documentation [Boolean] Whether the schema is the documented one (`to_schema`)
+      # @return [Hash] The schema
+      # @raise [ArgumentError] If a condition is invalid or the schema already has conditional keywords
+      def add_conditions(schema, documentation: false)
+        return schema if conditions.empty?
+
+        validate_conditions(schema)
+        return schema.replace(conditions.first.to_one_of_schema(schema)) if documentation && conditions.first.document_as
+
+        schema.merge!(conditions_schema)
+      end
+
+      # Checks the conditions before they are added to the schema
+      #
+      # @param schema [Hash] The scope schema
+      # @return [void]
+      # @raise [ArgumentError] If the JSON Schema version ignores conditions, the schema already
+      #   has conditional keywords, a condition documented as one_of is not alone, or a condition is invalid
+      def validate_conditions(schema)
+        dialect = Verquest.configuration.json_schema_version
+        raise ArgumentError, "Conditions need json_schema_version draft7 or later, or openapi31 (got #{dialect})" if UNSUPPORTED_DIALECTS.include?(dialect)
+        raise ArgumentError, "Raw if, then, else or allOf schema options can not be combined with conditions" if schema.keys.intersect?(RESERVED_KEYWORDS)
+        raise ArgumentError, "A condition documented as one_of must be the only condition in its version" if conditions.size > 1 && conditions.any?(&:document_as)
+
+        conditions.each { |condition| condition.validate!(all_properties.keys) }
+      end
+
+      # Builds the conditional keywords
+      #
+      # @return [Hash] `if` / `then` / `else` for one condition, `allOf` for several
+      def conditions_schema
+        return conditions.first.to_schema if conditions.one?
+
+        {"allOf" => conditions.map(&:to_schema)}
+      end
+    end
+  end
+end

data/lib/verquest/helper_methods/unnamed_one_of.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Verquest
+  module HelperMethods
+    # Checks that an unnamed oneOf is the only property in its scope
+    #
+    # An unnamed oneOf stands for the whole scope: the version, or a
+    # collection item. Its variants have nowhere to go next to other
+    # properties, so that is rejected when the properties are declared.
+    module UnnamedOneOf
+      # The error raised for an unnamed oneOf next to other properties
+      MESSAGE = "An unnamed one_of must be the only property in its scope. Give it a name: to declare it next to other properties"
+
+      private
+
+      # @param property [Verquest::Properties::Base] The property being added
+      # @return [void]
+      # @raise [ArgumentError] If an unnamed oneOf would share the scope with other properties
+      def check_unnamed_one_of(property)
+        # A property with the same name replaces the existing one, as in an inheriting version
+        others = properties.values.reject { |other| other.name.to_s == property.name.to_s }
+        return if others.empty?
+        return unless unnamed_one_of?(property) || others.any? { |other| unnamed_one_of?(other) }
+
+        raise ArgumentError, MESSAGE
+      end
+
+      # @param property [Verquest::Properties::Base] The property
+      # @return [Boolean] True for a oneOf without a name
+      def unnamed_one_of?(property)
+        property.is_a?(Properties::OneOf) && property.name.nil?
+      end
+    end
+  end
+end

data/lib/verquest/properties/array.rb

@@ -15,6 +15,9 @@ module Verquest
     #     required: true
     #   )
     class Array < Base
+      # @return [Boolean] In query requests, whether items are sent as repeated keys (true) or comma-separated (false)
+      attr_reader :explode
+
       # Initialize a new Array property
       #
       # @param name [String, Symbol] The name of the property
@@ -22,11 +25,12 @@ module Verquest
       # @param map [String, nil] The mapping path for this property (nil for no explicit mapping)
       # @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 explode [Boolean, nil] In query requests, whether items are sent as repeated keys (true) or comma-separated (false); nil uses the configuration
       # @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, nullable: false, item_schema_options: {}, **schema_options)
+      def initialize(name:, type:, map: nil, required: false, nullable: false, explode: nil, 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 == "/"
 
@@ -46,6 +50,7 @@ module Verquest
         @map = map
         @required = required
         @nullable = nullable
+        @explode = explode.nil? ? Verquest.configuration.query_array_explode : explode
         @schema_options = schema_options&.transform_keys(&:to_s)
 
         @type = if nullable
@@ -78,6 +83,15 @@ module Verquest
         mapping[(key_prefix + [name]).join("/")] = mapping_value_key(value_prefix:)
       end
 
+      # Returns this array's explode value and parameter examples
+      #
+      # @param prefix [Array<String>] Path of the parent property
+      # @param version [String] The version to resolve references with
+      # @return [Hash{Array<String> => Hash}] The options of this array, by path
+      def query_options(prefix:, version:)
+        {prefix + [name] => {explode:, examples: parameter_examples}.compact}
+      end
+
       private
 
       attr_reader :type, :item_type, :schema_options, :item_schema_options

data/lib/verquest/properties/base.rb

@@ -21,7 +21,9 @@ module Verquest
       #   @return [Boolean] Whether this property is required
       # @!attribute [rw] map
       #   @return [String, nil] The mapping path for this property
-      attr_accessor :name, :required, :map
+      # @!attribute [rw] parameter_examples
+      #   @return [Hash, nil] Named OpenAPI Example Objects for this property's query parameter, kept out of the JSON schemas
+      attr_accessor :name, :required, :map, :parameter_examples
 
       # Adds a child property to this property
       # @abstract
@@ -58,6 +60,54 @@ module Verquest
         raise NoMethodError
       end
 
+      # Adds this property to a transformer layout
+      #
+      # This is the layout of a scalar property: one source and target pair.
+      # Objects, collections, references and oneOfs override it.
+      #
+      # @param key_prefix [Array<String>] Prefix for the source key
+      # @param value_prefix [Array<String>] Prefix for the target value
+      # @param layout [Verquest::Transformer::Layout] The layout to add to
+      # @param version [String, nil] The version to create the layout for
+      # @return [void]
+      def layout(key_prefix:, value_prefix:, layout:, version:)
+        layout.add_pair((key_prefix + [name]).join("/"), mapping_value_key(value_prefix:))
+      end
+
+      # Returns the query parameter options under this property, by path
+      #
+      # Options are `explode:` for arrays and `examples:` for properties with
+      # parameter examples. Paths without options are left out.
+      #
+      # @param prefix [Array<String>] Path of the parent property
+      # @param version [String] The version to resolve references with
+      # @return [Hash{Array<String> => Hash}] The options of each property path
+      def query_options(prefix:, version:)
+        parameter_examples ? {prefix + [name] => {examples: parameter_examples}} : {}
+      end
+
+      # Returns a copy of this property under another name and map:
+      #
+      # Used by a reference to a single property, so the property maps as if
+      # it were declared where the reference is.
+      #
+      # @param name [String, Symbol] The new name
+      # @param map [String, nil] The new map: option
+      # @return [Verquest::Properties::Base] The renamed copy
+      def renamed(name:, map:)
+        dup.tap { |copy| copy.rename(name, map) }
+      end
+
+      protected
+
+      # @param name [String, Symbol] The new name
+      # @param map [String, nil] The new map: option
+      # @return [void]
+      def rename(name, map)
+        @name = name.to_s
+        @map = map
+      end
+
       private
 
       # @!attribute [r] nullable
@@ -75,10 +125,9 @@ module Verquest
 
       # 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?
+      def mapping_value_key(value_prefix:)
+        if map.nil?
           (value_prefix + [name]).join("/")
         elsif map == "/"
           ""
@@ -87,12 +136,6 @@ module Verquest
         else
           (value_prefix + map.split("/")).join("/")
         end
-
-        if collection
-          value_key + "[]"
-        else
-          value_key
-        end
       end
 
       # Determines the mapping target value prefix based on mapping configuration
@@ -117,6 +160,57 @@ module Verquest
 
         value_prefix
       end
+
+      # Adds the mapping of a child property
+      #
+      # A oneOf gets its own mapping in the `_oneOfs` array, so its metadata
+      # can't clash with another oneOf in the same mapping.
+      #
+      # @param property [Verquest::Properties::Base] The child property
+      # @param mapping [Hash] The mapping hash to be updated
+      # @param options [Hash] The key_prefix, value_prefix and version for the child mapping
+      # @return [void]
+      def add_child_mapping(property, mapping:, **options)
+        return property.mapping(mapping:, **options) unless property.is_a?(OneOf)
+
+        one_of_mapping = {}
+        property.mapping(mapping: one_of_mapping, **options)
+        (mapping["_oneOfs"] ||= []) << one_of_mapping
+      end
+
+      # Adds the mappings of a referenced request's properties under the given prefixes
+      #
+      # Each property maps itself with the prefixes, instead of the finished
+      # mapping of the request being copied, so its oneOfs keep their
+      # metadata and land in `_oneOfs`.
+      #
+      # @param request [Class<Verquest::Base>] The referenced request
+      # @param key_prefix [Array<String>] Prefix for the source keys
+      # @param value_prefix [Array<String>] Prefix for the target values
+      # @param mapping [Hash] The mapping hash to be updated
+      # @param version [String] The version to create mapping for
+      # @return [void]
+      def add_request_mapping(request, key_prefix:, value_prefix:, mapping:, version:)
+        referenced = request.resolve(version)
+        referenced.all_properties.each_value do |property|
+          add_child_mapping(property, key_prefix:, value_prefix:, mapping:, version: referenced.name)
+        end
+      end
+
+      # Adds a referenced request's properties to a layout under the given prefixes
+      #
+      # @param request [Class<Verquest::Base>] The referenced request
+      # @param key_prefix [Array<String>] Prefix for the source keys
+      # @param value_prefix [Array<String>] Prefix for the target values
+      # @param layout [Verquest::Transformer::Layout] The layout to add to
+      # @param version [String] The version to create the layout for
+      # @return [void]
+      def add_request_layout(request, key_prefix:, value_prefix:, layout:, version:)
+        referenced = request.resolve(version)
+        referenced.all_properties.each_value do |property|
+          property.layout(key_prefix:, value_prefix:, layout:, version: referenced.name)
+        end
+      end
     end
   end
 end