verquest 0.6.3 → 0.7.0

data/lib/verquest/transformer/mapping_layout.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+module Verquest
+  class Transformer
+    # Turns a mapping hash into a Layout
+    #
+    # A mapping is flat, holds a single oneOf (variant mappings that repeat
+    # the other properties, plus metadata keys), or several oneOfs (`_oneOfs`).
+    # The oneOf paths and collection targets the hash doesn't hold are worked
+    # out from its paths. Only the deprecated `Transformer.new(mapping:)` uses
+    # it; versions build their layout from their properties.
+    #
+    # @deprecated Removed in 1.0.0 together with `Transformer.new(mapping:)`
+    #
+    # Internal to the transformer, not part of the public API.
+    class MappingLayout
+      # Builds the layout of a mapping
+      #
+      # @param mapping [Hash] The mapping in any of its formats
+      # @param discriminator [String, Symbol, nil] The discriminator of a root-level oneOf
+      # @return [Layout] The layout
+      def self.call(mapping, discriminator: nil)
+        new(mapping, discriminator&.to_s).layout
+      end
+
+      private_class_method :new
+
+      # @!attribute [r] layout
+      #   @return [Layout] The layout of the mapping
+      attr_reader :layout
+
+      # @param mapping [Hash] The mapping in any of its formats
+      # @param discriminator [String, nil] The discriminator of a root-level oneOf
+      def initialize(mapping, discriminator)
+        @layout = Layout.new
+        pairs, one_ofs = split(mapping, discriminator)
+        pairs.each { |source, target| layout.add_pair(source, target) }
+        one_ofs.each { |one_of| layout.add_one_of(one_of) }
+        one_ofs.each { |one_of| add_collections(one_of.path, one_ofs, pairs) }
+      end
+
+      private
+
+      # Splits a mapping into its source and target pairs and its oneOfs
+      #
+      # @param mapping [Hash] The mapping in any of its formats
+      # @param discriminator [String, nil] The discriminator of a root-level oneOf
+      # @return [Array(Hash, Array<Layout::OneOfLayout>)] The pairs and the oneOfs
+      def split(mapping, discriminator)
+        pairs = mapping.reject { |key, value| METADATA_KEYS.include?(key) || value.is_a?(Hash) }
+        return [pairs, mapping["_oneOfs"].map { |one_of| one_of_layout(one_of) }] if mapping.key?("_oneOfs")
+        return [pairs, []] unless discriminator || mapping.key?("_discriminator") || mapping.key?("_variant_schemas")
+
+        single = mapping.except(*pairs.keys)
+        single = single.merge("_discriminator" => discriminator) if discriminator
+        one_of = one_of_layout(single)
+        [pairs.merge(shared_pairs(single, one_of.path)), [one_of]]
+      end
+
+      # Builds the layout of a oneOf mapping
+      #
+      # @param mapping [Hash] The oneOf mapping, with metadata keys
+      # @return [Layout::OneOfLayout] The oneOf layout
+      def one_of_layout(mapping)
+        variants = variant_mappings(mapping)
+        path = one_of_path(mapping, variants)
+        discriminator = mapping["_discriminator"]
+
+        Layout::OneOfLayout.new(
+          path:,
+          discriminator:,
+          variants: variants.transform_values { |pairs| variant_layout(pairs, path) },
+          variant_schemas: (mapping["_variant_schemas"] unless discriminator),
+          null_target: mapping["_nullable_target_path"]
+        )
+      end
+
+      # Builds the layout of a variant from its pairs inside the oneOf
+      #
+      # @param pairs [Hash] The variant mapping
+      # @param path [String] The oneOf source path
+      # @return [Layout] The variant layout
+      def variant_layout(pairs, path)
+        layout.variant.tap do |variant|
+          # A Hash target is a oneOf nested in the variant, which the mapping formats can't express
+          pairs.each { |source, target| variant.add_pair(source, target) if target.is_a?(String) && inside?(source, path) }
+        end
+      end
+
+      # Returns the variant mappings of a oneOf mapping
+      #
+      # @param mapping [Hash] The oneOf mapping
+      # @return [Hash<String, Hash>] Source and target pairs by variant name
+      def variant_mappings(mapping)
+        mapping.select { |key, value| !METADATA_KEYS.include?(key) && value.is_a?(Hash) }
+      end
+
+      # Returns the pairs a single-oneOf mapping repeats in every variant
+      #
+      # @param mapping [Hash] The oneOf mapping
+      # @param path [String] The oneOf source path
+      # @return [Hash] The pairs outside the oneOf property
+      def shared_pairs(mapping, path)
+        return {} if path.empty?
+
+        variant_mappings(mapping).values.first.reject { |source, _| inside?(source, path) }
+      end
+
+      # Returns the source path of a oneOf property
+      #
+      # Taken from the discriminator, the variant path or the nullable path.
+      # Otherwise, the oneOf is at the root, or at the items of the collection
+      # all its properties are in.
+      #
+      # @param mapping [Hash] The oneOf mapping
+      # @param variants [Hash<String, Hash>] Source and target pairs by variant name
+      # @return [String] The source path, empty for a root-level oneOf
+      def one_of_path(mapping, variants)
+        return mapping["_discriminator"].rpartition("/").first if mapping["_discriminator"]
+        return mapping["_variant_path"] || mapping["_nullable_path"] if mapping.key?("_variant_path") || mapping.key?("_nullable_path")
+
+        sources = variants.values.flat_map(&:keys)
+        collection = sources.first.include?("[]") ? "#{sources.first.split("[]").first}[]" : ""
+        (!collection.empty? && sources.all? { |source| inside?(source, collection) }) ? collection : ""
+      end
+
+      # Adds the collections a oneOf path enters, with their target paths
+      #
+      # @param path [String] The oneOf source path
+      # @param one_ofs [Array<Layout::OneOfLayout>] All oneOfs
+      # @param pairs [Hash] The source and target pairs outside the oneOfs
+      # @return [void]
+      def add_collections(path, one_ofs, pairs)
+        1.upto(path.scan("[]").size) do |depth|
+          prefix = "#{path.split("[]").first(depth).join("[]")}[]"
+          layout.add_collection(prefix, target_collection(prefix, one_ofs, pairs)) unless layout.collections.key?(prefix)
+        end
+      end
+
+      # Returns the target path of a collection, which differs when it uses map:
+      #
+      # Found from a property mapped inside the collection, so a property moved
+      # out of it with map: "/..." doesn't count.
+      #
+      # @param prefix [String] The collection source path, ending with "[]"
+      # @param one_ofs [Array<Layout::OneOfLayout>] All oneOfs
+      # @param pairs [Hash] The source and target pairs outside the oneOfs
+      # @return [String] The collection target path, ending with "[]"
+      def target_collection(prefix, one_ofs, pairs)
+        depth = prefix.scan("[]").size
+        candidates = one_ofs.flat_map { |one_of| one_of.variants.values.flat_map { |variant| variant.pairs.to_a } } + pairs.to_a
+        _, target = candidates.find { |source, target_path| inside?(source, prefix) && target_path.scan("[]/").size >= depth }
+        target ? "#{target.split("[]/").first(depth).join("[]/")}[]" : prefix
+      end
+
+      # Checks whether a path is inside another one
+      #
+      # @param path [String] The path
+      # @param prefix [String] The containing path, empty for the root
+      # @return [Boolean] True if the path is below the prefix
+      def inside?(path, prefix)
+        prefix.empty? || path.start_with?("#{prefix}/")
+      end
+    end
+  end
+end

data/lib/verquest/transformer/one_of.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Verquest
+  class Transformer
+    # One oneOf in a mapping, with the variant mapping each input selects
+    #
+    # Paths are relative to the scope the oneOf is resolved in: the params, or
+    # a collection item.
+    #
+    # @example
+    #   one_of = OneOf.new(
+    #     path: Path.new("pet"),
+    #     discriminator: Path.new("pet/type"),
+    #     variants: {"dog" => Scope.new(pairs: [[Path.new("pet/bark"), Path.new("pet/bark")]], one_ofs: [], collections: [])}
+    #   )
+    #   one_of.variant_for({"pet" => {"type" => "dog", "bark" => true}}) # => the "dog" scope
+    #
+    # Internal to the transformer, not part of the public API.
+    class OneOf
+      # An empty list of pairs, oneOfs or collections
+      NONE = [].freeze
+
+      # The variant of an absent oneOf
+      NO_VARIANT = Scope.new(pairs: NONE, one_ofs: NONE, collections: NONE)
+
+      # Initialize a new OneOf
+      #
+      # @param path [Path] The oneOf property, empty for a oneOf at the scope root
+      # @param variants [Hash<String, Scope>] The scope of each variant by name
+      # @param discriminator [Path, nil] The discriminator property
+      # @param variant_schemas [Hash<String, Hash>, nil] Validation schemas by variant name, without a discriminator
+      # @param null_target [Path, nil] Where a null oneOf goes, defaults to the oneOf path
+      def initialize(path:, variants:, discriminator: nil, variant_schemas: nil, null_target: nil)
+        @path = path
+        @variants = variants
+        @discriminator = discriminator
+        @schemers = variant_schemas&.transform_values { |schema| schemer(schema) }
+        @null_variant = path.empty? ? NO_VARIANT : Scope.new(pairs: [[path, null_target || path].freeze].freeze, one_ofs: NONE, collections: NONE)
+        freeze
+      end
+
+      # Returns the scope of the variant the data selects
+      #
+      # An absent oneOf maps nothing, and a null one maps only the null.
+      #
+      # @param data [Object] The scope data holding the oneOf
+      # @return [Scope] The variant scope
+      # @raise [Verquest::MappingError] If no variant or more than one variant matches
+      def variant_for(data)
+        value = path.extract(data)
+        return NO_VARIANT if value.equal?(Path::NOT_FOUND)
+        return null_variant if value.nil?
+
+        variants.fetch(discriminator ? discriminated_variant(data) : inferred_variant(value))
+      end
+
+      private
+
+      # @!attribute [r] path
+      #   @return [Path] The oneOf property
+      # @!attribute [r] variants
+      #   @return [Hash<String, Scope>] The scope of each variant by name
+      # @!attribute [r] discriminator
+      #   @return [Path, nil] The discriminator property
+      # @!attribute [r] schemers
+      #   @return [Hash<String, JSONSchemer::Schema>, nil] Schemers by variant name
+      # @!attribute [r] null_variant
+      #   @return [Scope] The variant of a null oneOf
+      attr_reader :path, :variants, :discriminator, :schemers, :null_variant
+
+      # Compiles a variant schema in the configured JSON Schema version, like the validation schema
+      #
+      # @param schema [Hash] The variant validation schema
+      # @return [JSONSchemer::Schema] The schemer
+      def schemer(schema)
+        configuration = Verquest.configuration
+        schema = ConstAsEnum.call(schema) unless configuration.const_keyword?
+        JSONSchemer.schema(schema, meta_schema: configuration.json_schema_uri)
+      end
+
+      # @param data [Object] The scope data holding the oneOf
+      # @return [String] The variant named by the discriminator value
+      # @raise [Verquest::MappingError] If the value is missing or unknown
+      def discriminated_variant(data)
+        value = discriminator.extract(data)
+        raise Verquest::MappingError, "Missing discriminator \"#{discriminator}\" for oneOf." if value.nil? || value.equal?(Path::NOT_FOUND)
+
+        name = value.to_s
+        return name if variants.key?(name)
+
+        raise Verquest::MappingError, "Unknown discriminator value \"#{value}\" for oneOf. No matching variant found."
+      end
+
+      # @param value [Object] The oneOf value
+      # @return [String] The only variant whose schema the value matches
+      # @raise [Verquest::MappingError] If no variant or more than one variant matches
+      def inferred_variant(value)
+        matches = []
+        schemers.each do |name, schemer|
+          matches << name if schemer.valid?(value)
+          break if matches.size == 2 # Two matches are enough to know the input is ambiguous
+        end
+        return matches.first if matches.one?
+        raise Verquest::MappingError, "No matching schema found for oneOf. Input does not match any of the defined schemas." if matches.empty?
+
+        raise Verquest::MappingError, "Ambiguous oneOf match. Input matches multiple schemas: #{matches.join(", ")}. " \
+          "Consider adding a discriminator or making schemas mutually exclusive."
+      end
+    end
+  end
+end

data/lib/verquest/transformer/path.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module Verquest
+  class Transformer
+    # A parsed slash-separated path, like "user/addresses[]/zip"
+    #
+    # A part ending with "[]" is an array: reading it reads every item, and
+    # writing it writes every item at its position. Paths are parsed once,
+    # when the transformer is built, and reading or writing allocates only
+    # the values and hashes it returns.
+    #
+    # @example
+    #   path = Path.new("users[]/name")
+    #   path.extract({"users" => [{"name" => "A"}, {}]}) # => ["A", Path::NOT_FOUND]
+    #   path.set({}, ["A", Path::NOT_FOUND]) # => {"users" => [{"name" => "A"}, {}]}
+    #
+    # Internal to the transformer, not part of the public API.
+    class Path
+      # Returned when a key is not in the data, to tell it apart from a null value
+      NOT_FOUND = Object.new.freeze
+
+      # A value below an explicit null in the data
+      #
+      # Returned by #extract with `nulls: true` when a parent of the path is
+      # null, so the matching part of the target path can be set to null too.
+      #
+      # @!attribute [r] depth_below
+      #   @return [Integer] How many path parts are below the null parent
+      NullParent = Data.define(:depth_below)
+
+      # One part of a path
+      #
+      # @!attribute [r] key
+      #   @return [String] The hash key
+      # @!attribute [r] array
+      #   @return [Boolean] Whether the key holds an array
+      Part = Data.define(:key, :array)
+
+      # @!attribute [r] to_s
+      #   @return [String] The path as given
+      # @!attribute [r] parts
+      #   @return [Array<Part>] The parsed parts
+      attr_reader :to_s, :parts
+
+      # @param path [String] The slash-separated path
+      def initialize(path)
+        @to_s = path.dup.freeze
+        @parts = path.split("/").map { |part| Part.new(key: part.delete_suffix("[]"), array: part.end_with?("[]")) }.freeze
+        # One NullParent per part, so reading a null allocates nothing
+        @null_parents = Array.new(parts.length) { |index| NullParent.new(depth_below: parts.length - index - 1) }.freeze
+        @last = parts.length - 1
+        freeze
+      end
+
+      # @return [Boolean] True for the empty path, which reads the data itself
+      def empty?
+        parts.empty?
+      end
+
+      # Reads the value at this path
+      #
+      # @param data [Object] The data to read from
+      # @param nulls [Boolean] Whether to return a NullParent for a value below an explicit null
+      # @return [Object, NullParent, NOT_FOUND] The value, an array of values for array parts, or NOT_FOUND
+      def extract(data, nulls: false)
+        extract_at(data, 0, nulls)
+      end
+
+      # Writes a value at this path
+      #
+      # Every item of an array keeps its position, even when none of its
+      # values are present, so empty items stay empty hashes. A NullParent
+      # sets the matching part of this path to null, unless it already has a value.
+      #
+      # @param result [Hash] The hash to write to
+      # @param value [Object, NullParent] The value, or an array of values for array parts
+      # @return [Hash] The result
+      def set(result, value)
+        set_at(result, value, 0)
+      end
+
+      private
+
+      # @!attribute [r] null_parents
+      #   @return [Array<NullParent>] The NullParent for a null at each part
+      # @!attribute [r] last
+      #   @return [Integer] The index of the last part
+      attr_reader :null_parents, :last
+
+      # @param data [Object] The data to read from
+      # @param index [Integer] The current part
+      # @param nulls [Boolean] Whether to return a NullParent below an explicit null
+      # @return [Object, NullParent, NOT_FOUND] The value
+      def extract_at(data, index, nulls)
+        return data if index > last
+
+        case data
+        when Hash then extract_from_hash(data, index, nulls)
+        # An array reached by a part without "[]" is read item by item
+        when Array then data.map { |item| extract_at(item, index, nulls) }
+        else NOT_FOUND
+        end
+      end
+
+      # @param data [Hash] The hash to read from
+      # @param index [Integer] The current part
+      # @param nulls [Boolean] Whether to return a NullParent below an explicit null
+      # @return [Object, NullParent, NOT_FOUND] The value
+      def extract_from_hash(data, index, nulls)
+        part = parts[index]
+        value = data.fetch(part.key) { return NOT_FOUND }
+        return null_parents[index] if value.nil? && nulls && index < last
+        return value.map { |item| extract_at(item, index + 1, nulls) } if part.array && value.is_a?(Array)
+
+        extract_at(value, index + 1, nulls)
+      end
+
+      # @param result [Hash] The hash to write to
+      # @param value [Object, NullParent] The value
+      # @param index [Integer] The current part
+      # @return [Hash] The result
+      def set_at(result, value, index)
+        return set_null(result, index, [last - value.depth_below, index].max) if value.is_a?(NullParent)
+
+        part = parts[index]
+        if index == last
+          result[part.key] = value.is_a?(Array) ? plain(value) : value
+        elsif part.array && value.is_a?(Array)
+          set_items(result[part.key] ||= [], value, index + 1)
+        else
+          set_at(result[part.key] ||= {}, value, index + 1)
+        end
+        result
+      end
+
+      # @param items [Array<Hash>] The array to write to
+      # @param values [Array<Object>] The values, one per item
+      # @param index [Integer] The part below the array
+      # @return [void]
+      def set_items(items, values, index)
+        values.each_with_index do |value, position|
+          item = (items[position] ||= {})
+          set_at(item, value, index) unless value.equal?(NOT_FOUND)
+        end
+      end
+
+      # Turns the markers in an array of values into nulls
+      #
+      # An array of values reaches the last part when a property is moved out
+      # of collection items with map: "/...". Items without the value keep
+      # their position as null.
+      #
+      # @param values [Array<Object>] The values, possibly nested
+      # @return [Array<Object>] The values with NOT_FOUND and NullParent as nil
+      def plain(values)
+        # Most arrays are array fields without markers, which are kept as they are
+        return values unless values.any? { |value| value.is_a?(Array) || value.is_a?(NullParent) || value.equal?(NOT_FOUND) }
+
+        values.map do |value|
+          case value
+          when Array then plain(value)
+          when NullParent, NOT_FOUND then nil
+          else value
+          end
+        end
+      end
+
+      # Sets the part at null_index to null, unless it already has a value
+      #
+      # The null goes as many parts above the end of this path as it is above
+      # the end of the source path, but never above the current part.
+      #
+      # @param result [Hash] The hash to write to
+      # @param index [Integer] The current part
+      # @param null_index [Integer] The part to set to null
+      # @return [Hash] The result
+      def set_null(result, index, null_index)
+        node = result
+        index.upto(null_index - 1) do |position|
+          node = (node[parts[position].key] ||= {})
+          return result unless node.is_a?(Hash)
+        end
+        node[parts[null_index].key] = nil unless node.key?(parts[null_index].key)
+        result
+      end
+    end
+  end
+end

data/lib/verquest/transformer/plan.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module Verquest
+  class Transformer
+    # Groups a Layout into the scopes the transformer applies
+    #
+    # The plan is a scope for the params, with a nested scope for the items
+    # of each collection that holds a oneOf, since every item can select a
+    # different variant. Paths in a collection scope are relative to the item.
+    # A oneOf variant is a scope with the same prefixes as the scope holding
+    # the oneOf.
+    #
+    # @example
+    #   plan = Plan.new(layout)
+    #   plan.root # => Scope with the params pairs, oneOfs and collections
+    #
+    # Internal to the transformer, not part of the public API.
+    class Plan
+      # The collection prefixes the paths of a scope are relative to
+      #
+      # @!attribute [r] source
+      #   @return [String] The source collection path ending with "[]", empty for the params
+      # @!attribute [r] target
+      #   @return [String] The target collection path ending with "[]", empty for the params
+      Prefix = Data.define(:source, :target)
+
+      # The prefix of the params scope
+      ROOT = Prefix.new(source: "", target: "")
+
+      private_constant :Prefix, :ROOT
+
+      # @!attribute [r] root
+      #   @return [Scope] The mapping of the params
+      attr_reader :root
+
+      # Builds the plan
+      #
+      # @param layout [Layout] The full paths of the request. Each layout must list every collection a oneOf path in it enters.
+      # @raise [Verquest::MappingError] If map: moves a oneOf variant property out of its collection item
+      def initialize(layout)
+        @paths = {}
+        @root = build_scope(layout.pairs, layout.one_ofs, ROOT, layout.collections)
+      end
+
+      private
+
+      # Returns the target path of a collection
+      #
+      # @param collections [Hash<String, String>] Target path by source path of each collection
+      # @param source [String] The collection source path, ending with "[]"
+      # @return [String] The collection target path, ending with "[]"
+      # @raise [ArgumentError] If the layout doesn't list the collection
+      def collection_target(collections, source)
+        collections.fetch(source) { raise ArgumentError, "The layout doesn't list the collection #{source}" }
+      end
+
+      # Builds a scope, with paths relative to the prefix
+      #
+      # The oneOfs inside a collection of this scope go to a nested scope for
+      # that collection's items, with the pairs mapped into those items. A pair
+      # moved out of the items with map: "/..." stays here.
+      #
+      # @param pairs [Hash] The source and target pairs in this scope
+      # @param one_ofs [Array<Layout::OneOfLayout>] The oneOfs in this scope
+      # @param prefix [Prefix] The collection prefixes, ROOT for the params
+      # @param collections [Hash<String, String>] Target path by source path of the collections this scope sees
+      # @return [Scope] The scope
+      def build_scope(pairs, one_ofs, prefix, collections)
+        by_collection = one_ofs.group_by { |one_of| collection_of(one_of.path, prefix.source) }
+        item_prefixes = (by_collection.keys - [""]).map { |source| Prefix.new(source:, target: collection_target(collections, source)) }
+        item_pairs = item_prefixes.to_h do |item_prefix|
+          [item_prefix, pairs.select { |source, target| inside?(source, item_prefix.source) && inside?(target, item_prefix.target) }]
+        end
+
+        Scope.new(
+          pairs: relative_pairs(pairs.reject { |source, _| item_pairs.each_value.any? { |inner| inner.key?(source) } }, prefix),
+          one_ofs: by_collection.fetch("", []).map { |one_of| build_one_of(one_of, prefix) }.freeze,
+          collections: item_prefixes.map { |item_prefix| build_collection(item_prefix, by_collection[item_prefix.source], item_pairs[item_prefix], prefix, collections) }.freeze
+        )
+      end
+
+      # Builds a collection whose items hold a oneOf
+      #
+      # @param item_prefix [Prefix] The collection prefixes, ending with "[]"
+      # @param one_ofs [Array<Layout::OneOfLayout>] The oneOfs in the collection items
+      # @param pairs [Hash] The source and target pairs mapped into the items
+      # @param prefix [Prefix] The prefixes of the parent scope
+      # @param collections [Hash<String, String>] Target path by source path of the collections the parent scope sees
+      # @return [Collection] The collection
+      def build_collection(item_prefix, one_ofs, pairs, prefix, collections)
+        Collection.new(
+          source: path(relative(item_prefix.source.delete_suffix("[]"), prefix.source)),
+          target: path(relative(item_prefix.target.delete_suffix("[]"), prefix.target)),
+          scope: build_scope(pairs, one_ofs, item_prefix, collections)
+        )
+      end
+
+      # Builds a oneOf, with paths relative to the prefix
+      #
+      # @param one_of [Layout::OneOfLayout] The oneOf layout
+      # @param prefix [Prefix] The collection prefixes, ROOT for the params
+      # @return [OneOf] The oneOf
+      # @raise [Verquest::MappingError] If map: moves a variant property out of the collection item
+      def build_one_of(one_of, prefix)
+        check_variant_targets(one_of, prefix)
+
+        OneOf.new(
+          path: path(relative(one_of.path, prefix.source)),
+          variants: one_of.variants.transform_values { |variant| build_scope(variant.pairs, variant.one_ofs, prefix, variant.collections) }.freeze,
+          discriminator: one_of.discriminator && path(relative(one_of.discriminator, prefix.source)),
+          variant_schemas: one_of.variant_schemas,
+          null_target: one_of.null_target && path(relative(one_of.null_target, prefix.target))
+        )
+      end
+
+      # Rejects variant properties moved out of the collection item
+      #
+      # Each item selects its own variant, so its properties can only be
+      # mapped inside the item.
+      #
+      # @param one_of [Layout::OneOfLayout] The oneOf layout
+      # @param prefix [Prefix] The collection prefixes, ROOT for the params
+      # @return [void]
+      # @raise [Verquest::MappingError] If a variant property is mapped out of the item
+      def check_variant_targets(one_of, prefix)
+        one_of.variants.each_value do |variant|
+          source, target = variant.pairs.find { |_, target_path| !inside?(target_path, prefix.target) }
+          raise MappingError, "map: can't move a oneOf variant property out of its collection item (#{source} => #{target})" if source
+        end
+      end
+
+      # Returns the first collection a path enters below a scope
+      #
+      # @param path [String] The source path
+      # @param scope_source [String] The source prefix of the scope, empty for the params
+      # @return [String] The collection path ending with "[]", empty when the path enters none
+      def collection_of(path, scope_source)
+        below = relative(path, scope_source)
+        return "" unless below.include?("[]")
+
+        collection = "#{below.split("[]").first}[]"
+        scope_source.empty? ? collection : "#{scope_source}/#{collection}"
+      end
+
+      # Converts source and target pairs to paths relative to the prefix
+      #
+      # @param pairs [Hash] Source and target pairs
+      # @param prefix [Prefix] The collection prefixes, ROOT for the params
+      # @return [Array<Array(Path, Path)>] The relative pairs
+      def relative_pairs(pairs, prefix)
+        pairs.map { |source, target| [path(relative(source, prefix.source)), path(relative(target, prefix.target))].freeze }.freeze
+      end
+
+      # Checks whether a path is inside another one
+      #
+      # @param path [String] The path
+      # @param prefix [String] The containing path, empty for the root
+      # @return [Boolean] True if the path is below the prefix
+      def inside?(path, prefix)
+        prefix.empty? || path.start_with?("#{prefix}/")
+      end
+
+      # Removes a prefix from a path
+      #
+      # @param path [String] The path
+      # @param prefix [String] The prefix, empty for none
+      # @return [String] The path below the prefix, empty for the prefix itself
+      def relative(path, prefix)
+        return "" if path == prefix
+
+        prefix.empty? ? path : path.delete_prefix("#{prefix}/")
+      end
+
+      # Returns a parsed path, shared between the pairs that use it
+      #
+      # @param path [String] The slash-separated path
+      # @return [Path] The parsed path
+      def path(path)
+        @paths[path.to_s] ||= Path.new(path.to_s)
+      end
+    end
+  end
+end