lutaml-model 0.8.42 → 0.8.43

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1cd747883eee7ea6a87aea0c708e6054f1f6cf9f7b06e295b32f1b7ba06a8a75
-  data.tar.gz: 639b21ad4dd77104b3bce40f0ba7bad925a5b608806e6e8979b50cb68f57b70e
+  metadata.gz: fe2357c36c2a199a3788090dffd420874612482e21e7ac678bd5f1e6fdd575ce
+  data.tar.gz: a3d601af07558b2915dce9f4df383c00b905505c8fbcd192a89ad88b3e66ea49
 SHA512:
-  metadata.gz: 05174a52193320261f496e92ac656b6ddc5a47167db5b98b3682c0397a4c9fb0f2a58f20e8be689d7f35486bea63dc2228d367574c3834587be6d5ba97306cd9
-  data.tar.gz: a6efef58f862390afe6fcf903ce3ff4d829d451079b7a1762990ed0e0bf1c5623c798c712a485d8e81cdc415189a37e9c5f7b1c02dd2d03ad6c17d96b5bac5a0
+  metadata.gz: c82bb3761127b4beb8f2d267a60d107d69eb509cd2fd094763eed5ab5d0814497252db4cd1311709072ab829b156aac46f839852bcc4f20f37e627aa7b5daea7
+  data.tar.gz: 32aa679d229c03ccccf0ee8f1359f9559309b92f5493a0207fd5a495e0f8ef1a0cc3255a0e4e30c2e7c5319e8910a8863286116d6a0e4bfe72af1a0b8be2c71f

data/docs/_guides/advanced-mapping.adoc

@@ -562,3 +562,35 @@ end
 ====
 
 
+
+=== Attribute-value dispatch on a shared element name
+
+When several distinct attributes share one wire element, selected by a
+sibling attribute's value, declare the discriminator with `when_attribute:`
+
+[source,ruby]
+----
+class Requirement < Lutaml::Model::Serializable
+  attribute :guidance, Component, collection: true
+  attribute :purpose, Component, collection: true
+
+  xml do
+    element "requirement"
+    map_element "component", to: :guidance,
+                             when_attribute: { "type" => "guidance" }
+    map_element "component", to: :purpose,
+                             when_attribute: { "type" => "purpose" }
+  end
+end
+----
+
+Each rule hydrates only from the `<component>` occurrences whose `type`
+attribute carries the expected value, in document order; uncovered values
+are ignored by all discriminator rules. On serialization the discriminator
+pair is re-emitted on the element (unless the value's own mapping already
+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.

data/lib/lutaml/key_value/mapping.rb

@@ -78,7 +78,8 @@ module Lutaml
         polymorphic: {},
         polymorphic_map: {},
         transform: {},
-        value_map: {}
+        value_map: {},
+        serialize: true
       )
         mapping_name = name_for_mapping(root_mappings, name)
         validate!(mapping_name, to, with, render_nil, render_empty)
@@ -100,6 +101,7 @@ module Lutaml
           polymorphic_map: polymorphic_map,
           transform: transform,
           value_map: value_map,
+          serialize: serialize,
         )
       end
 

data/lib/lutaml/key_value/mapping_rule.rb

@@ -22,7 +22,8 @@ module Lutaml
         polymorphic: {},
         polymorphic_map: {},
         transform: {},
-        value_map: {}
+        value_map: {},
+        serialize: true
       )
         super(
           name,
@@ -41,6 +42,7 @@ module Lutaml
           polymorphic_map: polymorphic_map,
           transform: transform,
           value_map: value_map,
+          serialize: serialize,
         )
 
         @child_mappings = child_mappings
@@ -65,6 +67,7 @@ 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),
+          serialize: serialize?,
         )
       end
 

data/lib/lutaml/key_value/transform.rb

@@ -127,6 +127,8 @@ module Lutaml
       end
 
       def valid_mapping?(rule, options)
+        return false if rule.respond_to?(:serialize?) && !rule.serialize?
+
         only = options[:only]
         except = options[:except]
         name = rule.to

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

@@ -230,6 +230,7 @@ transformation_factory:)
             custom_methods: custom_methods,
             delegate: delegate,
             root_mappings: mapping_rule.root_mappings,
+            serialize: mapping_rule.serialize?,
           )
         end
 
@@ -239,6 +240,8 @@ transformation_factory:)
         # @param options [Hash] Transformation options (may contain :only, :except)
         # @return [Boolean] true if the rule should be applied
         def valid_mapping?(rule, options)
+          return false if rule.option(:serialize) == false
+
           only = options[:only]
           except = options[:except]
           name = rule.attribute_name

data/lib/lutaml/model/collection_handler.rb

@@ -61,7 +61,17 @@ module Lutaml
       # @param register [Symbol, nil] Register for custom-collection type resolution
       # @return [Object] A new collection instance
       def build_collection(*args, register: nil)
-        items = args.flatten
+        # args.flatten allocated a fresh Array even for the dominant
+        # calls: no args, or one already-flat Array from cast_items
+        # (71,949 flatten allocations per ISO-13849 parse).
+        items = if args.empty?
+                  []
+                elsif args.length == 1 && (first = args[0]).is_a?(::Array) &&
+                    first.none?(::Array)
+                  first
+                else
+                  args.flatten
+                end
         unless register && initialize_accepts_register?
           return collection_class.new(items)
         end

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

@@ -70,7 +70,9 @@ module Lutaml
         polymorphic: {},
         polymorphic_map: {},
         transform: {},
-        value_map: {}
+        value_map: {},
+        serialize: true,
+        when_attribute: {}
       )
         @name = name
         @to = to
@@ -92,6 +94,11 @@ module Lutaml
         @polymorphic = polymorphic
         @polymorphic_map = polymorphic_map
         @transform = transform
+        @serialize_mapping = serialize
+        # Attribute-value discriminator (lutaml-model#88): select this
+        # rule's wire occurrences by a sibling attribute value, e.g.
+        # `when_attribute: { "type" => "guidance" }`.
+        @when_attribute = (when_attribute || {}).freeze
 
         # Cache whether this rule needs the full deserialize chain.
         # Over 95% of rules are "simple" (no custom method, no delegate).
@@ -174,6 +181,11 @@ module Lutaml
 
       alias from name
       alias render_default? render_default
+
+      # Whether this rule participates in serialization output. False
+      # marks a hydrate-only mapping: consumed by from_* but never
+      # rendered by to_*. (The value callback #serialize is separate.)
+      def serialize? = @serialize_mapping
       alias attribute? attribute
 
       def render?(value, instance = nil, options = {})
@@ -328,6 +340,16 @@ context = nil)
       # each time (240k allocations on the ISO-13849 serialize profile).
       # Rules may be frozen, so no per-instance memo: one to_s instead
       # of two is the frozen-safe diet.
+      # Discriminator pairs this rule selects (and re-emits) on, empty
+      # for an ordinary rule.
+      def when_attribute
+        @when_attribute ||= {}.freeze
+      end
+
+      def when_attribute?
+        !when_attribute.empty?
+      end
+
       def custom_method_only?
         name = attribute_name.to_s
         (name.start_with?("__") && name.end_with?("__")) ||

data/lib/lutaml/model/serialize/initialization.rb

@@ -133,8 +133,13 @@ module Lutaml
             return cached if cached
 
             ensure_imports!(register) if finalized?
-            @merged_attributes_cache[register_id] ||=
-              @attributes.merge(@register_records[register_id][:attributes])
+            # ensure_imports! may re-entrantly run clear_cache (restrict /
+            # import resolution), which nils @merged_attributes_cache —
+            # compute the merge first and re-materialize the memo store
+            # at write time (#815: standalone to_xml on register-bound
+            # models crashed with nil[] here).
+            merged = @attributes.merge(@register_records[register_id][:attributes])
+            (@merged_attributes_cache ||= {})[register_id] = merged
           else
             ensure_imports!(register) if finalized?
             @attributes

data/lib/lutaml/model/serialize.rb

@@ -241,12 +241,21 @@ module Lutaml
       end
 
       def respond_to_missing?(method_name, include_private = false)
-        (method_name.to_s.end_with?("=") && attribute_exist?(method_name)) ||
-          super
+        # Setter probes from non-compiled dispatch land here ~24k times per
+        # ISO-13849 parse; strip the suffix once instead of re-walking
+        # attribute_exist?'s to_s/chomp/to_sym chain.
+        name = method_name.to_s
+        if name.end_with?("=") &&
+            self.class.attributes(lutaml_register)
+                .key?(name.delete_suffix("=").to_sym)
+          return true
+        end
+
+        super
       end
 
       def attribute_exist?(name)
-        name = name.to_s.chomp("=").to_sym if name.end_with?("=")
+        name = name.to_s.delete_suffix("=").to_sym if name.end_with?("=")
 
         self.class.attributes(lutaml_register).key?(name)
       end

data/lib/lutaml/model/version.rb

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

data/lib/lutaml/xml/mapping.rb

@@ -527,6 +527,7 @@ module Lutaml
                nil),
       transform: {},
       value_map: {},
+      when_attribute: {},
       form: nil,
       documentation: nil,
       xsd_type: (xsd_type_provided = false
@@ -537,6 +538,8 @@ module Lutaml
           name, to, with, render_nil, render_empty, type: TYPES[:element]
         )
 
+        validate_when_attribute!(when_attribute) unless when_attribute.empty?
+
         # Warn if prefix parameter is provided
         if prefix_provided != false
           warn "[DEPRECATED] The prefix parameter on map_element is deprecated. " \
@@ -584,6 +587,7 @@ module Lutaml
           form: form,
           documentation: documentation,
           raw: raw,
+          when_attribute: when_attribute,
         )
         # Store rules with the same element name in an array to support
         # multiple mapping rules for the same element name with different target types
@@ -607,6 +611,20 @@ 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
+
       def map_attribute(
         name,
       to: nil,
@@ -1150,7 +1168,8 @@ module Lutaml
           grouped = {}
           mappings(reg_key).each do |r|
             next if r.attribute? || r.raw_mapping? || r.content_mapping? ||
-              r.cdata || r.has_custom_method_for_deserialization? ||
+              r.cdata || r.when_attribute? ||
+              r.has_custom_method_for_deserialization? ||
               (r.transform.is_a?(Hash) && !r.transform.empty?) ||
               r.transform.is_a?(Class)
 

data/lib/lutaml/xml/mapping_rule.rb

@@ -16,7 +16,7 @@ module Lutaml
       # Writers for deep_dup (preserves exact object references)
       attr_accessor :namespace, :prefix, :namespace_class
 
-      def initialize(
+      def initialize( # rubocop:disable Metrics/ParameterLists -- mirrors the DSL surface
         name,
       to:,
       render_nil: false,
@@ -37,6 +37,7 @@ module Lutaml
       polymorphic_map: {},
       transform: {},
       value_map: {},
+      when_attribute: {},
       as_list: nil,
       delimiter: nil,
       form: nil,
@@ -59,6 +60,7 @@ module Lutaml
           polymorphic_map: polymorphic_map,
           transform: transform,
           value_map: value_map,
+          when_attribute: when_attribute,
         )
 
         # Store original namespace parameter to preserve :inherit symbol
@@ -225,6 +227,15 @@ module Lutaml
         end
       end
 
+      # Whether a parsed element satisfies this rule's when_attribute
+      # discriminator: every expected attribute value matches.
+      def matches_when_attribute?(element)
+        when_attribute.all? do |name, expected|
+          actual = element.find_attribute_value(name.to_s)
+          !actual.nil? && actual.to_s == expected.to_s
+        end
+      end
+
       def deep_dup
         # Preserve @namespace_param exactly as it was (string, Class, :inherit, or nil)
         # This ensures the duplicate has the same internal state as the original
@@ -261,6 +272,7 @@ module Lutaml
           form: @form,
           documentation: @documentation,
           raw: @raw,
+          when_attribute: when_attribute,
         ).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

@@ -40,6 +40,10 @@ module Lutaml
       # Performance: Frozen empty hash to reduce allocations
       EMPTY_HASH = {}.freeze
 
+      # ":".getbyte(0) — getbyte comparisons avoid the per-candidate
+      # string slice in namespace-prefix checks on the lenient paths.
+      COLON_BYTE = 58
+
       def data_to_model(data, _format, options = {})
         # Use child's own default register if it has one
         # This ensures versioned schemas (e.g., MML v2 with lutaml_default_register = :mml_v2)
@@ -600,6 +604,21 @@ _effective_register)
       def convert_rule_name_to_attribute_name(doc, rule_name, session: nil)
         return nil unless rule_name.include?(":")
 
+        # Pure function of (element attributes, spelling) — the same
+        # conversions repeat per rule application (~450k find/slice
+        # allocations per ISO-13849 parse before this memo).
+        conversions = session&.rule_name_resolution(doc.root)
+        if conversions
+          return conversions[rule_name] if conversions.key?(rule_name)
+
+          converted = convert_rule_name_uncached(doc, rule_name, session)
+          conversions[rule_name] = converted
+        else
+          convert_rule_name_uncached(doc, rule_name, session)
+        end
+      end
+
+      def convert_rule_name_uncached(doc, rule_name, session)
         # URI-vs-prefix detection works on the whole rule name: the
         # namespace part is a prefix of rule_name, so "://" anywhere in
         # the name means a URI-form namespace, and a "urn:" namespace
@@ -620,10 +639,13 @@ _effective_register)
             candidates = session.element_local_attribute_index(doc.root)[local_name]
             # No candidate carries this local name: nothing in the
             # element can match, the scan is skipped entirely.
+            # getbyte, not a [i] slice — the slice allocated one
+            # string per probed candidate (~380k per ISO-13849 parse).
             matched = candidates&.find do |attr|
               ns = attr.namespace
               next false if ns.nil? || ns.length > last_colon_index
-              next false unless rule_name.start_with?(ns) && rule_name[ns.length] == ":"
+              next false unless rule_name.start_with?(ns) &&
+                rule_name.getbyte(ns.length) == COLON_BYTE
 
               attr.unprefixed_name == local_name
             end
@@ -631,7 +653,8 @@ _effective_register)
             matched = doc.root.attributes.each_value.find do |attr|
               ns = attr.namespace
               next false if ns.nil? || ns.length > last_colon_index
-              next false unless rule_name.start_with?(ns) && rule_name[ns.length] == ":"
+              next false unless rule_name.start_with?(ns) &&
+                rule_name.getbyte(ns.length) == COLON_BYTE
 
               attr.unprefixed_name == local_name
             end
@@ -661,13 +684,27 @@ _effective_register)
       def find_attribute_by_local_name(doc, rule_names,
                                        flexible_local: false, session: nil)
         root_index = session&.element_local_attribute_index(doc.root)
+        # Matched VALUE per (element, spelling, flexible flag) — pure
+        # while the element is parse-frozen.
+        memo = if session
+                 session.lenient_local_matches(doc.root,
+                                                                      flexible_local)
+               else
+                 nil
+               end
 
         rule_names.each do |rule_name|
           next unless rule_name.include?(":")
 
-          resolved = match_attribute_by_local_name(
-            doc, rule_name, root_index, flexible_local
-          )
+          resolved = if memo&.key?(rule_name)
+                       memo[rule_name]
+                     else
+                       match = match_attribute_by_local_name(
+                         doc, rule_name, root_index, flexible_local
+                       )
+                       memo[rule_name] = match if memo
+                       match
+                     end
           return resolved if resolved
         end
         nil
@@ -686,6 +723,11 @@ _effective_register)
         local_name, rule_uri = parts
 
         candidates = root_index&.[](local_name)
+        # The index carries every local form of every attribute on the
+        # element — a miss means no attribute can match, so the full
+        # each_value scan below is dead whenever the index exists.
+        return nil if root_index && !candidates
+
         matched_attr = if candidates
                          candidates.find do |attr|
                            local_name_match?(attr, local_name, rule_uri,
@@ -1009,6 +1051,15 @@ _effective_register)
           end
         end
 
+        # lutaml-model#88: attribute-value discriminator — among the
+        # name-matched occurrences, keep only those whose sibling
+        # attributes carry the expected values.
+        if rule.when_attribute?
+          children = children.select do |child|
+            rule.matches_when_attribute?(child)
+          end
+        end
+
         # Performance: Cache rule method check before loop to avoid repeated method calls
         rule_has_custom_method = rule.has_custom_method_for_deserialization?
         if rule_has_custom_method || attr_type == ::Lutaml::Model::Type::Hash

data/lib/lutaml/xml/parse_session.rb

@@ -29,8 +29,17 @@ module Lutaml
       # functions of the element and the name; ISO-13849-shaped
       # documents repeat the same resolutions per rule application, so
       # the computed answer is memoized per element for the parse.
-      def rule_name_resolution
-        @rule_name_resolution ||= {}
+      def rule_name_resolution(element)
+        @rule_name_resolution ||= {}.compare_by_identity
+        @rule_name_resolution[element] ||= {}
+      end
+
+      # Lenient local-name fallback matches, per (element, flexible_local):
+      # spelling -> matched attribute VALUE. Same purity argument as
+      # rule_name_resolution — elements are parse-frozen.
+      def lenient_local_matches(element, flexible_local)
+        @lenient_local_matches ||= {}.compare_by_identity
+        (@lenient_local_matches[element] ||= {})[flexible_local] ||= {}
       end
 
       # Local-name -> [attributes] index over one element's attributes,

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

@@ -42,12 +42,31 @@ register_id, register)
                 rule.attribute_type < Lutaml::Model::Serialize
             end
 
-          if is_nested_model
-            create_nested_model_element(rule, value, options, register,
-                                        union: union)
-          else
-            create_simple_value_element(rule, value, options, model_class,
-                                        register_id)
+          element = if is_nested_model
+                      create_nested_model_element(rule, value, options,
+                                                  register, union: union)
+                    else
+                      create_simple_value_element(rule, value, options,
+                                                  model_class, register_id)
+                    end
+          apply_when_attribute(element, rule)
+          element
+        end
+
+        # lutaml-model#88: re-emit the discriminator attributes on the
+        # element created for this rule, unless the value's own mapping
+        # already wrote them.
+        def apply_when_attribute(element, rule)
+          pairs = rule.option(:when_attribute)
+          return if pairs.nil? || pairs.empty?
+          return if element.nil?
+
+          pairs.each do |name, expected|
+            next if element.attributes.any? { |a| a.name == name.to_s }
+
+            element.attributes << ::Lutaml::Xml::DataModel::XmlAttribute.new(
+              name.to_s, expected.to_s
+            )
           end
         end
 

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

@@ -337,6 +337,7 @@ register_id, register, attr_name, custom_methods_value)
             value_map: value_map,
             custom_methods: custom_methods_value,
             polymorphic: mapping_rule.polymorphic,
+            when_attribute: mapping_rule.when_attribute,
             form: mapping_rule.form,
             delegate_from: delegate_target,
           )
@@ -417,6 +418,7 @@ register_id, register, custom_methods_value)
             value_map: value_map,
             custom_methods: custom_methods_value,
             polymorphic: mapping_rule.polymorphic,
+            when_attribute: mapping_rule.when_attribute,
             form: mapping_rule.form,
             alias_names: alias_names,
           )

data/spec/lutaml/key_value/transformation/rule_compiler_spec.rb

@@ -137,26 +137,36 @@ RSpec.describe Lutaml::KeyValue::Transformation::RuleCompiler do
   end
 
   describe "#valid_mapping?" do
-    let(:rule) { double("CompiledRule", attribute_name: :name) }
+    def compiled_rule(serialize: true)
+      Lutaml::Model::CompiledRule.new(
+        attribute_name: :name,
+        serialized_name: "name",
+        serialize: serialize,
+      )
+    end
 
     it "returns true when no only/except options" do
-      expect(compiler.valid_mapping?(rule, {})).to be true
+      expect(compiler.valid_mapping?(compiled_rule, {})).to be true
     end
 
     it "returns true when attribute is in only list" do
-      expect(compiler.valid_mapping?(rule, { only: [:name] })).to be true
+      expect(compiler.valid_mapping?(compiled_rule, { only: [:name] })).to be true
     end
 
     it "returns false when attribute is not in only list" do
-      expect(compiler.valid_mapping?(rule, { only: [:age] })).to be false
+      expect(compiler.valid_mapping?(compiled_rule, { only: [:age] })).to be false
     end
 
     it "returns true when attribute is not in except list" do
-      expect(compiler.valid_mapping?(rule, { except: [:age] })).to be true
+      expect(compiler.valid_mapping?(compiled_rule, { except: [:age] })).to be true
     end
 
     it "returns false when attribute is in except list" do
-      expect(compiler.valid_mapping?(rule, { except: [:name] })).to be false
+      expect(compiler.valid_mapping?(compiled_rule, { except: [:name] })).to be false
+    end
+
+    it "returns false for a hydrate-only rule (serialize: false)" do
+      expect(compiler.valid_mapping?(compiled_rule(serialize: false), {})).to be false
     end
   end
 

data/spec/lutaml/key_value/transformation_spec.rb

@@ -283,7 +283,10 @@ RSpec.describe Lutaml::KeyValue::Transformation do
 
       expect(transformation).to be_frozen
 
-      rule = instance_double(Lutaml::Model::CompiledRule, attribute_name: :name)
+      rule = Lutaml::Model::CompiledRule.new(
+        attribute_name: :name,
+        serialized_name: "name",
+      )
       expect do
         transformation.send(:valid_mapping?, rule, {})
       end.not_to raise_error

data/spec/lutaml/model/attributes_memo_clear_race_spec.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# lutaml-model#815: standalone `SomeModel.new.to_xml` crashed on 0.8.42 when
+# the model's attributes are merged through register records whose imports
+# clear @merged_attributes_cache re-entrantly from inside ensure_imports! —
+# the memo store was materialized before ensure_imports! and the write after
+# it hit nil[].
+RSpec.describe "attributes memo across import-triggered cache clears" do
+  let(:namespace_class) do
+    Class.new(Lutaml::Xml::W3c::XmlNamespace) do
+      uri "https://example.com/ns815"
+    end
+  end
+
+  let(:register) do
+    Lutaml::Model::Register.new(:attrs815, fallback: [:default]).tap do |reg|
+      reg.bind_namespace(namespace_class)
+    end
+  end
+
+  let(:base_model) do
+    Class.new(Lutaml::Model::Serializable) do
+      attribute :shared, :string
+
+      xml do
+        element "Base815"
+        namespace namespace_class
+        map_element "shared", to: :shared
+      end
+    end
+  end
+
+  let(:consumer_model) do
+    Class.new(Lutaml::Model::Serializable) do
+      attribute :own, :string
+
+      xml do
+        element "Consumer815"
+        namespace namespace_class
+        map_element "own", to: :own
+      end
+    end
+  end
+
+  before do
+    stub_const("Attrs815::NamespaceClass", namespace_class)
+    Lutaml::Model::GlobalContext.reset!
+    Lutaml::Model::GlobalRegister.instance.register(register)
+    # Populate @register_records through the import the parse path uses.
+    base_model.import_model_attributes(consumer_model, register.id)
+  end
+
+  after do
+    Lutaml::Model::GlobalContext.reset!
+  end
+
+  it "serializes a register-bound model as its own document root" do
+    instance = base_model.new(shared: "x")
+    expect(instance.to_xml).to include("<shared>x</shared>")
+  end
+
+  it "merges register attributes after an import-triggered cache clear" do
+    instance = consumer_model.new(own: "y")
+    expect(instance.to_xml).to include("<own>y</own>")
+  end
+
+  it "keeps answering attributes() from the memo after imports" do
+    first = consumer_model.attributes(:attrs815)
+    expect(consumer_model.attributes(:attrs815)).to equal(first)
+  end
+
+  it "survives a re-entrant cache clear from inside ensure_imports!" do
+    # uniword's register-bound models (#815): choice/restrict resolution
+    # runs clear_cache while ensure_imports! is still on the stack, which
+    # nils @merged_attributes_cache after the reader materialized it.
+    reentrant = Class.new(base_model) do
+      def self.finalized? = true
+
+      def self.ensure_format_mapping_imports!(_register = nil)
+        clear_cache
+        super
+      end
+    end
+
+    expect { reentrant.attributes(:attrs815) }.not_to raise_error
+    expect(reentrant.attributes(:attrs815)[:shared].name).to eq(:shared)
+  end
+end

data/spec/lutaml/model/hydrate_only_mapping_spec.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require_relative "../../../lib/lutaml/model"
+
+module HydrateOnlyMapping
+  class Message < Lutaml::Model::Serializable
+    attribute :body, :string
+    attribute :source_offset, :integer
+
+    key_value do
+      map "body", to: :body
+      map "source_offset", to: :source_offset, serialize: false
+    end
+  end
+end
+
+RSpec.describe "hydrate-only mappings (serialize: false)" do
+  let(:input) { { "body" => "hello", "source_offset" => 42 } }
+
+  it "hydrates the attribute from input" do
+    message = HydrateOnlyMapping::Message.from_hash(input)
+
+    expect(message.body).to eq("hello")
+    expect(message.source_offset).to eq(42)
+  end
+
+  it "omits the attribute from serialized output" do
+    message = HydrateOnlyMapping::Message.from_hash(input)
+
+    expect(message.to_hash).to eq("body" => "hello")
+  end
+
+  it "round-trips through JSON without the hidden key" do
+    message = HydrateOnlyMapping::Message.from_json(input.to_json)
+
+    expect(JSON.parse(message.to_json)).to eq("body" => "hello")
+  end
+
+  it "keeps the mapping through deep-copied mappings" do
+    mapping = HydrateOnlyMapping::Message.mappings_for(:hash)
+    rule = mapping.mappings.find { |r| r.to == :source_offset }
+
+    expect(mapping.deep_dup.mappings.find { |r| r.to == :source_offset }
+      .serialize?).to eq(rule.serialize?)
+  end
+end

data/spec/lutaml/xml/when_attribute_spec.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# lutaml-model#88: attribute-value dispatch on a shared wire name.
+# `map_element "component", to: :guidance, when_attribute: { "type" =>
+# "guidance" }` selects only the occurrences whose sibling attribute carries
+# the expected value, and re-emits the discriminator on serialization.
+class WhenAttrComponent < Lutaml::Model::Serializable
+  attribute :text, :string
+
+  xml do
+    element "component"
+    map_element "text", to: :text
+  end
+end
+
+class WhenAttrRequirement < Lutaml::Model::Serializable
+  attribute :guidance, WhenAttrComponent, collection: true
+  attribute :purpose, WhenAttrComponent, collection: true
+  attribute :test_method, WhenAttrComponent, collection: true
+
+  xml do
+    element "requirement"
+    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 discriminator mappings" do
+  before do
+    stub_const("WhenAttr::Component", WhenAttrComponent)
+    stub_const("WhenAttr::Requirement", WhenAttrRequirement)
+  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
+
+  it "dispatches occurrences by the discriminator value" do
+    req = WhenAttr::Requirement.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 "keeps document order within each target attribute" do
+    req = WhenAttr::Requirement.from_xml(xml)
+    expect(req.guidance.map(&:text)).to eq(%w[g1 g2])
+  end
+
+  it "drops occurrences whose discriminator is not covered" do
+    doc = '<requirement><component type="unknown"><text>x</text></component></requirement>'
+    req = WhenAttr::Requirement.from_xml(doc)
+
+    expect(req.guidance).to be_empty
+    expect(req.purpose).to be_empty
+  end
+
+  it "re-emits the discriminator attribute on serialization" do
+    round = WhenAttr::Requirement.from_xml(WhenAttr::Requirement.from_xml(xml).to_xml)
+
+    expect(round.guidance.map(&:text)).to eq(%w[g1 g2])
+    expect(round.purpose.map(&:text)).to eq(["p1"])
+    expect(round.test_method.map(&:text)).to eq(["t1"])
+
+    serialized = WhenAttr::Requirement.from_xml(xml).to_xml
+    expect(serialized).to include('type="guidance"')
+    expect(serialized).to include('type="purpose"')
+    expect(serialized).to include('type="test-method"')
+  end
+
+  it "does not emit a discriminator for ordinary rules" do
+    plain = Class.new(Lutaml::Model::Serializable) do
+      attribute :text, :string
+
+      xml do
+        element "plain"
+        map_element "text", to: :text
+      end
+    end
+
+    expect(plain.from_xml("<plain><text>t</text></plain>").to_xml)
+      .not_to include("type=")
+  end
+
+  it "survives deep_dup of mappings" do
+    mapping = WhenAttr::Requirement.mappings_for(:xml)
+    duped = mapping.deep_dup.mappings.find do |r|
+      r.to == :guidance
+    end
+
+    expect(duped.when_attribute).to eq("type" => "guidance")
+  end
+
+  it "rejects non-string/symbol discriminator shapes" do
+    expect do
+      Class.new(Lutaml::Model::Serializable) do
+        attribute :x, :string
+
+        xml do
+          element "x"
+          map_element "x", to: :x, when_attribute: { "type" => 42 }
+        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, when_attribute: { "type" => "guidance" }
+        end
+      end
+    end.to raise_error(ArgumentError)
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lutaml-model
 version: !ruby/object:Gem::Version
-  version: 0.8.42
+  version: 0.8.43
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-19 00:00:00.000000000 Z
+date: 2026-09-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -1695,6 +1695,7 @@ files:
 - spec/lutaml/model/attribute_form_default_spec.rb
 - spec/lutaml/model/attribute_restriction_spec.rb
 - spec/lutaml/model/attribute_spec.rb
+- spec/lutaml/model/attributes_memo_clear_race_spec.rb
 - spec/lutaml/model/boot_manifest_spec.rb
 - spec/lutaml/model/cached_type_resolver_spec.rb
 - spec/lutaml/model/cardinality_strict_spec.rb
@@ -1737,6 +1738,7 @@ files:
 - spec/lutaml/model/global_register_spec.rb
 - spec/lutaml/model/group_spec.rb
 - spec/lutaml/model/hash/adapter_spec.rb
+- spec/lutaml/model/hydrate_only_mapping_spec.rb
 - spec/lutaml/model/import_registry_spec.rb
 - spec/lutaml/model/included_spec.rb
 - spec/lutaml/model/inheritance_spec.rb
@@ -2004,6 +2006,7 @@ 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_spec.rb
 - spec/lutaml/xml/xml_adapter_spec.rb
 - spec/lutaml/xml/xml_declaration_spec.rb
 - spec/lutaml/xml/xml_element_guard_spec.rb