lutaml-model 0.8.45 → 0.8.46

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 07e6ecf8e0047cd91862259a5a9db3b1cfb09122e752cdd17a4523d7169c89c5
-  data.tar.gz: 5fd97454986a0d0f4bd1f13d75af01d0a692618acd9fafcc702bfaea7a73827f
+  metadata.gz: b2f28f3c9d10541b92778ec5ab996c7b41110bb5784b4832d08e650a758db5f8
+  data.tar.gz: 22b516d73a1b76acf9421226b3f00204c3dec0cc46e4e1a9f1531ee979b1f8a2
 SHA512:
-  metadata.gz: d95d9d885d0fbc63200900751b75c62282b63970f3fe4ebb1707ff134452bd57d714b8aad22f2253b70ea9509d1456dfd6bbee2a43f3cb292de8ae87959ab617
-  data.tar.gz: 455d7af1865469474d7f11f623dede9fbd65311dabaa30c0546a0193bdfbab4e99356b50ca6e8ffa2deb5f108ca0d5e2de9bf112e03ce607328c9ff4e6de0a8d
+  metadata.gz: 779f779b5b3d76947306eec00d8652c4d8ca5e41a1a5846df1b34d5b52c03cc7e6302a53a4280d921aaddc96172daed52e1476b0662b60af40ea49558cba87f5
+  data.tar.gz: 1e19049f5e0e8a57218bdd2d6a3366f018c37b53a773c6f660d18eb071fa7736db3521762040314097b0ab8b0d9507bd2a778a06af17719935c013639854ff82

data/docs/_guides/advanced-mapping.adoc

@@ -645,3 +645,55 @@ end
 Given `<component type="guidance">`, `<component type="purpose">`,
 `<component type="guidance">` in the source, `to_xml` re-emits exactly
 that guidance, purpose, guidance sequence.
+
+
+==== Key-value formats
+
+The same discriminator works for JSON, YAML, TOML and Hash: the wire
+name is an object key, and the discriminator is a sibling key's value
+inside each item.
+
+[source,ruby]
+----
+class KvRequirement < Lutaml::Model::Serializable
+  attribute :guidance, Component, collection: true
+  attribute :purpose, Component, collection: true
+
+  json do
+    map "component", to: :guidance,
+                     when_attribute: { "type" => "guidance" }
+    map "component", to: :purpose,
+                     when_attribute: { "type" => "purpose" }
+  end
+end
+----
+
+[source,json]
+----
+{ "component": [
+  { "type": "guidance", "text": "g1" },
+  { "type": "purpose", "text": "p1" }
+] }
+----
+
+`guidance` holds `g1` and `purpose` holds `p1`. A bare object instead of
+an array counts as one occurrence. Every semantics from the XML side
+carries over: plain rules on the same key capture only unclaimed items,
+`unmatched: :raise` fails the parse on an item no rule claims, and
+string or symbol keys both match.
+
+On serialization the rules merge back under the one key, each item
+stamped with its rule's discriminator pair (unless the item's own
+mapping already writes that key):
+
+[source,json]
+----
+{ "component": [
+  { "type": "guidance", "text": "g1" },
+  { "type": "purpose", "text": "p1" }
+] }
+----
+
+Items are grouped by rule in mapping-declaration order — object
+documents carry no interleaving to preserve. `when_attribute` cannot be
+combined with `with:` or `delegate:` in key-value mappings.

data/lib/lutaml/key_value/mapping.rb

@@ -79,12 +79,21 @@ module Lutaml
         polymorphic_map: {},
         transform: {},
         value_map: {},
+        when_attribute: {},
+        unmatched: :drop,
         serialize: true
       )
         mapping_name = name_for_mapping(root_mappings, name)
         validate!(mapping_name, to, with, render_nil, render_empty)
+        validate_when_attribute!(when_attribute) unless when_attribute.empty?
+        validate_unmatched!(unmatched, when_attribute)
+        if !when_attribute.empty? && (!with.empty? || delegate)
+          raise Lutaml::Model::IncorrectMappingArgumentsError,
+                "when_attribute cannot be combined with :with or :delegate " \
+                "in key-value mappings"
+        end
 
-        @mappings[mapping_name] = MappingRule.new(
+        rule = MappingRule.new(
           mapping_name,
           to: to,
           render_nil: render_nil,
@@ -101,8 +110,23 @@ module Lutaml
           polymorphic_map: polymorphic_map,
           transform: transform,
           value_map: value_map,
+          when_attribute: when_attribute,
+          unmatched: unmatched,
           serialize: serialize,
         )
+        # lutaml-model#88: rules may share a wire key (when_attribute
+        # partitions) — store per-key arrays, like the XML mapping. A
+        # rule redefining the same target (`to:`) replaces its
+        # predecessor, so subclass and redeclaration overrides keep the
+        # pre-array replace semantics.
+        existing = @mappings[mapping_name]
+        if existing.nil?
+          @mappings[mapping_name] = [rule]
+        elsif (index = existing.index { |r| r.to == rule.to })
+          existing[index] = rule
+        else
+          existing << rule
+        end
       end
 
       alias map_element map
@@ -117,14 +141,14 @@ module Lutaml
         @raw_mapping = true
         validate!(Lutaml::Model::Constants::RAW_MAPPING_KEY, to, with,
                   render_nil, nil)
-        @mappings[Lutaml::Model::Constants::RAW_MAPPING_KEY] = MappingRule.new(
+        @mappings[Lutaml::Model::Constants::RAW_MAPPING_KEY] = [MappingRule.new(
           Lutaml::Model::Constants::RAW_MAPPING_KEY,
           to: to,
           render_nil: render_nil,
           render_default: render_default,
           with: with,
           delegate: delegate,
-        )
+        )]
       end
 
       alias map_all_content map_all
@@ -153,7 +177,9 @@ module Lutaml
         return if !instance_mapping?
 
         mapping_name = name_for_mapping(nil, key_name || @instance)
-        @mappings[mapping_name].child_mappings = @key_mapping.merge(@value_mapping)
+        @mappings[mapping_name].each do |rule|
+          rule.child_mappings = @key_mapping.merge(@value_mapping)
+        end
       end
 
       def name_for_mapping(root_mappings, name)
@@ -164,7 +190,7 @@ module Lutaml
 
       def mappings(register_id = nil)
         ensure_mappings_imported!(register_id) if finalized?
-        mappings_hash(register_id).values
+        mappings_hash(register_id).values.flatten
       end
 
       def mappings_hash(register_id = nil)
@@ -271,7 +297,7 @@ module Lutaml
       end
 
       def find_by_name(name)
-        @mappings.find { |m| m.name.to_s == name.to_s }
+        mappings.find { |m| m.name.to_s == name.to_s }
       end
 
       def polymorphic_mapping

data/lib/lutaml/key_value/mapping_rule.rb

@@ -4,6 +4,8 @@ module Lutaml
       attr_accessor :child_mappings,
                     :root_mappings
 
+      attr_reader :unmatched
+
       def initialize(
         name,
         to:,
@@ -23,6 +25,8 @@ module Lutaml
         polymorphic_map: {},
         transform: {},
         value_map: {},
+        when_attribute: {},
+        unmatched: :drop,
         serialize: true
       )
         super(
@@ -42,11 +46,14 @@ module Lutaml
           polymorphic_map: polymorphic_map,
           transform: transform,
           value_map: value_map,
+          when_attribute: when_attribute,
           serialize: serialize,
         )
 
         @child_mappings = child_mappings
         @root_mappings = root_mappings
+        # lutaml-model#88: policy for occurrences claimed by no rule
+        @unmatched = unmatched
       end
 
       def hash_mappings
@@ -67,6 +74,8 @@ module Lutaml
           child_mappings: Lutaml::Model::Utils.deep_dup(child_mappings),
           root_mappings: Lutaml::Model::Utils.deep_dup(root_mappings),
           value_map: Lutaml::Model::Utils.deep_dup(@value_map),
+          when_attribute: when_attribute,
+          unmatched: @unmatched,
           serialize: serialize?,
         )
       end

data/lib/lutaml/key_value/transform.rb

@@ -18,8 +18,12 @@ module Lutaml
         root_and_parent_assignment(instance, options)
         mappings = extract_mappings(options, format)
 
-        mappings.mappings(lutaml_register).each do |rule|
-          process_mapping_rule(data, instance, format, rule, options)
+        rules = mappings.mappings(lutaml_register)
+        # lutaml-model#88: nil unless the mapping partitions a wire key
+        # with when_attribute rules — the common case pays one scan.
+        partition = kv_partition(rules)
+        rules.each do |rule|
+          process_mapping_rule(data, instance, format, rule, options, partition)
         end
 
         instance
@@ -48,11 +52,22 @@ module Lutaml
         # This maintains backward compatibility for models without transformations
         mappings = extract_mappings(options, format)
 
+        rules = mappings.mappings(lutaml_register)
+        partition = kv_partition(rules)
         hash = {}
-        mappings.mappings(lutaml_register).each do |rule|
+        handled_groups = nil
+        rules.each do |rule|
           next unless valid_mapping?(rule, options)
 
-          process_rule!(instance, rule, hash, format, mappings, options)
+          group = partition && kv_partition_group(rule, partition)
+          if group
+            next if handled_groups&.include?(group)
+
+            (handled_groups ||= []) << group
+            process_partition_group!(instance, group, hash, format, options)
+          else
+            process_rule!(instance, rule, hash, format, mappings, options)
+          end
         end
 
         hash.keys == [""] ? hash[""] : hash
@@ -263,7 +278,163 @@ format)
         options[:mappings] || mappings_for(format, lutaml_register)
       end
 
-      def process_mapping_rule(doc, instance, format, rule, options = {})
+      # ---- lutaml-model#88: when_attribute for key-value formats ----
+
+      # Wire keys partitioned by when_attribute rules: key -> { rules: all
+      # rules on the key in declaration order, discriminators: the subset
+      # carrying when_attribute }. nil unless any rule uses when_attribute.
+      def kv_partition(rules)
+        partitions = nil
+        rules.each do |rule|
+          next if rule.when_attribute.empty?
+
+          partitions ||= {}
+          key = kv_partition_key(rule)
+          entry = (partitions[key] ||= { rules: [], discriminators: [] })
+          entry[:discriminators] << rule
+        end
+        return nil unless partitions
+
+        rules.each do |rule|
+          key = kv_partition_key(rule)
+          partitions[key][:rules] << rule if partitions.key?(key)
+        end
+        partitions
+      end
+
+      def kv_partition_key(rule)
+        name = rule.name
+        name = name.first if name.is_a?(Array)
+        name.to_s
+      end
+
+      # The partition entry covering any of the rule's wire names.
+      def kv_partition_group(rule, partition)
+        return nil if partition.nil?
+
+        if rule.multiple_mappings?
+          rule.name.each do |name|
+            entry = partition[name.to_s]
+            return entry if entry
+          end
+          nil
+        else
+          partition[rule.name.to_s]
+        end
+      end
+
+      # A value at a partitioned key, filtered for one rule: a
+      # discriminator rule keeps its matches; a plain rule keeps the
+      # occurrences no discriminator claimed (single-capture, mirroring
+      # the XML side).
+      def apply_kv_when_attribute(value, rule, entry, attr = nil)
+        if rule.when_attribute.empty?
+          return kv_partition_value(value, attr) do |item|
+            entry[:discriminators].none? { |s| kv_item_matches?(item, s) }
+          end
+        end
+
+        plain_sibling = entry[:rules].any? { |r| r.when_attribute.empty? }
+        if rule.unmatched == :raise && !plain_sibling
+          check_unclaimed_kv_items!(value, rule, entry)
+        end
+        kv_partition_value(value, attr) { |item| kv_item_matches?(item, rule) }
+      end
+
+      def kv_item_matches?(item, rule)
+        return false unless item.is_a?(::Hash)
+
+        rule.when_attribute.all? do |name, expected|
+          actual = Lutaml::Model::Utils.fetch_str_or_sym(item, name.to_s)
+          !actual.nil? && actual.to_s == expected.to_s
+        end
+      end
+
+      # select/reject over the occurrence shape: an Array filters per
+      # item; a single occurrence is kept or dropped as a whole; nil
+      # passes through. A dropped occurrence existed on the wire, so a
+      # collection attribute reads it as [] rather than absent. A
+      # non-hash item satisfies no discriminator, so plain rules keep it
+      # and discriminator rules drop it.
+      def kv_partition_value(value, attr = nil, &block)
+        case value
+        when ::Array
+          value.select(&block)
+        when nil
+          nil
+        else
+          if yield(value)
+            value
+          else
+            attr&.collection? ? [] : nil
+          end
+        end
+      end
+
+      # lutaml-model#88: fail closed for `unmatched: :raise` — an item
+      # no rule on the key claims is exactly the data the default
+      # policy silently drops.
+      def check_unclaimed_kv_items!(value, rule, entry)
+        items = value.is_a?(::Array) ? value : [value]
+        tested = entry[:discriminators].flat_map { |s| s.when_attribute.keys }
+          .uniq.map(&:to_s)
+        items.each do |item|
+          next if entry[:discriminators].any? { |s| kv_item_matches?(item, s) }
+
+          values = tested.filter_map do |name|
+            v = item.is_a?(::Hash) &&
+              Lutaml::Model::Utils.fetch_str_or_sym(item, name)
+            "#{name}=#{v.inspect}" if v
+          end
+          raise ::Lutaml::Model::UnknownDiscriminatorError,
+                "Item at <#{kv_partition_key(rule)}> (#{values.join(', ')}) " \
+                "is claimed by no rule: it matches no when_attribute " \
+                "discriminator and no plain rule shares the key. Cover the " \
+                "value, add a plain rule, or opt out with unmatched: :drop"
+        end
+        nil
+      end
+
+      # Serialize a partitioned key as one wire value: every rule on the
+      # key contributes its items in declaration order, each stamped with
+      # its rule's discriminator pairs (unless the item already carries
+      # the key — the value's own mapping wins).
+      def process_partition_group!(instance, group, hash, format, options)
+        wire = rule_from_name(group[:rules].first)
+        items = []
+        present = false
+        group[:rules].each do |rule|
+          next unless valid_mapping?(rule, options)
+
+          scratch = {}
+          process_mapping_for_instance(instance, scratch, format, rule, options)
+          value = scratch[rule_from_name(rule)]
+          next if value.nil?
+
+          present = true
+          Array(value).each do |item|
+            items << kv_stamp_discriminator(item, rule)
+          end
+        end
+        return unless present
+
+        hash[wire] = items
+      end
+
+      def kv_stamp_discriminator(item, rule)
+        return item unless item.is_a?(::Hash)
+
+        missing = {}
+        rule.when_attribute.each do |name, expected|
+          unless Lutaml::Model::Utils.string_or_symbol_key?(item, name)
+            missing[name.to_s] = expected.to_s
+          end
+        end
+        missing.empty? ? item : item.merge(missing)
+      end
+
+      def process_mapping_rule(doc, instance, format, rule, options = {},
+partition = nil)
         attr = attribute_for_rule(rule)
         return if attr&.derived?
 
@@ -271,7 +442,11 @@ format)
           rule, attr
         )
 
-        if (plan = kv_rule_plan(format, rule, attr)) &&
+        # lutaml-model#88: discriminator rules (and plain rules on a
+        # partitioned key) must filter the raw value, so they keep the
+        # interpretive path.
+        partitioned = partition && kv_partition_group(rule, partition)
+        if partitioned.nil? && (plan = kv_rule_plan(format, rule, attr)) &&
             (value = kv_fast_extract(doc, plan))
           rule.deserialize(instance, kv_fast_cast(value, plan, instance),
                            attributes, self, options[:context])
@@ -280,6 +455,9 @@ format)
 
         value = rule_value_extractor_class.call(rule, doc, format, attr,
                                                 lutaml_register, options, instance)
+        if partitioned && !Lutaml::Model::Utils.uninitialized?(value)
+          value = apply_kv_when_attribute(value, rule, partitioned, attr)
+        end
         value = apply_value_map(value, rule.value_map(:from, options), attr)
 
         if rule.has_custom_method_for_deserialization?
@@ -328,7 +506,8 @@ format)
         return nil if rule.delegate || rule.raw_mapping? || rule.root_mapping? ||
           rule.hash_mappings || rule.child_mappings ||
           rule.has_custom_method_for_serialization? ||
-          rule.multiple_mappings? || polymorphic_rule?(rule) ||
+          rule.when_attribute? || rule.multiple_mappings? ||
+          polymorphic_rule?(rule) ||
           (rule.transform.is_a?(Hash) && !rule.transform.empty?) ||
           rule.transform.is_a?(Class) || attr.nil? || attr.derived? ||
           attr.union? || attr.polymorphic? || attr.custom_collection? ||

data/lib/lutaml/key_value/transformation/rule_compiler.rb

@@ -231,6 +231,8 @@ transformation_factory:)
             delegate: delegate,
             root_mappings: mapping_rule.root_mappings,
             serialize: mapping_rule.serialize?,
+            when_attribute: mapping_rule.when_attribute,
+            unmatched: mapping_rule.unmatched,
           )
         end
 

data/lib/lutaml/key_value/transformation.rb

@@ -118,6 +118,37 @@ register = self.register)
         end
       end
 
+      # lutaml-model#88: rules sharing a wire key through when_attribute
+      # must serialize as ONE value — group them here, before freeze.
+      # Rules with custom `to` methods or delegates keep their own path;
+      # a key mixing them with discriminator rules is not a partition.
+      def after_compile
+        partitioned_names = nil
+        compiled_rules.each do |rule|
+          pairs = rule.option(:when_attribute)
+          next if pairs.nil? || pairs.empty?
+
+          (partitioned_names ||= {})[rule.serialized_name] = true
+        end
+        return unless partitioned_names
+
+        groups = {}
+        by_rule = {}.compare_by_identity
+        compiled_rules.each do |rule|
+          name = rule.serialized_name
+          next unless partitioned_names[name]
+          next if (rule.custom_methods || {}).key?(:to) || rule.option(:delegate)
+
+          entry = (groups[name] ||= [])
+          entry << rule
+          by_rule[rule] = entry
+        end
+        groups.each_value(&:freeze)
+
+        @partition_groups = groups.freeze
+        @partitioned_rules = by_rule
+      end
+
       private
 
       # Get the register ID, handling both Symbol and Register objects
@@ -180,12 +211,21 @@ register = self.register)
         # Instead, we create an anonymous root that holds all attributes
         root = Lutaml::KeyValue::DataModel::Element.new("__root__")
 
-        # Apply each compiled rule (with filtering support)
+        # Apply each compiled rule (with filtering support). A
+        # when_attribute partition applies once for its whole key.
+        handled_groups = nil
         compiled_rules.each do |rule|
           # Check if this rule should be applied based on only/except options
           next unless valid_mapping?(rule, options)
 
-          apply_rule(root, rule, model_instance, options)
+          if @partitioned_rules && (group = @partitioned_rules[rule])
+            next if handled_groups&.include?(group)
+
+            (handled_groups ||= []) << group
+            apply_partition_group(root, group, model_instance, options)
+          else
+            apply_rule(root, rule, model_instance, options)
+          end
         end
 
         if ENV["DEBUG_KEYED_COLLECTION"]
@@ -202,6 +242,77 @@ register = self.register)
 
       private
 
+      # The rule's value on the instance, initializing an absent
+      # delegate target like apply_rule does.
+      def extract_rule_value(rule, model_instance)
+        delegate = rule.option(:delegate)
+        unless delegate
+          return model_instance.public_send(rule.attribute_name)
+        end
+
+        delegated_object = model_instance.public_send(delegate)
+        if delegated_object.nil? ||
+            Lutaml::Model::Utils.uninitialized?(delegated_object)
+          delegate_attr = model_class.attributes(register_id)&.[](delegate)
+          if delegate_attr
+            delegated_object = delegate_attr.type(register_id).new
+            model_instance.public_send(:"#{delegate}=", delegated_object)
+          end
+        end
+        delegated_object&.public_send(rule.attribute_name)
+      end
+
+      # Serialize one when_attribute partition: every rule on the key
+      # contributes its items in declaration order, each stamped with
+      # its rule's discriminator pairs (unless the item's own mapping
+      # already wrote the key). The wire value is an array whenever any
+      # rule had a present value.
+      def apply_partition_group(parent, group, model_instance, options)
+        items = []
+        present = false
+        group.each do |rule|
+          next unless valid_mapping?(rule, options)
+
+          value = extract_rule_value(rule, model_instance)
+          next if should_skip_value?(value, rule, model_instance,
+                                     rule.option(:delegate))
+
+          value = rule.transform_value(value, :export) if rule.value_transformer
+
+          present = true
+          Array(value).each do |item|
+            child = create_value_for_item(rule, item, options)
+            next if child.nil?
+
+            items << stamp_discriminator(child, rule)
+          end
+        end
+        return unless present
+
+        element = Lutaml::KeyValue::DataModel::Element.new(
+          group.first.serialized_name,
+        )
+        if items.empty?
+          element.value = []
+        else
+          items.each { |item| element.add_child(item) }
+        end
+        parent.add_child(element)
+      end
+
+      def stamp_discriminator(item, rule)
+        pairs = rule.option(:when_attribute)
+        return item if pairs.nil? || pairs.empty? || !item.is_a?(::Hash)
+
+        missing = {}
+        pairs.each do |name, expected|
+          unless Lutaml::Model::Utils.string_or_symbol_key?(item, name)
+            missing[name.to_s] = expected.to_s
+          end
+        end
+        missing.empty? ? item : item.merge(missing)
+      end
+
       # Apply a single transformation rule
       #
       # @param parent [Lutaml::KeyValue::DataModel::Element] Parent element

data/lib/lutaml/model/mapping/mapping.rb

@@ -106,6 +106,36 @@ module Lutaml
 
       attr_accessor :importable_mappings
 
+      # lutaml-model#88: attribute-value discriminator. Keys are wire
+      # names (an XML attribute, or an object key in key-value formats),
+      # values the expected string value. Shared by the XML and KV DSLs.
+      def validate_when_attribute!(when_attribute)
+        when_attribute.each do |k, v|
+          next if (k.is_a?(::String) || k.is_a?(::Symbol)) &&
+            (v.is_a?(::String) || v.is_a?(::Symbol))
+
+          raise Lutaml::Model::IncorrectMappingArgumentsError,
+                "when_attribute expects string/symbol attribute names " \
+                "mapped to string/symbol values, got " \
+                "#{k.inspect} => #{v.inspect}"
+        end
+      end
+
+      # lutaml-model#88: what a parse does with an occurrence that no
+      # rule on the wire name claims — :drop it (default) or :raise
+      # UnknownDiscriminatorError. Only meaningful on discriminator rules.
+      def validate_unmatched!(unmatched, when_attribute)
+        unless %i[drop raise].include?(unmatched)
+          raise Lutaml::Model::IncorrectMappingArgumentsError,
+                "unmatched expects :drop or :raise, got #{unmatched.inspect}"
+        end
+
+        return unless when_attribute.empty? && unmatched != :drop
+
+        raise Lutaml::Model::IncorrectMappingArgumentsError,
+              "unmatched only applies to rules declared with when_attribute"
+      end
+
       def register(register_id = nil)
         register_id ||= Lutaml::Model::Config.default_register
         Lutaml::Model::GlobalRegister.lookup(register_id)

data/lib/lutaml/model/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Model
-    VERSION = "0.8.45"
+    VERSION = "0.8.46"
   end
 end

data/lib/lutaml/xml/mapping.rb

@@ -614,35 +614,6 @@ module Lutaml
         end
       end
 
-      # lutaml-model#88: attribute-value discriminator. Keys are wire
-      # attribute names, values the expected string value.
-      def validate_when_attribute!(when_attribute)
-        when_attribute.each do |k, v|
-          next if (k.is_a?(::String) || k.is_a?(::Symbol)) &&
-            (v.is_a?(::String) || v.is_a?(::Symbol))
-
-          raise Lutaml::Model::IncorrectMappingArgumentsError,
-                "when_attribute expects string/symbol attribute names " \
-                "mapped to string/symbol values, got " \
-                "#{k.inspect} => #{v.inspect}"
-        end
-      end
-
-      # lutaml-model#88: what a parse does with an occurrence that no
-      # rule on the wire name claims — :drop it (default) or :raise
-      # UnknownDiscriminatorError. Only meaningful on discriminator rules.
-      def validate_unmatched!(unmatched, when_attribute)
-        unless %i[drop raise].include?(unmatched)
-          raise Lutaml::Model::IncorrectMappingArgumentsError,
-                "unmatched expects :drop or :raise, got #{unmatched.inspect}"
-        end
-
-        return unless when_attribute.empty? && unmatched != :drop
-
-        raise Lutaml::Model::IncorrectMappingArgumentsError,
-              "unmatched only applies to rules declared with when_attribute"
-      end
-
       def map_attribute(
         name,
       to: nil,

data/spec/lutaml/key_value/when_attribute_spec.rb

@@ -0,0 +1,348 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# lutaml-model#88: `when_attribute` partitioning for key-value formats.
+# The discriminator is an object key: items of the array at a shared wire
+# key are claimed by the rule whose pairs their key values satisfy.
+# Serialization merges every rule's items back under the one key, each
+# item stamped with its rule's discriminator pairs.
+class KvWhenComponent < Lutaml::Model::Serializable
+  attribute :text, :string
+
+  json do
+    map "text", to: :text
+  end
+
+  yaml do
+    map "text", to: :text
+  end
+
+  toml do
+    map "text", to: :text
+  end
+
+  hsh do
+    map "text", to: :text
+  end
+end
+
+class KvWhenRequirement < Lutaml::Model::Serializable
+  attribute :guidance, KvWhenComponent, collection: true
+  attribute :purpose, KvWhenComponent, collection: true
+
+  json do
+    map "component", to: :guidance,
+                     when_attribute: { "type" => "guidance" }
+    map "component", to: :purpose,
+                     when_attribute: { "type" => "purpose" }
+  end
+
+  yaml do
+    map "component", to: :guidance,
+                     when_attribute: { "type" => "guidance" }
+    map "component", to: :purpose,
+                     when_attribute: { "type" => "purpose" }
+  end
+
+  hsh do
+    map "component", to: :guidance,
+                     when_attribute: { "type" => "guidance" }
+    map "component", to: :purpose,
+                     when_attribute: { "type" => "purpose" }
+  end
+end
+
+RSpec.describe "when_attribute for key-value formats" do
+  before do
+    stub_const("KvWhen::Component", KvWhenComponent)
+    stub_const("KvWhen::Requirement", KvWhenRequirement)
+  end
+
+  let(:payload) do
+    {
+      "component" => [
+        { "type" => "guidance", "text" => "g1" },
+        { "type" => "purpose", "text" => "p1" },
+        { "type" => "guidance", "text" => "g2" },
+      ],
+    }
+  end
+
+  it "partitions json by the discriminator key" do
+    req = KvWhenRequirement.from_json(payload.to_json)
+
+    expect(req.guidance.map(&:text)).to eq(%w[g1 g2])
+    expect(req.purpose.map(&:text)).to eq(["p1"])
+  end
+
+  it "partitions yaml arrays of mappings" do
+    req = KvWhenRequirement.from_yaml(payload.to_yaml)
+
+    expect(req.guidance.map(&:text)).to eq(%w[g1 g2])
+    expect(req.purpose.map(&:text)).to eq(["p1"])
+  end
+
+  it "partitions hashes passed directly with symbol keys" do
+    req = KvWhenRequirement.from_hash(
+      component: [
+        { type: "guidance", text: "g1" },
+        { type: "purpose", text: "p1" },
+      ],
+    )
+
+    expect(req.guidance.map(&:text)).to eq(["g1"])
+    expect(req.purpose.map(&:text)).to eq(["p1"])
+  end
+
+  it "keeps a single object occurrence as one item" do
+    req = KvWhenRequirement.from_hash(
+      "component" => { "type" => "purpose", "text" => "p1" },
+    )
+
+    expect(req.purpose.map(&:text)).to eq(["p1"])
+    expect(req.guidance).to be_empty
+  end
+
+  it "serializes one merged array with the discriminators stamped" do
+    req = KvWhenRequirement.from_json(payload.to_json)
+    out = req.to_json
+
+    items = JSON.parse(out)["component"]
+    expect(items).to eq([
+                          { "type" => "guidance", "text" => "g1" },
+                          { "type" => "guidance", "text" => "g2" },
+                          { "type" => "purpose", "text" => "p1" },
+                        ])
+  end
+
+  it "round-trips through yaml" do
+    req = KvWhenRequirement.from_yaml(payload.to_yaml)
+    again = KvWhenRequirement.from_yaml(req.to_yaml)
+
+    expect(again.guidance.map(&:text)).to eq(%w[g1 g2])
+    expect(again.purpose.map(&:text)).to eq(["p1"])
+  end
+
+  it "does not stamp over a key the item's own mapping writes" do
+    holder = Class.new(Lutaml::Model::Serializable) do
+      attribute :items, KvWhenComponent, collection: true
+
+      json do
+        map "component", to: :items,
+                         when_attribute: { "type" => "guidance" }
+      end
+
+      hsh do
+        map "component", to: :items,
+                         when_attribute: { "type" => "guidance" }
+      end
+    end
+    stub_const("KvWhen::Holder", holder)
+
+    out = holder.from_hash(
+      "component" => [{ "type" => "guidance", "text" => "g" }],
+    ).to_json
+    expect(JSON.parse(out)["component"]).to eq(
+      [{ "type" => "guidance", "text" => "g" }],
+    )
+  end
+
+  describe "plain rule complement" do
+    let(:holder) do
+      Class.new(Lutaml::Model::Serializable) do
+        attribute :special, KvWhenComponent, collection: true
+        attribute :plain, KvWhenComponent, collection: true
+
+        json do
+          map "item", to: :special, when_attribute: { "kind" => "special" }
+          map "item", to: :plain
+        end
+
+        hsh do
+          map "item", to: :special, when_attribute: { "kind" => "special" }
+          map "item", to: :plain
+        end
+      end
+    end
+
+    it "captures occurrences no discriminator claimed exactly once" do
+      stub_const("KvWhen::Both", holder)
+      doc = holder.from_hash(
+        "item" => [
+          { "kind" => "special", "text" => "b" },
+          { "text" => "a" },
+          { "kind" => "other", "text" => "x" },
+        ],
+      )
+
+      expect(doc.special.map(&:text)).to eq(["b"])
+      expect(doc.plain.map(&:text)).to eq(%w[a x])
+    end
+
+    it "merges plain and stamped items into the one key" do
+      stub_const("KvWhen::Both", holder)
+      doc = holder.from_hash(
+        "item" => [
+          { "kind" => "special", "text" => "b" },
+          { "text" => "a" },
+        ],
+      )
+      items = JSON.parse(doc.to_json)["item"]
+
+      expect(items).to eq([
+                            { "kind" => "special", "text" => "b" },
+                            { "text" => "a" },
+                          ])
+    end
+  end
+
+  describe "unmatched policy" do
+    let(:strict) do
+      Class.new(Lutaml::Model::Serializable) do
+        attribute :guidance, KvWhenComponent, collection: true
+
+        json do
+          map "component", to: :guidance,
+                           when_attribute: { "type" => "guidance" },
+                           unmatched: :raise
+        end
+      end
+    end
+
+    it "raises on an unclaimed discriminator value" do
+      stub_const("KvWhen::Strict", strict)
+
+      expect do
+        strict.from_json({ "component" => [
+          { "type" => "guidance", "text" => "g" },
+          { "type" => "nope", "text" => "x" },
+        ] }.to_json)
+      end.to raise_error(Lutaml::Model::UnknownDiscriminatorError, /type="nope"/)
+    end
+
+    it "raises on an item without the discriminator key" do
+      stub_const("KvWhen::Strict", strict)
+
+      expect do
+        strict.from_json({ "component" => [{ "text" => "x" }] }.to_json)
+      end.to raise_error(Lutaml::Model::UnknownDiscriminatorError, /<component>/)
+    end
+
+    it "drops unclaimed occurrences by default" do
+      lenient = Class.new(Lutaml::Model::Serializable) do
+        attribute :guidance, KvWhenComponent, collection: true
+
+        json do
+          map "component", to: :guidance,
+                           when_attribute: { "type" => "guidance" }
+        end
+      end
+      stub_const("KvWhen::Lenient", lenient)
+
+      doc = lenient.from_json({ "component" => [
+        { "type" => "guidance", "text" => "g" },
+        { "type" => "other", "text" => "x" },
+      ] }.to_json)
+      expect(doc.guidance.map(&:text)).to eq(["g"])
+    end
+  end
+
+  describe "toml arrays of tables" do
+    let(:toml_holder) do
+      Class.new(Lutaml::Model::Serializable) do
+        attribute :guidance, KvWhenComponent, collection: true
+        attribute :purpose, KvWhenComponent, collection: true
+
+        toml do
+          map "component", to: :guidance,
+                           when_attribute: { "type" => "guidance" }
+          map "component", to: :purpose,
+                           when_attribute: { "type" => "purpose" }
+        end
+      end
+    end
+
+    it "partitions and round-trips" do
+      stub_const("KvWhen::TomlHolder", toml_holder)
+      src = <<~TOML
+        [[component]]
+        type = "guidance"
+        text = "g1"
+
+        [[component]]
+        type = "purpose"
+        text = "p1"
+      TOML
+
+      doc = toml_holder.from_toml(src)
+      expect(doc.guidance.map(&:text)).to eq(["g1"])
+      expect(doc.purpose.map(&:text)).to eq(["p1"])
+
+      again = toml_holder.from_toml(doc.to_toml)
+      expect(again.guidance.map(&:text)).to eq(["g1"])
+      expect(again.purpose.map(&:text)).to eq(["p1"])
+    end
+  end
+
+  describe "DSL validation" do
+    it "rejects non-string/symbol pairs" do
+      expect do
+        Class.new(Lutaml::Model::Serializable) do
+          attribute :x, :string
+
+          json do
+            map "x", to: :x, when_attribute: { "type" => 42 }
+          end
+        end
+      end.to raise_error(Lutaml::Model::IncorrectMappingArgumentsError, /when_attribute/)
+    end
+
+    it "rejects unmatched without when_attribute" do
+      expect do
+        Class.new(Lutaml::Model::Serializable) do
+          attribute :x, :string
+
+          json do
+            map "x", to: :x, unmatched: :raise
+          end
+        end
+      end.to raise_error(Lutaml::Model::IncorrectMappingArgumentsError, /when_attribute/)
+    end
+
+    it "rejects unknown policy values" do
+      expect do
+        Class.new(Lutaml::Model::Serializable) do
+          attribute :x, :string
+
+          json do
+            map "x", to: :x, when_attribute: { "type" => "a" },
+                     unmatched: :explode
+          end
+        end
+      end.to raise_error(Lutaml::Model::IncorrectMappingArgumentsError, /unmatched/)
+    end
+
+    it "rejects when_attribute combined with custom methods" do
+      expect do
+        Class.new(Lutaml::Model::Serializable) do
+          attribute :x, :string
+
+          json do
+            map "x", to: :x, when_attribute: { "type" => "a" },
+                     with: { to: :x_to, from: :x_from }
+          end
+        end
+      end.to raise_error(Lutaml::Model::IncorrectMappingArgumentsError, /when_attribute/)
+    end
+
+    it "survives deep_dup of mappings" do
+      rule = KvWhenRequirement.mappings_for(:json).mappings.find do |r|
+        r.to == :guidance
+      end
+
+      expect(rule.when_attribute).to eq("type" => "guidance")
+      expect(rule.deep_dup.when_attribute).to eq("type" => "guidance")
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lutaml-model
 version: !ruby/object:Gem::Version
-  version: 0.8.45
+  version: 0.8.46
 platform: ruby
 authors:
 - Ribose Inc.
@@ -1688,6 +1688,7 @@ files:
 - spec/lutaml/key_value/transformation/rule_compiler_spec.rb
 - spec/lutaml/key_value/transformation/value_serializer_spec.rb
 - spec/lutaml/key_value/transformation_spec.rb
+- spec/lutaml/key_value/when_attribute_spec.rb
 - spec/lutaml/model/absent_value_contracts_spec.rb
 - spec/lutaml/model/adapter_resolver_configured_spec.rb
 - spec/lutaml/model/attribute_apply_value_map_spec.rb