lutaml-model 0.8.43 → 0.8.45

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fe2357c36c2a199a3788090dffd420874612482e21e7ac678bd5f1e6fdd575ce
-  data.tar.gz: a3d601af07558b2915dce9f4df383c00b905505c8fbcd192a89ad88b3e66ea49
+  metadata.gz: 07e6ecf8e0047cd91862259a5a9db3b1cfb09122e752cdd17a4523d7169c89c5
+  data.tar.gz: 5fd97454986a0d0f4bd1f13d75af01d0a692618acd9fafcc702bfaea7a73827f
 SHA512:
-  metadata.gz: c82bb3761127b4beb8f2d267a60d107d69eb509cd2fd094763eed5ab5d0814497252db4cd1311709072ab829b156aac46f839852bcc4f20f37e627aa7b5daea7
-  data.tar.gz: 32aa679d229c03ccccf0ee8f1359f9559309b92f5493a0207fd5a495e0f8ef1a0cc3255a0e4e30c2e7c5319e8910a8863286116d6a0e4bfe72af1a0b8be2c71f
+  metadata.gz: d95d9d885d0fbc63200900751b75c62282b63970f3fe4ebb1707ff134452bd57d714b8aad22f2253b70ea9509d1456dfd6bbee2a43f3cb292de8ae87959ab617
+  data.tar.gz: 455d7af1865469474d7f11f623dede9fbd65311dabaa30c0546a0193bdfbab4e99356b50ca6e8ffa2deb5f108ca0d5e2de9bf112e03ce607328c9ff4e6de0a8d

data/docs/_guides/advanced-mapping.adoc

@@ -592,5 +592,56 @@ writes that attribute).
 
 Co-occurrence semantics: several `when_attribute` rules may share the
 element name; each target attribute fills independently, so declare each
-as `collection: true` when the element repeats. Rules without
-`when_attribute` keep claiming every occurrence of their name as before.
+as `collection: true` when the element repeats. A rule without
+`when_attribute` that shares the name only claims occurrences no
+discriminator rule claimed, so every occurrence is captured exactly once.
+
+By default an occurrence no rule claims — an uncovered discriminator
+value, or a missing discriminator attribute — is silently dropped.
+Declare `unmatched: :raise` on a discriminator rule to fail the parse
+instead: `Lutaml::Model::UnknownDiscriminatorError` names the element and
+the unclaimed discriminator values. A plain rule sharing the name claims
+everything left, so the strict policy never fires when one is present.
+
+[source,ruby]
+----
+xml do
+  element "requirement"
+  map_element "component", to: :guidance,
+                           when_attribute: { "type" => "guidance" },
+                           unmatched: :raise
+end
+----
+
+`when_attribute` and `polymorphic:` are two different dispatch axes over
+the same discriminator idea — pick by what the discriminator selects:
+
+* `polymorphic: { attribute:, class_map: }` — the value selects the
+  **class** each occurrence hydrates into; ONE attribute holds every
+  occurrence. See the polymorphic models tutorial.
+* `when_attribute:` — the value selects **which attribute** claims the
+  occurrence; the declared type stays fixed.
+
+They compose: a rule may partition with `when_attribute` while its
+attribute dispatches classes with `polymorphic`.
+
+Under an `ordered` mapping, serialization preserves the original
+interleaving: `element_order` records each occurrence's attributes, and
+the ordered walk routes every occurrence back to the rule whose
+discriminator it satisfies.
+
+[source,ruby]
+----
+xml do
+  element "requirement"
+  ordered
+  map_element "component", to: :guidance,
+                           when_attribute: { "type" => "guidance" }
+  map_element "component", to: :purpose,
+                           when_attribute: { "type" => "purpose" }
+end
+----
+
+Given `<component type="guidance">`, `<component type="purpose">`,
+`<component type="guidance">` in the source, `to_xml` re-emits exactly
+that guidance, purpose, guidance sequence.

data/docs/_tutorials/polymorphic-models-tutorial.adoc

@@ -9,6 +9,8 @@ nav_order: 8
 
 Polymorphic attributes allow an attribute to accept multiple types of values. This is useful when attributes share common characteristics but have type-specific behaviors.
 
+NOTE: Polymorphism dispatches the *class* of each hydrated item into one attribute. If the discriminator instead needs to route occurrences of a shared element name into *different attributes* (e.g. `component[@type='guidance']` → `guidance`, `component[@type='purpose']` → `purpose`), that is `when_attribute:` in the advanced mapping guide — the two compose on one rule.
+
 == Understanding polymorphism
 
 A polymorphic attribute can accept instances of different classes that share a common base class.

data/lib/compat/opal/lutaml_model_boot.rb

@@ -283,6 +283,7 @@ require "lutaml/model/error/type_only_namespace_error"
 require "lutaml/model/error/undefined_attribute_error"
 require "lutaml/model/error/union_schema_unsupported_error"
 require "lutaml/model/error/unknown_adapter_type_error"
+require "lutaml/model/error/unknown_discriminator_error"
 require "lutaml/model/error/unknown_sequence_mapping_error"
 require "lutaml/model/error/unknown_type_error"
 require "lutaml/model/error/unresolvable_type_error"

data/lib/lutaml/model/error/unknown_discriminator_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Model
+    # Raised when a `when_attribute` rule declared `unmatched: :raise`
+    # parses an occurrence that no rule claims: it matches no
+    # discriminator and no plain rule shares the wire name.
+    class UnknownDiscriminatorError < Error
+    end
+  end
+end

data/lib/lutaml/model/version.rb

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

data/lib/lutaml/model.rb

@@ -138,6 +138,8 @@ module Lutaml
     autoload :ElementCountOutOfRangeError,
              "#{__dir__}/model/error/element_count_out_of_range_error"
     autoload :ValidationError, "#{__dir__}/model/error/validation_error"
+    autoload :UnknownDiscriminatorError,
+             "#{__dir__}/model/error/unknown_discriminator_error"
     autoload :TypeNotEnabledError,
              "#{__dir__}/model/error/type_not_enabled_error"
     autoload :TypeError, "#{__dir__}/model/error/type_error"

data/lib/lutaml/xml/adapter_element.rb

@@ -302,7 +302,8 @@ module Lutaml
               Lutaml::Xml::Element.new("Element", child.unprefixed_name,
                                        node_type: :element,
                                        namespace_uri: child.namespace_uri,
-                                       namespace_prefix: child.namespace_prefix)
+                                       namespace_prefix: child.namespace_prefix,
+                                       attributes: order_entry_attributes(child))
             end
           end
         end.each(&:freeze).freeze

data/lib/lutaml/xml/element.rb

@@ -4,7 +4,7 @@ module Lutaml
       include Lutaml::Model::Liquefiable
 
       attr_reader :type, :name, :text_content, :node_type, :namespace_uri,
-                  :namespace_prefix
+                  :namespace_prefix, :attributes
 
       # Create a new Element for order tracking
       #
@@ -14,8 +14,13 @@ module Lutaml
       # @param node_type [Symbol, nil] The node type (:text, :cdata, :element, :comment, :processing_instruction)
       # @param namespace_uri [String, nil] The namespace URI of this element
       # @param namespace_prefix [String, nil] The namespace prefix of this element
+      # @param attributes [::Hash{String=>String}, nil] The element's
+      #   attributes keyed by namespaced name. Only element entries parsed
+      #   from a document carry them, so `when_attribute` rules can tell
+      #   same-name entries apart on ordered serialization.
       def initialize(type, name, text_content: nil, node_type: nil,
-                     namespace_uri: nil, namespace_prefix: nil)
+                     namespace_uri: nil, namespace_prefix: nil,
+                     attributes: nil)
         @type = type # "Text" or "Element" - deprecated, kept for backward compatibility
         @name = name
         # Infer node_type from type for backward compatibility if not provided
@@ -26,6 +31,7 @@ module Lutaml
         @text_content ||= name if text? || cdata?
         @namespace_uri = namespace_uri
         @namespace_prefix = namespace_prefix
+        @attributes = attributes&.freeze
       end
 
       # Check if this is a text content node (not CDATA)

data/lib/lutaml/xml/mapping.rb

@@ -528,6 +528,7 @@ module Lutaml
       transform: {},
       value_map: {},
       when_attribute: {},
+      unmatched: :drop,
       form: nil,
       documentation: nil,
       xsd_type: (xsd_type_provided = false
@@ -539,6 +540,7 @@ module Lutaml
         )
 
         validate_when_attribute!(when_attribute) unless when_attribute.empty?
+        validate_unmatched!(unmatched, when_attribute)
 
         # Warn if prefix parameter is provided
         if prefix_provided != false
@@ -588,6 +590,7 @@ module Lutaml
           documentation: documentation,
           raw: raw,
           when_attribute: when_attribute,
+          unmatched: unmatched,
         )
         # Store rules with the same element name in an array to support
         # multiple mapping rules for the same element name with different target types
@@ -625,6 +628,21 @@ module Lutaml
         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/lib/lutaml/xml/mapping_rule.rb

@@ -11,7 +11,8 @@ module Lutaml
                   :delimiter,
                   :form,
                   :documentation,
-                  :raw
+                  :raw,
+                  :unmatched
 
       # Writers for deep_dup (preserves exact object references)
       attr_accessor :namespace, :prefix, :namespace_class
@@ -38,6 +39,7 @@ module Lutaml
       transform: {},
       value_map: {},
       when_attribute: {},
+      unmatched: :drop,
       as_list: nil,
       delimiter: nil,
       form: nil,
@@ -66,6 +68,9 @@ module Lutaml
         # Store original namespace parameter to preserve :inherit symbol
         @namespace_param = namespace
 
+        # lutaml-model#88: policy for occurrences claimed by no rule
+        @unmatched = unmatched
+
         # Normalize namespace to XmlNamespace class
         @namespace_class = normalize_namespace(namespace)
         @namespace = @namespace_class == :blank ? nil : @namespace_class&.uri
@@ -273,6 +278,7 @@ module Lutaml
           documentation: @documentation,
           raw: @raw,
           when_attribute: when_attribute,
+          unmatched: @unmatched,
         ).tap do |dup_rule|
           # Manually preserve the exact @namespace_class object to avoid
           # recreating anonymous classes (which would have different object_ids)

data/lib/lutaml/xml/model_transform.rb

@@ -859,6 +859,35 @@ _effective_register)
         cache[type_class] = type_class.mappings_for(:xml)&.namespace_class
       end
 
+      # lutaml-model#88: fail closed for `unmatched: :raise`. An
+      # occurrence no rule on the wire name claims — no discriminator
+      # match, no plain sibling — is exactly the data the default policy
+      # silently drops.
+      def check_unmatched_discriminators!(children, rule, rule_names, session)
+        plain_names = session.plain_element_rule_names
+        return if rule_names.any? { |name| plain_names[name] }
+
+        group = rule_names.filter_map do |name|
+          session.when_attribute_siblings_by_name[name]
+        end.flatten
+        tested = group.flat_map { |sibling| sibling.when_attribute.keys }
+          .uniq.map(&:to_s)
+        children.each do |child|
+          next if group.any? { |sibling| sibling.matches_when_attribute?(child) }
+
+          values = tested.filter_map do |name|
+            value = child.find_attribute_value(name)
+            "#{name}=#{value.inspect}" if value
+          end
+          raise ::Lutaml::Model::UnknownDiscriminatorError,
+                "Element <#{rule.name}> (#{values.join(', ')}) is claimed by " \
+                "no rule: it matches no when_attribute discriminator and no " \
+                "plain rule shares the name. Cover the value, add a plain " \
+                "rule, or opt out with unmatched: :drop"
+        end
+        nil
+      end
+
       def value_for_rule(session, rule, options, cached_attr = nil,
                          extra_rule_names = nil)
         doc = session.doc
@@ -1053,11 +1082,27 @@ _effective_register)
 
         # lutaml-model#88: attribute-value discriminator — among the
         # name-matched occurrences, keep only those whose sibling
-        # attributes carry the expected values.
+        # attributes carry the expected values. A plain rule sharing the
+        # name with discriminator rules gets the complement — occurrences
+        # no discriminator claimed — so each occurrence is captured
+        # exactly once, mirroring ordered-serialization routing.
         if rule.when_attribute?
+          if rule.unmatched == :raise
+            check_unmatched_discriminators!(children, rule, rule_names, session)
+          end
           children = children.select do |child|
             rule.matches_when_attribute?(child)
           end
+        else
+          siblings = session.when_attribute_siblings_by_name
+          unless siblings.empty?
+            claimed = rule_names.filter_map { |n| siblings[n] }.flatten
+            unless claimed.empty?
+              children = children.reject do |child|
+                claimed.any? { |sibling| sibling.matches_when_attribute?(child) }
+              end
+            end
+          end
         end
 
         # Performance: Cache rule method check before loop to avoid repeated method calls

data/lib/lutaml/xml/parse_session.rb

@@ -65,6 +65,50 @@ module Lutaml
         end
       end
 
+      # lutaml-model#88: element wire names partitioned by `when_attribute`
+      # rules. One pass builds two views over the mapping's element rules:
+      #
+      # - name -> discriminator rules. A plain rule on a partitioned name
+      #   captures only occurrences no discriminator claimed — the mirror
+      #   of ordered-serialization routing, so each occurrence is captured
+      #   exactly once instead of double-captured by the plain rule and
+      #   its discriminator sibling.
+      # - name -> true when a plain element rule also holds the name.
+      #   Everything on the name is then claimed, so `unmatched: :raise`
+      #   never fires.
+      #
+      # Empty unless the mapping uses when_attribute at all; non-Serialize
+      # custom models have no mappings to partition.
+      def when_attribute_partition
+        @when_attribute_partition ||=
+          if instance_is_serialize && (mapping = xml_mapping)
+            siblings = {}
+            plain_names = {}
+            mapping.mappings.each do |rule|
+              next if rule.attribute? || rule.content_mapping? ||
+                rule.raw_mapping? || rule.cdata
+
+              pairs = rule.when_attribute
+              if pairs && !pairs.empty?
+                (siblings[rule.name.to_s] ||= []) << rule
+              else
+                plain_names[rule.name.to_s] = true
+              end
+            end
+            [siblings, plain_names]
+          else
+            [{}, {}]
+          end
+      end
+
+      def when_attribute_siblings_by_name
+        when_attribute_partition[0]
+      end
+
+      def plain_element_rule_names
+        when_attribute_partition[1]
+      end
+
       def model_class
         @model_class ||= instance.class
       end

data/lib/lutaml/xml/transformation/order_reconciler.rb

@@ -220,25 +220,40 @@ module Lutaml
         # accepts a nil rule namespace, namespace aliases and name aliases.
         # When more than one rule would claim the entry, reconciling would
         # feed the value to the wrong rule, so leave the rule alone.
+        # Rules distinguished by `when_attribute` are separate rules: their
+        # inserted entries carry the discriminator attributes, so they
+        # resolve back correctly.
         def unambiguous?(rule, element_rules)
+          discriminator = rule_discriminator(rule)
           matches = element_rules.select do |candidate|
             matches_element_rule?(candidate, rule.serialized_name,
-                                  rule.namespace_class&.uri)
+                                  rule.namespace_class&.uri) &&
+              rule_discriminator(candidate) == discriminator
           end
 
           matches == [rule]
         end
 
         def new_order_entry(rule)
+          discriminator = rule_discriminator(rule)
           ::Lutaml::Xml::Element.new(
             "Element",
             rule.serialized_name,
             node_type: :element,
             namespace_uri: rule.namespace_class&.uri,
             namespace_prefix: nil,
+            attributes: discriminator && discriminator_attributes(discriminator),
           )
         end
 
+        # The discriminator pairs as order-entry attributes, so an inserted
+        # entry routes back to its own rule at emit time and re-parses.
+        def discriminator_attributes(pairs)
+          pairs.each_with_object({}) do |(name, value), attrs|
+            attrs[name.to_s] = value.to_s
+          end
+        end
+
         # Where a rule's new entries go:
         # - after the last entry that already resolves to it, so extra
         #   collection items follow the existing ones and any interleaved

data/lib/lutaml/xml/transformation/ordered_applier.rb

@@ -122,6 +122,14 @@ model_class, register_id)
 
         # Find the mapping rule for an element from element_order
         #
+        # Same-name entries under different `when_attribute` discriminators
+        # (all `<component>`s, distinguished by `type="guidance"` vs
+        # `type="purpose"`) route to the rule whose discriminator pairs the
+        # entry's recorded attributes satisfy. Entries carrying no
+        # attributes — built before the entry format carried them, or
+        # inserted by hand — fall back to the first plain rule, which is
+        # the pre-discriminator behavior.
+        #
         # @param object [Xml::Element] Element from element_order
         # @param compiled_rules [Array<CompiledRule>] The compiled rules
         # @return [CompiledRule, nil] The matching rule or nil
@@ -131,11 +139,23 @@ model_class, register_id)
 
           object_ns_uri = object.namespace_uri # nil if old element_order (backward compat)
 
-          compiled_rules.find do |r|
-            r.is_a?(::Lutaml::Model::CompiledRule) &&
+          first = nil
+          shared_name = false
+          compiled_rules.each do |r|
+            next unless r.is_a?(::Lutaml::Model::CompiledRule) &&
               r.option(:mapping_type) == :element &&
               matches_element_rule?(r, object.name, object_ns_uri)
+
+            if first.nil?
+              first = r
+            else
+              shared_name = true
+              break
+            end
           end
+          return first unless shared_name
+
+          resolve_shared_name_rule(object, compiled_rules, object_ns_uri)
         end
 
         private
@@ -175,6 +195,57 @@ model_class, register_id)
           rule.matches_name?(name) && rule_ns_matches
         end
 
+        # Pick among rules sharing a serialized name when the entry's
+        # recorded attributes are the only thing that tells them apart.
+        #
+        # A discriminator rule whose pairs the entry satisfies wins over
+        # any plain rule regardless of declaration order, because a plain
+        # rule would claim EVERY same-name entry including discriminated
+        # ones. Entries matching no discriminator pair — an unknown value,
+        # or an entry without attributes — fall back to the first plain
+        # rule.
+        def resolve_shared_name_rule(object, compiled_rules, object_ns_uri)
+          plain = nil
+          compiled_rules.each do |r|
+            next unless r.is_a?(::Lutaml::Model::CompiledRule) &&
+              r.option(:mapping_type) == :element &&
+              matches_element_rule?(r, object.name, object_ns_uri)
+
+            pairs = rule_discriminator(r)
+            return r if pairs && entry_matches_when_attribute?(object, pairs)
+
+            plain ||= r if pairs.nil?
+          end
+          plain
+        end
+
+        # The rule's `when_attribute` discriminator pairs, or nil for a
+        # plain rule. Shared by OrderedApplier and OrderReconciler since
+        # both run on the same transform host.
+        #
+        # @param rule [CompiledRule]
+        # @return [::Hash, nil]
+        def rule_discriminator(rule)
+          pairs = rule.option(:when_attribute)
+          pairs && !pairs.empty? ? pairs : nil
+        end
+
+        # Whether an order entry's recorded attributes satisfy a rule's
+        # discriminator pairs. Mirrors Xml::MappingRule#matches_when_attribute?
+        # — non-nil and string-equal — against the namespaced-name keying
+        # the entries record.
+        def entry_matches_when_attribute?(object, pairs)
+          return false unless object.is_a?(::Lutaml::Xml::Element)
+
+          attrs = object.attributes
+          return false if attrs.nil?
+
+          pairs.all? do |name, expected|
+            actual = attrs[name.to_s]
+            !actual.nil? && actual.to_s == expected.to_s
+          end
+        end
+
         def process_element_order_item(object, root, model_instance, options,
 compiled_rules, _mapping, element_indices,
 content_rule = nil, text_node_index = 0,

data/lib/lutaml/xml/xml_element.rb

@@ -284,11 +284,30 @@ module Lutaml
             Lutaml::Xml::Element.new("Element", child.unprefixed_name,
                                      node_type: :element,
                                      namespace_uri: child.namespace_uri,
-                                     namespace_prefix: child.namespace_prefix)
+                                     namespace_prefix: child.namespace_prefix,
+                                     attributes: order_entry_attributes(child))
           end
         end.each(&:freeze).freeze
       end
 
+      # The attributes an element-order entry records, keyed by namespaced
+      # name — the same key find_attribute_value indexes. Same-name entries
+      # under different `when_attribute` discriminators need them to route
+      # back to the right rule on ordered serialization. nil for attribute-
+      # less children keeps the common entry allocation-free.
+      #
+      # @param child [XmlElement] An element child of this node
+      # @return [::Hash{String=>String}, nil]
+      def order_entry_attributes(child)
+        return if child.attributes.empty?
+
+        attrs = {}
+        child.attributes.each_value do |attr|
+          attrs[attr.namespaced_name] = attr.value
+        end
+        attrs.freeze
+      end
+
       def root
         self
       end

data/spec/lutaml/xml/when_attribute_ordered_spec.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# lutaml-model#88: `when_attribute` partitioning under `ordered` mappings.
+# The ordered walk routes each element_order entry by its recorded
+# attributes, so `<component type="guidance">` and `<component
+# type="purpose">` interleave on to_xml exactly as the source document did.
+class WhenOrderedComponent < Lutaml::Model::Serializable
+  attribute :text, :string
+
+  xml do
+    element "component"
+    map_element "text", to: :text
+  end
+end
+
+class WhenOrderedRequirement < Lutaml::Model::Serializable
+  attribute :guidance, WhenOrderedComponent, collection: true
+  attribute :purpose, WhenOrderedComponent, collection: true
+  attribute :test_method, WhenOrderedComponent, collection: true
+
+  xml do
+    element "requirement"
+    ordered
+    map_element "component", to: :guidance,
+                             when_attribute: { "type" => "guidance" }
+    map_element "component", to: :purpose,
+                             when_attribute: { "type" => "purpose" }
+    map_element "component", to: :test_method,
+                             when_attribute: { type: "test-method" }
+  end
+end
+
+RSpec.describe "when_attribute under ordered mappings" do
+  before do
+    stub_const("WhenOrdered::Component", WhenOrderedComponent)
+    stub_const("WhenOrdered::Requirement", WhenOrderedRequirement)
+  end
+
+  let(:xml) do
+    <<~XML
+      <requirement>
+        <component type="guidance"><text>g1</text></component>
+        <component type="purpose"><text>p1</text></component>
+        <component type="guidance"><text>g2</text></component>
+        <component type="test-method"><text>t1</text></component>
+      </requirement>
+    XML
+  end
+
+  def serialized_types(doc)
+    doc.scan(/<component type="([^"]+)">/).flatten
+  end
+
+  it "parses partitioned values" do
+    req = WhenOrderedRequirement.from_xml(xml)
+
+    expect(req.guidance.map(&:text)).to eq(%w[g1 g2])
+    expect(req.purpose.map(&:text)).to eq(["p1"])
+    expect(req.test_method.map(&:text)).to eq(["t1"])
+  end
+
+  it "records the discriminator attributes on element_order entries" do
+    req = WhenOrderedRequirement.from_xml(xml)
+    entries = req.element_order.select { |e| e.type == "Element" }
+
+    expect(entries.map(&:attributes)).to eq([
+                                              { "type" => "guidance" },
+                                              { "type" => "purpose" },
+                                              { "type" => "guidance" },
+                                              { "type" => "test-method" },
+                                            ])
+  end
+
+  it "round-trips the original interleaving" do
+    round = WhenOrderedRequirement.from_xml(xml).to_xml
+
+    expect(serialized_types(round)).to eq(
+      %w[guidance purpose guidance test-method],
+    )
+  end
+
+  it "survives a re-parse of the ordered output" do
+    once = WhenOrderedRequirement.from_xml(xml)
+    twice = WhenOrderedRequirement.from_xml(once.to_xml)
+
+    expect(twice.guidance.map(&:text)).to eq(%w[g1 g2])
+    expect(twice.purpose.map(&:text)).to eq(["p1"])
+    expect(twice.test_method.map(&:text)).to eq(["t1"])
+  end
+
+  it "routes appended items to the right attribute on ordered output" do
+    req = WhenOrderedRequirement.from_xml(xml)
+    req.guidance << WhenOrderedComponent.new(text: "g3")
+
+    out = req.to_xml
+    # Reconciliation places new entries after the rule's last existing
+    # occurrence (the OrderReconciler contract), not at document end.
+    expect(serialized_types(out)).to eq(
+      %w[guidance purpose guidance guidance test-method],
+    )
+
+    reparsed = WhenOrderedRequirement.from_xml(out)
+    expect(reparsed.guidance.map(&:text)).to eq(%w[g1 g2 g3])
+    expect(reparsed.purpose.map(&:text)).to eq(["p1"])
+  end
+
+  it "drops occurrences with an unknown discriminator from ordered output" do
+    with_unknown = WhenOrderedRequirement.from_xml(<<~XML)
+      <requirement>
+        <component type="guidance"><text>g1</text></component>
+        <component type="unknown"><text>x</text></component>
+        <component type="purpose"><text>p1</text></component>
+      </requirement>
+    XML
+
+    expect(with_unknown.guidance.map(&:text)).to eq(["g1"])
+    expect(with_unknown.purpose.map(&:text)).to eq(["p1"])
+    expect(serialized_types(with_unknown.to_xml)).to eq(%w[guidance purpose])
+  end
+
+  it "falls back to the plain rule for legacy attribute-less entries" do
+    both = Class.new(Lutaml::Model::Serializable) do
+      attribute :plain, :string
+      attribute :special, :string
+
+      xml do
+        element "holder"
+        ordered
+        map_element "item", to: :plain
+        map_element "item", to: :special, when_attribute: { "kind" => "special" }
+      end
+    end
+    stub_const("WhenOrdered::Holder", both)
+
+    doc = both.from_xml(
+      "<holder><item>a</item><item kind=\"special\">b</item></holder>",
+    )
+
+    expect(doc.plain).to eq("a")
+    expect(doc.special).to eq("b")
+
+    out = doc.to_xml
+    expect(out.scan(%r{<item[^>]*>([^<]*)</item>})).to eq([["a"], ["b"]])
+    expect(out).to include('kind="special"')
+  end
+end

data/spec/lutaml/xml/when_attribute_spec.rb

@@ -130,4 +130,96 @@ RSpec.describe "when_attribute discriminator mappings" do
       end
     end.to raise_error(ArgumentError)
   end
+
+  # Orthogonality guard: `when_attribute` partitions occurrences across
+  # attributes; `polymorphic` dispatches the class of each hydrated item.
+  # Different axes over the same discriminator concept — they compose on
+  # one rule rather than substitute for each other.
+  describe "vs polymorphic dispatch" do
+    before do
+      stub_const("AxisComp", Class.new(Lutaml::Model::Serializable) do
+        attribute :text, :string
+      end)
+      stub_const("AxisGuidanceComp", Class.new(AxisComp))
+      stub_const("AxisPurposeComp", Class.new(AxisComp))
+    end
+
+    let(:axes_xml) do
+      <<~XML
+        <req>
+          <component type="guidance"><text>g1</text></component>
+          <component type="purpose"><text>p1</text></component>
+          <component type="guidance"><text>g2</text></component>
+        </req>
+      XML
+    end
+
+    it "polymorphic keeps one attribute and dispatches classes" do
+      poly = Class.new(Lutaml::Model::Serializable) do
+        attribute :components, AxisComp, collection: true
+
+        xml do
+          element "req"
+          map_element "component", to: :components, polymorphic: {
+            attribute: "type",
+            class_map: {
+              "guidance" => "AxisGuidanceComp",
+              "purpose" => "AxisPurposeComp",
+            },
+          }
+        end
+      end
+
+      parsed = poly.from_xml(axes_xml)
+      expect(parsed.components.map(&:class))
+        .to eq([AxisGuidanceComp, AxisPurposeComp, AxisGuidanceComp])
+    end
+
+    it "when_attribute keeps one class and partitions attributes" do
+      partitioned = Class.new(Lutaml::Model::Serializable) do
+        attribute :guidance, AxisComp, collection: true
+        attribute :purpose, AxisComp, collection: true
+
+        xml do
+          element "req"
+          map_element "component", to: :guidance,
+                                   when_attribute: { "type" => "guidance" }
+          map_element "component", to: :purpose,
+                                   when_attribute: { "type" => "purpose" }
+        end
+      end
+
+      parsed = partitioned.from_xml(axes_xml)
+      expect(parsed.guidance.map(&:text)).to eq(%w[g1 g2])
+      expect(parsed.purpose.map(&:text)).to eq(["p1"])
+      expect(parsed.guidance.first.class).to eq(AxisComp)
+    end
+
+    it "composes: partition and class dispatch on the same rule" do
+      both = Class.new(Lutaml::Model::Serializable) do
+        attribute :guidance, AxisComp, collection: true
+        attribute :purpose, AxisComp, collection: true
+
+        xml do
+          element "req"
+          map_element "component", to: :guidance,
+                                   when_attribute: { "type" => "guidance" },
+                                   polymorphic: {
+                                     attribute: "type",
+                                     class_map: { "guidance" => "AxisGuidanceComp" },
+                                   }
+          map_element "component", to: :purpose,
+                                   when_attribute: { "type" => "purpose" },
+                                   polymorphic: {
+                                     attribute: "type",
+                                     class_map: { "purpose" => "AxisPurposeComp" },
+                                   }
+        end
+      end
+
+      parsed = both.from_xml(axes_xml)
+      expect(parsed.guidance.map(&:class)).to eq([AxisGuidanceComp, AxisGuidanceComp])
+      expect(parsed.purpose.map(&:class)).to eq([AxisPurposeComp])
+    end
+  end
 end

data/spec/lutaml/xml/when_attribute_unmatched_spec.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# lutaml-model#88: `unmatched: :raise` on a when_attribute rule fails the
+# parse when an occurrence is claimed by no rule — no discriminator match
+# and no plain sibling on the wire name. The default (:drop) keeps the
+# silent-drop behavior.
+class UnmatchedComponent < Lutaml::Model::Serializable
+  attribute :text, :string
+
+  xml do
+    element "component"
+    map_element "text", to: :text
+  end
+end
+
+class UnmatchedRequirement < Lutaml::Model::Serializable
+  attribute :guidance, UnmatchedComponent, collection: true
+  attribute :purpose, UnmatchedComponent, collection: true
+
+  xml do
+    element "requirement"
+    map_element "component", to: :guidance,
+                             when_attribute: { "type" => "guidance" },
+                             unmatched: :raise
+    map_element "component", to: :purpose,
+                             when_attribute: { "type" => "purpose" }
+  end
+end
+
+RSpec.describe "when_attribute unmatched policy" do
+  before do
+    stub_const("Unmatched::Component", UnmatchedComponent)
+    stub_const("Unmatched::Requirement", UnmatchedRequirement)
+  end
+
+  it "parses when every occurrence is covered" do
+    req = UnmatchedRequirement.from_xml(<<~XML)
+      <requirement>
+        <component type="guidance"><text>g1</text></component>
+        <component type="purpose"><text>p1</text></component>
+      </requirement>
+    XML
+
+    expect(req.guidance.map(&:text)).to eq(["g1"])
+    expect(req.purpose.map(&:text)).to eq(["p1"])
+  end
+
+  it "raises on an unknown discriminator value" do
+    xml = <<~XML
+      <requirement>
+        <component type="guidance"><text>g1</text></component>
+        <component type="unknown"><text>x</text></component>
+      </requirement>
+    XML
+
+    expect { UnmatchedRequirement.from_xml(xml) }
+      .to raise_error(Lutaml::Model::UnknownDiscriminatorError, /type="unknown"/)
+  end
+
+  it "raises when the discriminator attribute is missing entirely" do
+    xml = "<requirement><component><text>x</text></component></requirement>"
+
+    expect { UnmatchedRequirement.from_xml(xml) }
+      .to raise_error(Lutaml::Model::UnknownDiscriminatorError, /<component>/)
+  end
+
+  it "names the tested attributes of the unclaimed occurrence" do
+    xml = '<requirement><component type="later"><text>x</text></component></requirement>'
+
+    expect { UnmatchedRequirement.from_xml(xml) }
+      .to raise_error(Lutaml::Model::UnknownDiscriminatorError, /unmatched: :drop/)
+  end
+
+  it "does not raise when a plain rule claims the leftovers" do
+    both = Class.new(Lutaml::Model::Serializable) do
+      attribute :special, UnmatchedComponent, collection: true
+      attribute :plain, UnmatchedComponent, collection: true
+
+      xml do
+        element "holder"
+        map_element "item", to: :special,
+                            when_attribute: { "kind" => "special" },
+                            unmatched: :raise
+        map_element "item", to: :plain
+      end
+    end
+    stub_const("Unmatched::Holder", both)
+
+    doc = both.from_xml(
+      '<holder><item kind="special"><text>b</text></item><item><text>a</text></item></holder>',
+    )
+
+    expect(doc.special.map(&:text)).to eq(["b"])
+    expect(doc.plain.map(&:text)).to eq(["a"])
+  end
+
+  it "drops unmatched occurrences by default" do
+    lenient = Class.new(Lutaml::Model::Serializable) do
+      attribute :guidance, UnmatchedComponent, collection: true
+
+      xml do
+        element "requirement"
+        map_element "component", to: :guidance,
+                                 when_attribute: { "type" => "guidance" }
+      end
+    end
+    stub_const("Unmatched::Lenient", lenient)
+
+    doc = lenient.from_xml(
+      '<requirement><component type="guidance"><text>g</text></component>' \
+      '<component type="other"><text>x</text></component></requirement>',
+    )
+    expect(doc.guidance.map(&:text)).to eq(["g"])
+  end
+
+  it "survives deep_dup of mappings" do
+    rule = UnmatchedRequirement.mappings_for(:xml).mappings.find do |r|
+      r.to == :guidance
+    end
+
+    expect(rule.unmatched).to eq(:raise)
+    duped = rule.deep_dup
+    expect(duped.unmatched).to eq(:raise)
+    expect(duped.when_attribute).to eq("type" => "guidance")
+  end
+
+  it "rejects unknown policy values" do
+    expect do
+      Class.new(Lutaml::Model::Serializable) do
+        attribute :x, :string
+
+        xml do
+          element "x"
+          map_element "x", to: :x,
+                           when_attribute: { "type" => "a" },
+                           unmatched: :explode
+        end
+      end
+    end.to raise_error(Lutaml::Model::IncorrectMappingArgumentsError, /unmatched/)
+  end
+
+  it "rejects unmatched without when_attribute" do
+    expect do
+      Class.new(Lutaml::Model::Serializable) do
+        attribute :x, :string
+
+        xml do
+          element "x"
+          map_element "x", to: :x, unmatched: :raise
+        end
+      end
+    end.to raise_error(Lutaml::Model::IncorrectMappingArgumentsError, /when_attribute/)
+  end
+
+  it "is rejected on attribute mappings" do
+    expect do
+      Class.new(Lutaml::Model::Serializable) do
+        attribute :x, :string
+
+        xml do
+          element "x"
+          map_attribute "x", to: :x, unmatched: :raise
+        end
+      end
+    end.to raise_error(ArgumentError)
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lutaml-model
 version: !ruby/object:Gem::Version
-  version: 0.8.43
+  version: 0.8.45
 platform: ruby
 authors:
 - Ribose Inc.
@@ -489,6 +489,7 @@ files:
 - lib/lutaml/model/error/undefined_attribute_error.rb
 - lib/lutaml/model/error/union_schema_unsupported_error.rb
 - lib/lutaml/model/error/unknown_adapter_type_error.rb
+- lib/lutaml/model/error/unknown_discriminator_error.rb
 - lib/lutaml/model/error/unknown_sequence_mapping_error.rb
 - lib/lutaml/model/error/unknown_type_error.rb
 - lib/lutaml/model/error/unresolvable_type_error.rb
@@ -2006,7 +2007,9 @@ files:
 - spec/lutaml/xml/validate_xml_with_constructs_spec.rb
 - spec/lutaml/xml/validate_xml_with_spec.rb
 - spec/lutaml/xml/w3c_types_spec.rb
+- spec/lutaml/xml/when_attribute_ordered_spec.rb
 - spec/lutaml/xml/when_attribute_spec.rb
+- spec/lutaml/xml/when_attribute_unmatched_spec.rb
 - spec/lutaml/xml/xml_adapter_spec.rb
 - spec/lutaml/xml/xml_declaration_spec.rb
 - spec/lutaml/xml/xml_element_guard_spec.rb