lutaml-model 0.8.41 → 0.8.43

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)
@@ -315,6 +319,13 @@ module Lutaml
                     compiled_rule_records(instance.class, effective_register,
                                           grouped_plain_rules)
                   end
+        # Loop invariants: the entity-decode flag is a per-(class, register)
+        # fact and the attributes hash is memoized per register — both were
+        # re-asked per rule application (942k + 751k calls per ISO-13849
+        # parse).
+        decode_entities_flag = decode_html_entities_for(instance,
+                                                        effective_register)
+        deserialize_attributes = attributes
         mappings.each do |rule|
           record = records&.[](rule)
           rule_to = rule.to
@@ -376,6 +387,9 @@ module Lutaml
                                            default_namespace)
                     # Pre-match: no child element matches this rule.
                     # Skip expensive value_for_rule, handle defaults inline.
+                    # NOTE: do not "read the instance" here (to_value_for) —
+                    # the compiled getters materialize lazy collections on
+                    # first read, which tripled parse allocations when tried.
                     if instance.using_default?(rule_to) || rule.render_default
                       defaults_used << rule_to
                       attr&.default(effective_register) || rule.to_value_for(instance)
@@ -409,9 +423,7 @@ module Lutaml
           value = apply_value_map(value, from_map, attr)
           value = normalize_xml_value(value, rule, attr, new_opts,
                                       effective_register)
-          value = decode_html_entities_value(value, decode_html_entities_for(
-                                                      instance, effective_register
-                                                    ))
+          value = decode_html_entities_value(value, decode_entities_flag)
           value = rule.transform_value(attr, value, :from, :xml)
           # An over-count is normally left for `.validate` to report. A mapped
           # PORO has no `.validate`, so deferring there would discard the
@@ -420,7 +432,7 @@ module Lutaml
               !rule.content_mapping?
             attr.valid_collection!(value, context)
           end
-          rule.deserialize(instance, value, attributes, context,
+          rule.deserialize(instance, value, deserialize_attributes, context,
                            options[:context])
 
           instance.value_set_for(rule_to)
@@ -592,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
@@ -612,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
@@ -623,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
@@ -653,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
@@ -678,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,
@@ -786,10 +836,27 @@ _effective_register)
       end
 
       def decode_html_entities_for(instance, register)
+        # Asked per rule application (942k per ISO-13849 parse) for a
+        # per-(class, register) fact; the transform instance itself is
+        # cached per (model class, register), so the memo lives here.
+        per_class = (@decode_html_entities_cache ||= {}.compare_by_identity)
+        per_register = (per_class[instance.class] ||= {})
+        return per_register[register] if per_register.key?(register)
+
         klass = instance.class
-        return false unless klass.is_a?(Class) && klass.include?(Lutaml::Model::Serialize)
+        per_register[register] = klass.is_a?(Class) &&
+          klass.include?(Lutaml::Model::Serialize) &&
+          (klass.mappings_for(:xml, register)&.decode_html_entities? || false)
+      end
 
-        klass.mappings_for(:xml, register)&.decode_html_entities?
+      # Serializable type class → its XML namespace class, asked per
+      # (rule × element) in value_for_rule / resolve_rule_names_with_type
+      # for a per-type static.
+      def type_namespace_class_of(type_class)
+        cache = (@type_ns_class_cache ||= {}.compare_by_identity)
+        return cache[type_class] if cache.key?(type_class)
+
+        cache[type_class] = type_class.mappings_for(:xml)&.namespace_class
       end
 
       def value_for_rule(session, rule, options, cached_attr = nil,
@@ -847,7 +914,7 @@ _effective_register)
         type_ns_all_uris = nil
         if attr_type_is_serializable
           type_ns_class = if attr_type_is_class
-                            attr_type.mappings_for(:xml)&.namespace_class
+                            type_namespace_class_of(attr_type)
                           else
                             attr.type_namespace_class(effective_register)
                           end
@@ -984,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
@@ -1292,7 +1368,7 @@ effective_register = lutaml_register)
         elsif precomputed_type.is_a?(Class) &&
             precomputed_type.include?(::Lutaml::Model::Serialize)
           # Use pre-computed type directly — avoids redundant attr.type() call
-          attr_type_ns_class = precomputed_type.mappings_for(:xml)&.namespace_class
+          attr_type_ns_class = type_namespace_class_of(precomputed_type)
           if attr_type_ns_class
             return ["#{attr_type_ns_class.uri}:#{rule.name}"]
           end
@@ -1309,7 +1385,7 @@ effective_register = lutaml_register)
           if attr_type_class
             attr_type_ns_class = if attr_type_class.is_a?(Class) &&
                 attr_type_class.include?(::Lutaml::Model::Serialize)
-                                   attr_type_class.mappings_for(:xml)&.namespace_class
+                                   type_namespace_class_of(attr_type_class)
                                  end
             if attr_type_ns_class
               return ["#{attr_type_ns_class.uri}:#{rule.name}"]

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