verquest 0.6.4 → 0.7.0

data/lib/verquest/properties/collection.rb

@@ -18,6 +18,9 @@ module Verquest
     #     item: ProductRequest
     #   )
     class Collection < Base
+      include HelperMethods::ConditionalProperties
+      include HelperMethods::UnnamedOneOf
+
       # Initialize a new Collection property
       #
       # @param name [String, Symbol] The name of the property
@@ -31,6 +34,7 @@ module Verquest
         raise ArgumentError, "You can not map collection to the root" if map == "/"
 
         @properties = {}
+        @conditions = []
 
         @name = name.to_s
         @item = item
@@ -51,9 +55,21 @@ module Verquest
       # @param property [Verquest::Properties::Base] The property to add to the collection items
       # @return [Verquest::Properties::Base] The added property
       def add(property)
+        check_unnamed_one_of(property)
         properties[property.name] = property
       end
 
+      # Add a condition to this collection's item definition
+      #
+      # @param condition [Verquest::Conditions::Condition] The condition to add
+      # @return [Array<Verquest::Conditions::Condition>] The conditions
+      # @raise [ArgumentError] If the collection items are defined by `item:`
+      def add_condition(condition)
+        raise ArgumentError, "condition can not be declared in a collection defined by item:" if has_item?
+
+        super
+      end
+
       # Check if this collection references an external item schema
       #
       # @return [Boolean] True if the collection uses an external reference
@@ -61,18 +77,21 @@ module Verquest
         !item.nil?
       end
 
-      # Check if this collection contains a oneOf property as its item type
+      # Check if the items are a oneOf: an unnamed oneOf is the collection's only property
       #
-      # @return [Boolean] True if the collection contains a oneOf property
+      # @return [Boolean] True if the item schema is the oneOf itself
       def has_one_of?
-        properties.values.size == 1 && properties.values.first.is_a?(Verquest::Properties::OneOf)
+        # A named oneOf is a property of the item, like any other
+        properties.values.size == 1 && properties.values.first.is_a?(Verquest::Properties::OneOf) && properties.values.first.name.nil?
       end
 
       # Returns the oneOf property if this collection contains one
       #
       # @return [Verquest::Properties::OneOf, nil] The oneOf property or nil
+      # @raise [ArgumentError] If the collection also has conditions
       def one_of_property
         return nil unless has_one_of?
+        raise ArgumentError, "Conditions can not be declared next to a one_of in a collection" if conditions.any?
 
         properties.values.first
       end
@@ -104,10 +123,11 @@ module Verquest
               "items" => {
                 "type" => "object",
                 "required" => required_properties,
-                "properties" => properties.transform_values { |property| property.to_schema[property.name] },
+                "properties" => all_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?
+                add_conditions(schema)
               end
             }.merge(schema_options)
           }
@@ -141,10 +161,11 @@ module Verquest
               "items" => {
                 "type" => "object",
                 "required" => required_properties,
-                "properties" => properties.transform_values { |property| property.to_validation_schema(version: version)[property.name] },
+                "properties" => all_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?
+                add_conditions(schema)
               end
             }.merge(schema_options)
           }
@@ -174,24 +195,36 @@ module Verquest
       # @return [void]
       def mapping(key_prefix:, value_prefix:, mapping:, version:)
         if has_item?
-          value_key_prefix = mapping_value_key(value_prefix: value_prefix, collection: true)
-
-          reference_mapping = item.mapping(version:).dup
-          reference_mapping.transform_keys! { |k| "#{(key_prefix + [name]).join("/")}[]/#{k}" }
-          reference_mapping.transform_values! { |v| "#{value_key_prefix}/#{v}" }
-
-          mapping.merge!(reference_mapping)
-        elsif has_one_of?
-          one_of_mapping = {}
-          one_of_property.mapping(key_prefix: key_prefix + ["#{name}[]"], value_prefix: mapping_value_prefix(value_prefix: value_prefix, collection: true), mapping: one_of_mapping, version:)
-          mapping.merge!(one_of_mapping)
+          add_request_mapping(item, key_prefix: key_prefix + ["#{name}[]"], value_prefix: mapping_value_prefix(value_prefix: value_prefix, collection: true), mapping:, version:)
         else
-          properties.values.each do |property|
-            property.mapping(key_prefix: key_prefix + ["#{name}[]"], value_prefix: mapping_value_prefix(value_prefix: value_prefix, collection: true), mapping:, version:)
+          children = has_one_of? ? [one_of_property] : all_properties.values
+          children.each do |property|
+            add_child_mapping(property, key_prefix: key_prefix + ["#{name}[]"], value_prefix: mapping_value_prefix(value_prefix: value_prefix, collection: true), mapping:, version:)
           end
         end
       end
 
+      # Adds this collection and its item properties to a transformer layout
+      #
+      # The collection's source and target paths are added too, so the plan
+      # knows where the items go when they hold a oneOf.
+      #
+      # @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:)
+        item_key_prefix = key_prefix + ["#{name}[]"]
+        item_value_prefix = mapping_value_prefix(value_prefix:, collection: true)
+        layout.add_collection(item_key_prefix.join("/"), item_value_prefix.join("/"))
+        return add_request_layout(item, key_prefix: item_key_prefix, value_prefix: item_value_prefix, layout:, version:) if has_item?
+
+        (has_one_of? ? [one_of_property] : all_properties.values).each do |property|
+          property.layout(key_prefix: item_key_prefix, value_prefix: item_value_prefix, layout:, version:)
+        end
+      end
+
       private
 
       attr_reader :item, :schema_options, :properties, :type

data/lib/verquest/properties/const.rb

@@ -30,7 +30,8 @@ module Verquest
       # @return [Hash] The schema definition for this constant
       def to_schema
         {
-          name => nullable_schema({"const" => value}.merge(schema_options))
+          # Draft 4 and OpenAPI 3.0 have no const, but a one-value enum means the same
+          name => nullable_schema((Verquest.configuration.const_keyword? ? {"const" => value} : {"enum" => [value]}).merge(schema_options))
         }
       end
 

data/lib/verquest/properties/object.rb

@@ -12,6 +12,9 @@ module Verquest
     #   address.add(Verquest::Properties::Field.new(name: :street, type: :string))
     #   address.add(Verquest::Properties::Field.new(name: :city, type: :string, required: true))
     class Object < Base
+      include HelperMethods::ConditionalProperties
+      include HelperMethods::UnnamedOneOf
+
       # Initialize a new Object property
       #
       # @param name [String, Symbol] The name of the property
@@ -21,6 +24,7 @@ module Verquest
       # @param schema_options [Hash] Additional JSON schema options for this property
       def initialize(name:, required: false, nullable: false, map: nil, **schema_options)
         @properties = {}
+        @conditions = []
 
         @name = name.to_s
         @required = required
@@ -44,6 +48,7 @@ module Verquest
       # @param property [Verquest::Properties::Base] The property to add to this object
       # @return [Verquest::Properties::Base] The added property
       def add(property)
+        check_unnamed_one_of(property)
         properties[property.name.to_s] = property
       end
 
@@ -55,9 +60,10 @@ module Verquest
           name => {
             "type" => type,
             "required" => required_properties,
-            "properties" => properties.transform_values { |property| property.to_schema[property.name] }
+            "properties" => all_properties.transform_values { |property| property.to_schema[property.name] }
           }.merge(schema_options).tap do |schema|
             schema["dependentRequired"] = dependent_required_properties if dependent_required_properties.any?
+            add_conditions(schema)
           end
         }
       end
@@ -71,23 +77,51 @@ module Verquest
           name => {
             "type" => type,
             "required" => required_properties,
-            "properties" => properties.transform_values { |property| property.to_validation_schema(version: version)[property.name] }
+            "properties" => all_properties.transform_values { |property| property.to_validation_schema(version: version)[property.name] }
           }.merge(schema_options).tap do |schema|
             schema["dependentRequired"] = dependent_required_properties if dependent_required_properties.any?
+            add_conditions(schema)
           end
         }
       end
 
       # Create mapping for this object property and all its children
       #
+      # Each nested oneOf gets its own mapping in the `_oneOfs` array, so its
+      # metadata can't clash with another oneOf.
+      #
       # @param key_prefix [Array<String>] Prefix for the source key
       # @param value_prefix [Array<String>] Prefix for the target value
       # @param mapping [Hash] The mapping hash to be updated
       # @param version [String, nil] The version to create mapping for
       # @return [void]
       def mapping(key_prefix:, value_prefix:, mapping:, version: nil)
-        properties.values.each do |property|
-          property.mapping(key_prefix: key_prefix + [name], value_prefix: mapping_value_prefix(value_prefix:), mapping:, version:)
+        all_properties.values.each do |property|
+          add_child_mapping(property, key_prefix: key_prefix + [name], value_prefix: mapping_value_prefix(value_prefix:), mapping:, version:)
+        end
+      end
+
+      # Adds this object's properties to a transformer layout
+      #
+      # @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:)
+        all_properties.each_value do |property|
+          property.layout(key_prefix: key_prefix + [name], value_prefix: mapping_value_prefix(value_prefix:), layout:, version:)
+        end
+      end
+
+      # Returns the query parameter options of this object and its properties
+      #
+      # @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:)
+        all_properties.each_value.with_object(super) do |property, options|
+          options.merge!(property.query_options(prefix: prefix + [name], version:))
         end
       end
 

data/lib/verquest/properties/one_of/discriminated_schema.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Verquest
+  module Properties
+    class OneOf < Base
+      # Builds a self-contained oneOf validation schema that keeps the discriminator
+      #
+      # OpenAPI validators (json_schemer's OpenAPI 3.0 and 3.1 dialects) select the
+      # discriminated variant through each oneOf entry's `$ref`, so the variants move
+      # into local definitions. The content-based identifier makes those `$ref`s resolve
+      # against this schema wherever it is embedded, and identical content always gets
+      # the same identifier. Other dialects ignore the discriminator and validate every variant.
+      #
+      # The identifier is set as both `$id` (draft 6 and later, OpenAPI 3.1) and `id`
+      # (draft 4, OpenAPI 3.0), and the variants live under `definitions`, which every
+      # dialect can reference. The output is the same whatever `json_schema_version` is.
+      #
+      # @example
+      #   DiscriminatedSchema.new(definitions: {"dog" => dog_schema, "cat" => cat_schema}, discriminator: "type").to_h
+      #   # => {
+      #   #   "$id" => "https://verquest.local/one_of/3f1c9a0b2d4e5f67",
+      #   #   "id" => "https://verquest.local/one_of/3f1c9a0b2d4e5f67",
+      #   #   "definitions" => {"dog" => dog_schema, "cat" => cat_schema},
+      #   #   "oneOf" => [{"$ref" => "#/definitions/dog"}, {"$ref" => "#/definitions/cat"}],
+      #   #   "discriminator" => {"propertyName" => "type", "mapping" => {"dog" => "#/definitions/dog", "cat" => "#/definitions/cat"}}
+      #   # }
+      class DiscriminatedSchema
+        # Base URI for the schema identifier
+        ID_PREFIX = "https://verquest.local/one_of/"
+
+        # Initialize a new DiscriminatedSchema
+        #
+        # @param definitions [Hash<String, Hash>] Variant name (discriminator value) => inline validation schema
+        # @param discriminator [String] The discriminator property name
+        def initialize(definitions:, discriminator:)
+          @definitions = definitions
+          @discriminator = discriminator
+        end
+
+        # Builds the validation schema
+        #
+        # @return [Hash] Schema with identifiers, definitions, oneOf refs, and discriminator
+        def to_h
+          {"$id" => id, "id" => id}.merge(body)
+        end
+
+        private
+
+        # @!attribute [r] definitions
+        #   @return [Hash<String, Hash>] Variant name => inline validation schema
+        # @!attribute [r] discriminator
+        #   @return [String] The discriminator property name
+        attr_reader :definitions, :discriminator
+
+        # The schema without the identifiers
+        #
+        # @return [Hash] Definitions, oneOf refs, and discriminator
+        def body
+          @body ||= {
+            "definitions" => definitions,
+            "oneOf" => refs.values.map { |ref| {"$ref" => ref} },
+            "discriminator" => {"propertyName" => discriminator, "mapping" => refs}
+          }
+        end
+
+        # Content-based identifier, so identical schemas share it
+        #
+        # `allow_nan` keeps schemas with infinite or NaN numbers (e.g. `maximum: Float::INFINITY`) hashable.
+        #
+        # @return [String] The identifier URI
+        def id
+          @id ||= "#{ID_PREFIX}#{Digest::SHA256.hexdigest(JSON.generate(body, allow_nan: true))[0, 16]}"
+        end
+
+        # Local `$ref` for each variant, keyed by variant name
+        #
+        # @return [Hash<String, String>] Variant name => `$ref` string
+        def refs
+          @refs ||= definitions.keys.to_h { |name| [name, "#/definitions/#{name}"] }
+        end
+      end
+    end
+  end
+end

data/lib/verquest/properties/one_of.rb

@@ -30,6 +30,9 @@ module Verquest
     # @example oneOf without discriminator (pure JSON Schema validation)
     #   one_of = Verquest::Properties::OneOf.new(name: :value)
     #   # Validates that exactly one schema matches
+    #
+    # With a discriminator, the validation schema keeps the discriminator (see DiscriminatedSchema),
+    # so OpenAPI 3.0 and 3.1 validators validate only the variant the discriminator selects.
     class OneOf < Base
       # @return [String, nil] The discriminator property name for schema selection
       attr_reader :discriminator
@@ -113,8 +116,33 @@ module Verquest
 
         build_variant_mappings(mapping, source_prefix, target_prefix, version)
         store_discriminator_path(mapping, source_prefix)
-        store_variant_schemas(mapping, version) unless discriminator
-        store_nullable_metadata(mapping, target_prefix:) if nullable
+        store_variant_schemas(mapping, source_prefix, version) unless discriminator
+        store_nullable_metadata(mapping, source_prefix:, target_prefix:) if nullable
+      end
+
+      # Adds this oneOf to a transformer layout
+      #
+      # Each variant gets its own layout, so it can hold oneOfs and collections.
+      # Like in the mapping, variant properties sit directly under the oneOf
+      # path, not under the variant name.
+      #
+      # @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:)
+        freeze_schemas
+        source_prefix = compute_source_prefix(key_prefix)
+        target_prefix = compute_target_prefix(value_prefix)
+
+        layout.add_one_of(Transformer::Layout::OneOfLayout.new(
+          path: source_prefix.join("/"),
+          discriminator: discriminator && join_path(source_prefix, discriminator),
+          variants: schemas.each_value.to_h { |schema| [schema.name, variant_layout(schema, source_prefix, target_prefix, layout, version)] },
+          variant_schemas: (variant_schemas(version:) unless discriminator),
+          null_target: (target_prefix.join("/") if nullable && !source_prefix.empty?)
+        ))
       end
 
       # Returns validation schemas for all variants
@@ -191,7 +219,7 @@ module Verquest
       # Builds variant mappings for each schema option
       #
       # Handles both Reference and Object schemas:
-      # - Reference: delegates to the referenced schema's mapping
+      # - Reference: maps the referenced request's properties under the oneOf path
       # - Object: builds mapping from child properties directly
       #
       # @param mapping [Hash] The mapping hash to populate
@@ -211,6 +239,9 @@ module Verquest
 
       # Builds mapping for a Reference variant
       #
+      # Maps the referenced request's properties under the oneOf path, so its
+      # oneOfs land in the variant's `_oneOfs` with full paths.
+      #
       # @param mapping [Hash] The mapping hash to populate
       # @param schema [Verquest::Properties::Reference] The reference schema
       # @param source_prefix [Array<String>] Source path prefix
@@ -218,15 +249,10 @@ module Verquest
       # @param version [String, nil] The version for schema resolution
       # @return [void]
       def build_reference_variant_mapping(mapping, schema, source_prefix, target_prefix, version)
-        reference_mapping = schema.send(:from).mapping(version: version)
-        reference_map = schema.send(:map)
-        variant_target_prefix = compute_reference_target_prefix(reference_map, target_prefix)
+        variant_target_prefix = compute_reference_target_prefix(schema.send(:map), target_prefix)
+        variant_mapping = mapping[schema.name] = {}
 
-        mapping[schema.name] = build_prefixed_mapping(
-          reference_mapping,
-          source_prefix,
-          variant_target_prefix
-        )
+        add_request_mapping(schema.send(:from), key_prefix: source_prefix, value_prefix: variant_target_prefix, mapping: variant_mapping, version:)
       end
 
       # Builds mapping for an inline Object variant
@@ -242,34 +268,34 @@ module Verquest
       # @param version [String, nil] The version for schema resolution
       # @return [void]
       def build_object_variant_mapping(mapping, schema, source_prefix, target_prefix, version)
-        object_mapping = {}
-        object_map = schema.send(:map)
-        variant_target_prefix = compute_reference_target_prefix(object_map, target_prefix)
+        variant_target_prefix = compute_reference_target_prefix(schema.send(:map), target_prefix)
+        variant_mapping = mapping[schema.name] = {}
 
-        # Build mapping from object's child properties
         # Properties are mapped directly under source_prefix (not source_prefix + object_name)
-        # to match how Reference variants work
-        schema.send(:properties).each_value do |property|
-          property.mapping(
-            key_prefix: source_prefix,
-            value_prefix: variant_target_prefix,
-            mapping: object_mapping,
-            version: version
-          )
+        # to match how Reference variants work; a nested oneOf lands in the variant's _oneOfs
+        schema.all_properties.each_value do |property|
+          add_child_mapping(property, key_prefix: source_prefix, value_prefix: variant_target_prefix, mapping: variant_mapping, version:)
         end
-
-        mapping[schema.name] = object_mapping
       end
 
-      # Builds a mapping hash with prefixes applied to all keys and values
+      # Adds a variant's properties to its layout, directly under the oneOf path
       #
-      # @param base_mapping [Hash] The source mapping from the referenced schema
-      # @param source_prefix [Array<String>] Prefix for source keys
-      # @param target_prefix [Array<String>] Prefix for target values
-      # @return [Hash] The mapping with prefixes applied
-      def build_prefixed_mapping(base_mapping, source_prefix, target_prefix)
-        base_mapping.each_with_object({}) do |(source_key, target_value), result|
-          result[join_path(source_prefix, source_key)] = join_path(target_prefix, target_value)
+      # @param schema [Verquest::Properties::Reference, Verquest::Properties::Object] The variant
+      # @param source_prefix [Array<String>] The oneOf source path
+      # @param target_prefix [Array<String>] The oneOf target path
+      # @param layout [Verquest::Transformer::Layout] The layout holding the oneOf
+      # @param version [String, nil] The version for schema resolution
+      # @return [Verquest::Transformer::Layout] The variant layout
+      def variant_layout(schema, source_prefix, target_prefix, layout, version)
+        variant_target_prefix = compute_reference_target_prefix(schema.send(:map), target_prefix)
+        layout.variant.tap do |variant|
+          if schema.is_a?(Verquest::Properties::Reference)
+            add_request_layout(schema.send(:from), key_prefix: source_prefix, value_prefix: variant_target_prefix, layout: variant, version:)
+          else
+            schema.all_properties.each_value do |property|
+              property.layout(key_prefix: source_prefix, value_prefix: variant_target_prefix, layout: variant, version:)
+            end
+          end
         end
       end
 
@@ -295,11 +321,13 @@ module Verquest
       # schemas to determine which variant matches the input data.
       #
       # @param mapping [Hash] The mapping hash to update
+      # @param source_prefix [Array<String>] The source path prefix, ending with the oneOf name
       # @param version [String, nil] The version for schema resolution
       # @return [void]
-      def store_variant_schemas(mapping, version)
+      def store_variant_schemas(mapping, source_prefix, version)
         mapping["_variant_schemas"] = variant_schemas(version: version)
-        mapping["_variant_path"] = name unless root_level?
+        # An unnamed oneOf is only at the root when nothing references it
+        mapping["_variant_path"] = source_prefix.join("/") unless source_prefix.empty?
       end
 
       # Stores nullable metadata in the mapping
@@ -308,13 +336,14 @@ module Verquest
       # without attempting variant resolution.
       #
       # @param mapping [Hash] The mapping hash to update
+      # @param source_prefix [Array<String>] The source path prefix, ending with the oneOf name
       # @param target_prefix [Array<String>] The target path prefix for the oneOf property
       # @return [void]
-      def store_nullable_metadata(mapping, target_prefix:)
+      def store_nullable_metadata(mapping, source_prefix:, target_prefix:)
         mapping["_nullable"] = true
-        return if root_level?
+        return if source_prefix.empty?
 
-        mapping["_nullable_path"] = name
+        mapping["_nullable_path"] = source_prefix.join("/")
         mapping["_nullable_target_path"] = target_prefix.join("/")
       end
 
@@ -369,14 +398,16 @@ module Verquest
 
       # Builds the validation schema structure with inline definitions
       #
-      # Unlike the documentation schema, the validation schema omits the discriminator
-      # since it's an OpenAPI extension that JSON Schema validators ignore.
-      # Validators validate against the oneOf array directly.
+      # Without a discriminator, the variants are inlined in the oneOf array.
+      # With a discriminator, DiscriminatedSchema builds a self-contained schema
+      # that keeps the discriminator.
       #
       # @param version [String, nil] The version to generate validation schema for
-      # @return [Hash] Validation schema with oneOf array (no discriminator)
+      # @return [Hash] Validation schema with oneOf array
       def build_validation_schema(version:)
-        {schema_keyword => collect_inline_schemas(version)}
+        return {schema_keyword => collect_inline_schemas(version)} unless discriminator
+
+        DiscriminatedSchema.new(definitions: collect_inline_definitions(version), discriminator: discriminator).to_h
       end
 
       # Collects $ref schema references for all variants
@@ -391,7 +422,15 @@ module Verquest
       # @param version [String, nil] The version for schema resolution
       # @return [Array<Hash>] Array of inline schema definitions
       def collect_inline_schemas(version)
-        schemas.values.map { |schema| schema.to_validation_schema(version: version)[schema.name] }
+        collect_inline_definitions(version).values
+      end
+
+      # Collects inline schema definitions keyed by variant name
+      #
+      # @param version [String, nil] The version for schema resolution
+      # @return [Hash<String, Hash>] Variant name => inline schema definition
+      def collect_inline_definitions(version)
+        schemas.transform_values { |schema| schema.to_validation_schema(version: version)[schema.name] }
       end
 
       # Adds discriminator information to the schema if present

data/lib/verquest/properties/reference.rb

@@ -56,37 +56,68 @@ module Verquest
       end
 
       # Create mapping for this reference property
-      # This delegates to the referenced schema's mapping with appropriate key prefixing
+      #
+      # The referenced request's properties map themselves under this
+      # reference's prefixes. A reference to a single property maps that
+      # property as if it were declared here, with this reference's name and map:.
       #
       # @param key_prefix [Array<String>] Prefix for the source key
       # @param value_prefix [Array<String>] Prefix for the target value
       # @param mapping [Hash] The mapping hash to be updated
       # @param version [String] The version to create mapping for
       # @return [void]
+      # @raise [Verquest::PropertyNotFoundError] If the referenced property doesn't exist
       def mapping(key_prefix:, value_prefix:, mapping:, version:)
-        reference_mapping = from.mapping(version:, property:).dup
-        value_key_prefix = mapping_value_key(value_prefix:)
+        return add_request_mapping(from, key_prefix: key_prefix + [name], value_prefix: mapping_value_prefix(value_prefix:), mapping:, version:) unless property
 
-        # Single field mapping
-        if property && reference_mapping.size == 1 && !reference_mapping.keys.first.include?("/")
-          reference_mapping = {
-            (key_prefix + [name]).join("/") => value_key_prefix
-          }
-        else
-          if value_key_prefix != "" && !value_key_prefix.end_with?("/")
-            value_key_prefix = "#{value_key_prefix}/"
-          end
+        referenced = from.resolve(version)
+        add_child_mapping(referenced.fetch_property(property).renamed(name:, map:), key_prefix:, value_prefix:, mapping:, version: referenced.name)
+      end
 
-          reference_mapping.transform_keys! { "#{(key_prefix + [name]).join("/")}/#{_1}" }
-          reference_mapping.transform_values! { "#{value_key_prefix}#{_1}" }
-        end
+      # Adds the referenced request's properties, or the referenced property, to a transformer layout
+      #
+      # @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]
+      # @raise [Verquest::PropertyNotFoundError] If the referenced property doesn't exist
+      def layout(key_prefix:, value_prefix:, layout:, version:)
+        return add_request_layout(from, key_prefix: key_prefix + [name], value_prefix: mapping_value_prefix(value_prefix:), layout:, version:) unless property
+
+        referenced = from.resolve(version)
+        referenced.fetch_property(property).renamed(name:, map:).layout(key_prefix:, value_prefix:, layout:, version: referenced.name)
+      end
+
+      # Returns the query parameter options of the referenced request, or of
+      # the referenced property renamed to this reference
+      #
+      # This reference's own parameter examples replace the referenced ones.
+      #
+      # @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
+      # @raise [Verquest::PropertyNotFoundError] If the referenced property doesn't exist
+      def query_options(prefix:, version:)
+        referenced = from.resolve(version)
+        return referenced_property_options(referenced, prefix:) if property
 
-        mapping.merge!(reference_mapping)
+        referenced.all_properties.each_value.with_object(super) do |child, options|
+          options.merge!(child.query_options(prefix: prefix + [name], version: referenced.name))
+        end
       end
 
       private
 
       attr_reader :from, :property
+
+      # @return [Hash{Array<String> => Hash}] The options of the referenced property under this reference's name
+      def referenced_property_options(referenced, prefix:)
+        copy = referenced.fetch_property(property).renamed(name:, map:)
+        copy.parameter_examples = parameter_examples if parameter_examples
+
+        copy.query_options(prefix:, version: referenced.name)
+      end
     end
   end
 end