lutaml-model 0.8.130 → 0.8.132

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 600c15c36628ae5051c4c447ebd9f6b8fe7e2b5b5c70dc894e2de663f2725a32
-  data.tar.gz: a5bcfd67b0416116fdfe806123ce7c679866fc292d19eb6eb1c6ea8849ac2e72
+  metadata.gz: 83ece4646bc4f2ecd052f6ba5edf994cb512b4be3a08e8a1778c5b357daab424
+  data.tar.gz: 9bac20d16559163de764a7148974724c199cacbce0d88d945b932c7d36ccaa19
 SHA512:
-  metadata.gz: 46d83e87714efcd4d5c60f552eaf94aac748b5c121f458008a07eeece815e1121a00ad95623dc85bad3cab77204de675c0cd876ca0745fe9dfcb63655304ae67
-  data.tar.gz: be9904e6941df96b90c3feed829f399475a247ecc1900d86787d8dba224d1ef0a7ad8d68838ad13d5c4136df54d034dccb10bb72988424a95cf6541205243739
+  metadata.gz: 27120683de1ff8d9c95049e683dffdf302aa43edf9a4e5e6debda189df3903fdf98f4722200eb4106285e86dfabb170b77fcaea3313c6e1a8e8e548ec2db0eab
+  data.tar.gz: 26a84cc1b288f7b829c1bdb44360adc7211843e506d1d51c1f416c411636fa6099dee79fd26d4d41a7e22b5eaf3ef1510d9580dbe49318ac8c2b9e02b80974bc

data/docs/key_value_data_model.adoc

@@ -697,21 +697,21 @@ end
 
 === Detection Logic
 
-All adapters follow this pattern:
+The transformation emits the output hash directly (hash-direct
+emission), and every adapter serializes the hash it is given:
 
 [source,ruby]
 ----
-def to_json(root, options = {})
-  if root.is_a?(Lutaml::KeyValue::DataModel::Element)
-    build_from_key_value_element(root)
-  elsif root.is_a?(Hash)
-    build_from_hash(root)  # Legacy path
-  else
-    raise TypeError, "Expected KeyValueElement or Hash, got #{root.class}"
-  end
+def to_json(hash, options = {})
+  JSON.generate(hash)
 end
 ----
 
+`Lutaml::KeyValue::DataModel::Element` remains the content model for
+rule compilation and for custom `to:` handlers (whose scratch document
+element merges its payload into the output hash), but the Element tree
+is no longer passed across the adapter boundary.
+
 === Building from KeyValueElement
 
 ==== JSON Example

data/lib/lutaml/json/adapter/multi_json_adapter.rb

@@ -22,13 +22,7 @@ module Lutaml
         def to_json(*args)
           require "multi_json"
           # Handle KeyValueElement input (new symmetric architecture)
-          attributes_to_serialize = if @attributes.is_a?(Lutaml::KeyValue::DataModel::Element)
-                                      # Unwrap __root__ wrapper to get actual content
-                                      @attributes.to_hash["__root__"]
-                                    else
-                                      # Legacy Hash input (backward compatibility)
-                                      @attributes
-                                    end
+          attributes_to_serialize = @attributes
 
           # LutaML's own threading keys must not reach the backend; the
           # rest (e.g. :pretty) are meaningful to multi_json. The json

data/lib/lutaml/json/adapter/oj_adapter.rb

@@ -27,13 +27,7 @@ module Lutaml
         def to_json(*args)
           require "oj"
           # Handle KeyValueElement input (new symmetric architecture)
-          attributes_to_serialize = if @attributes.is_a?(Lutaml::KeyValue::DataModel::Element)
-                                      # Unwrap __root__ wrapper to get actual content
-                                      @attributes.to_hash["__root__"]
-                                    else
-                                      # Legacy Hash input (backward compatibility)
-                                      @attributes
-                                    end
+          attributes_to_serialize = @attributes
 
           Oj.dump(attributes_to_serialize, *args)
         # rubocop:enable Style/ArgumentsForwarding

data/lib/lutaml/json/adapter/standard_adapter.rb

@@ -22,13 +22,7 @@ module Lutaml
 
         def to_json(*args)
           # Handle KeyValueElement input (new symmetric architecture)
-          attributes_to_serialize = if @attributes.is_a?(Lutaml::KeyValue::DataModel::Element)
-                                      # Unwrap __root__ wrapper to get actual content
-                                      @attributes.to_hash["__root__"]
-                                    else
-                                      # Legacy Hash input (backward compatibility)
-                                      @attributes
-                                    end
+          attributes_to_serialize = @attributes
 
           unless GeneratorOptions.lutaml_options?(args.first)
             return JSON.generate(attributes_to_serialize, args.first)

data/lib/lutaml/key_value/adapter/json/multi_json_adapter.rb

@@ -26,13 +26,7 @@ module Lutaml
           def to_json(*args)
             require "multi_json"
             # Handle KeyValueElement input (new symmetric architecture)
-            attributes_to_serialize = if @attributes.is_a?(Lutaml::KeyValue::DataModel::Element)
-                                        # Unwrap __root__ wrapper to get actual content
-                                        @attributes.to_hash["__root__"]
-                                      else
-                                        # Legacy Hash input (backward compatibility)
-                                        @attributes
-                                      end
+            attributes_to_serialize = @attributes
 
             # LutaML's own options must not reach the backend: the json
             # gem 3.x and Oj both raise on unknown generator options

data/lib/lutaml/key_value/adapter/json/oj_adapter.rb

@@ -31,13 +31,7 @@ module Lutaml
           def to_json(*args)
             require "oj"
             # Handle KeyValueElement input (new symmetric architecture)
-            attributes_to_serialize = if @attributes.is_a?(Lutaml::KeyValue::DataModel::Element)
-                                        # Unwrap __root__ wrapper to get actual content
-                                        @attributes.to_hash["__root__"]
-                                      else
-                                        # Legacy Hash input (backward compatibility)
-                                        @attributes
-                                      end
+            attributes_to_serialize = @attributes
 
             Oj.dump(attributes_to_serialize, *args)
           # rubocop:enable Style/ArgumentsForwarding

data/lib/lutaml/key_value/adapter/json/standard_adapter.rb

@@ -25,13 +25,7 @@ module Lutaml
 
           def to_json(*args)
             # Handle KeyValueElement input (new symmetric architecture)
-            attributes_to_serialize = if @attributes.is_a?(Lutaml::KeyValue::DataModel::Element)
-                                        # Unwrap __root__ wrapper to get actual content
-                                        @attributes.to_hash["__root__"]
-                                      else
-                                        # Legacy Hash input (backward compatibility)
-                                        @attributes
-                                      end
+            attributes_to_serialize = @attributes
 
             unless Lutaml::Json::GeneratorOptions.lutaml_options?(args.first)
               return JSON.generate(attributes_to_serialize, args.first)

data/lib/lutaml/key_value/adapter/toml/teptris_adapter.rb

@@ -25,13 +25,7 @@ module Lutaml
           def to_toml(*)
             require "teptris"
             # Handle KeyValueElement input (new symmetric architecture)
-            attributes_to_serialize = if @attributes.is_a?(Lutaml::KeyValue::DataModel::Element)
-                                        # Unwrap __root__ wrapper to get actual content
-                                        @attributes.to_hash["__root__"]
-                                      else
-                                        # Legacy Hash input (backward compatibility)
-                                        @attributes
-                                      end
+            attributes_to_serialize = @attributes
 
             Teptris::TOML.dump(attributes_to_serialize)
           end

data/lib/lutaml/key_value/adapter/toml/toml_rb_adapter.rb

@@ -20,13 +20,7 @@ module Lutaml
           def to_toml(*)
             require "toml-rb"
             # Handle KeyValueElement input (new symmetric architecture)
-            attributes_to_serialize = if @attributes.is_a?(Lutaml::KeyValue::DataModel::Element)
-                                        # Unwrap __root__ wrapper to get actual content
-                                        @attributes.to_hash["__root__"]
-                                      else
-                                        # Legacy Hash input (backward compatibility)
-                                        @attributes
-                                      end
+            attributes_to_serialize = @attributes
 
             TomlRB.dump(attributes_to_serialize)
           rescue LoadError

data/lib/lutaml/key_value/adapter/toml/tomlib_adapter.rb

@@ -25,13 +25,7 @@ module Lutaml
           def to_toml(*)
             require "tomlib"
             # Handle KeyValueElement input (new symmetric architecture)
-            attributes_to_serialize = if @attributes.is_a?(Lutaml::KeyValue::DataModel::Element)
-                                        # Unwrap __root__ wrapper to get actual content
-                                        @attributes.to_hash["__root__"]
-                                      else
-                                        # Legacy Hash input (backward compatibility)
-                                        @attributes
-                                      end
+            attributes_to_serialize = @attributes
 
             Tomlib.dump(attributes_to_serialize)
             # Tomlib::Generator.new(to_h).toml_str

data/lib/lutaml/key_value/adapter/yaml/standard_adapter.rb

@@ -24,13 +24,7 @@ module Lutaml
 
           def to_yaml(options = {})
             # Handle KeyValueElement input (new symmetric architecture)
-            attributes_to_serialize = if @attributes.is_a?(Lutaml::KeyValue::DataModel::Element)
-                                        # Unwrap __root__ wrapper to get actual content
-                                        @attributes.to_hash["__root__"]
-                                      else
-                                        # Legacy Hash input (backward compatibility)
-                                        @attributes
-                                      end
+            attributes_to_serialize = @attributes
 
             YAML.dump(attributes_to_serialize, options)
           end

data/lib/lutaml/key_value/data_model/element.rb

@@ -85,6 +85,21 @@ module Lutaml
           has_value? && !has_children?
         end
 
+        # The content this element carries, independent of its own key:
+        # the child-merged structure when children exist, otherwise the
+        # direct value (nil when neither). This is the half of to_hash
+        # that survives the {key => ...} envelope, so callers that
+        # assemble documents themselves never round-trip through a key.
+        #
+        # @return [Object, nil]
+        def payload
+          if has_children?
+            children_to_value
+          elsif has_value?
+            @value
+          end
+        end
+
         # Convert to Hash representation
         #
         # This is the primary method for adapter rendering.
@@ -93,19 +108,10 @@ module Lutaml
         # 2. If has children that are all Elements: {key => merged_hash}
         # 3. If has children that are mixed/primitives: {key => array}
         # 4. If has both value and children: children take precedence
-        # 5. Special case: __root__ with no children returns empty hash (for omitted attributes)
         #
         # @return [Hash]
         def to_hash
-          if has_children?
-            { @key => children_to_value }
-          elsif has_value?
-            { @key => @value }
-          else
-            # Special case: __root__ element should return empty hash when all attributes omitted
-            # This allows hash["__root__"].keys to work without raising NoMethodError
-            { @key => (@key == "__root__" ? {} : nil) }
-          end
+          { @key => payload }
         end
 
         # String representation for debugging
@@ -123,43 +129,36 @@ module Lutaml
 
         # Hash-like access for backward compatibility
         #
-        # Allows Element to be used like a hash in tests and existing code.
-        # Converts to hash first, then accesses the key.
+        # A child element's payload answers by the child's key; a leaf
+        # answers by its own key ({"name" => "John"}["name"]). This is
+        # what lets custom `to:` handlers build nested structures in
+        # place: `doc["locality"] = {}; doc["locality"]["type"] = v` —
+        # the read returns the child's value hash and the write mutates
+        # it in place.
         #
         # @param key [String, Symbol] Key to access
         # @return [Object] Value for the key
         def [](key)
-          hash = to_hash
-          # If this is the root element, access the inner hash
-          if @key == "__root__" && hash.key?("__root__")
-            inner = hash["__root__"]
-            inner.is_a?(Hash) ? inner[key.to_s] : nil
-          else
-            hash[key.to_s]
-          end
+          key = key.to_s
+          child = @children.find { |c| c.is_a?(Element) && c.key == key }
+          child ? child.payload : to_hash[key]
         end
 
         # Hash-like assignment for backward compatibility
         #
         # Allows Element to be used like a hash in tests and existing code.
-        # Creates a new child Element for the key-value pair.
+        # Replaces any existing child element of the same key, then adds
+        # a new child Element for the key-value pair.
         #
         # @param key [String, Symbol] Key to set
         # @param value [Object] Value to set
         # @return [Object] The assigned value
         def []=(key, value)
-          # For root element, add child with the key-value pair
-          if @key == "__root__"
-            # Remove existing child with same key if any
-            @children.reject! do |child|
-              child.is_a?(Element) && child.key == key.to_s
-            end
-            # Add new child
-          else
-            # For non-root elements, convert to hash and merge
-            # This shouldn't normally happen in the transformation flow
+          key = key.to_s
+          @children.reject! do |child|
+            child.is_a?(Element) && child.key == key
           end
-          @children << Element.new(key.to_s, value)
+          @children << Element.new(key, value)
           value
         end
 

data/lib/lutaml/key_value/transform.rb

@@ -106,8 +106,7 @@ module Lutaml
           # transformation_for returns nil for cyclic dependencies or :building sentinel
           # Fall back to legacy approach in these cases
           if transformation.is_a?(Lutaml::KeyValue::Transformation)
-            # transform emits the output hash directly (TODO.perf 19) —
-            # the __root__ Element tree and its to_hash flatten are gone.
+            # transform emits the output hash directly (TODO.perf 19)
             return transformation.transform(instance, options)
           end
         end
@@ -347,15 +346,21 @@ child_mappings)
       # path. Returns nil (caller falls back) on any shape the plan
       # does not cover, e.g. a non-Hash item where a model was expected.
       def kv_group_build(rows, doc, format, register, options)
-        setters = []
+        # Positional values, not per-row [name, value] pairs: rows are a
+        # fixed per-class list, so the writer to apply lives at the row's
+        # index and the pair arrays were the lane's biggest allocation
+        # (~6 arrays per node on hydrate-heavy corpora).
+        values = Array.new(rows.size, MISSING)
         children = []
         # Lazy: the present-key hot path never pushes, and this runs
         # once per hydrated model instance.
         absent = nil
         unmapped = nil
+        i = 0
         rows.each do |rule, attr, kind, type, child_rows, child_register|
           if kind == :unmapped
             unmapped = [type, child_rows]
+            i += 1
             next
           end
 
@@ -365,6 +370,7 @@ child_mappings)
           v = Lutaml::Model::Utils.fetch_str_or_sym(doc, rule.name, MISSING)
           if v.equal?(MISSING)
             (absent ||= []) << rule
+            i += 1
             next
           end
 
@@ -390,13 +396,15 @@ child_mappings)
               built << self.class.data_to_model(type.attr_type,
 child_hash, format, { mappings: type.child_rules })
             end
-            setters << [rule.kv_setter, built]
+            values[i] = built
             children.concat(built)
+            i += 1
             next
           end
 
           if kind == :scalar
-            setters << [rule.kv_setter, v]
+            values[i] = v
+            i += 1
             next
           end
 
@@ -418,7 +426,7 @@ child_hash, format, { mappings: type.child_rules })
 
               built << child
             end
-            setters << [rule.kv_setter, built]
+            values[i] = built
             children.concat(built)
           else
             return nil unless v.is_a?(::Hash)
@@ -428,12 +436,20 @@ child_hash, format, { mappings: type.child_rules })
                                                  options)
             return nil if child.nil?
 
-            setters << [rule.kv_setter, child]
+            values[i] = child
             children << child
           end
+          i += 1
         end
         instance = model_class.allocate_for_walk(register)
-        setters.each { |name, value| instance.public_send(name, value) }
+        i = 0
+        rows.each do |rule, _attr, kind, *_rest|
+          v = values[i]
+          i += 1
+          next if v.equal?(MISSING) || kind == :unmapped
+
+          instance.public_send(rule.kv_setter, v)
+        end
         absent&.each do |rule|
           process_mapping_rule(doc, instance, format, rule, options, nil)
         end

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

@@ -43,6 +43,9 @@ model_class: nil)
           @register_id = register_id
           @transformation_factory = transformation_factory
           @model_class = model_class
+          # Pre-declared: the serializer may be frozen after setup, and
+          # the type-transformation memo mutates this hash in place.
+          @lutaml_type_transformations = {}
         end
 
         # Serialize a value for an item (handles nested models and primitives).
@@ -117,10 +120,10 @@ model_class: nil)
 
           # Get or create child transformation
           child_transformation = if uses_polymorphism
-                                   create_transformation(actual_type)
+                                   transformation_for_type(actual_type)
                                  else
                                    rule.child_transformation ||
-                                     create_transformation(rule.attribute_type)
+                                     transformation_for_type(rule.attribute_type)
                                  end
 
           if child_transformation
@@ -296,6 +299,15 @@ model_class: nil)
           transformation_factory.call(type_class)
         end
 
+        # Memoized on this object: the factory binds this object's
+        # mapping/format/register, so the memo is register-safe, and
+        # building one per serialized node is a Transformation per
+        # nested model per instance.
+        def transformation_for_type(type_class)
+          (@lutaml_type_transformations ||= {})[type_class] ||=
+            create_transformation(type_class)
+        end
+
         # Transform a nested model using the child transformation.
         #
         # @param value [Object] The model instance

data/lib/lutaml/key_value/transformation.rb

@@ -63,6 +63,9 @@ module Lutaml
 
         # Set up serializers before calling super
         # The super will call compile_rules and freeze
+        # Pre-declared: the transformation is frozen after compile, and
+        # the type-transformation memo mutates this hash in place.
+        @lutaml_type_transformations = {}
         @rule_compiler = RuleCompiler.new(
           model_class: model_class,
           register_id: register_id,
@@ -221,9 +224,8 @@ register = self.register)
       def transform(model_instance, options = {})
         # For key-value formats, we typically don't have a named root
         # Instead, we create an anonymous root that holds all attributes
-        # Hash-direct emission (TODO.perf 19): the __root__ Element
-        # tree was write-only in production — every consumer flattened
-        # it straight back to a hash. The output hash is built directly.
+        # Hash-direct emission (TODO.perf 19): the output hash is built
+        # directly; the intermediate Element tree and its flatten are gone.
         root = {}
 
         # Apply each compiled rule (with filtering support). A
@@ -343,9 +345,10 @@ register = self.register)
         if rule.has_custom_methods? && rule.custom_methods[:to]
           to_method = rule.custom_methods[:to]
           # Custom methods receive an Element "doc" and populate it
-          # (public contract, TODO.perf 19 keeps it): a scratch element
-          # is merged into the output hash afterwards.
-          doc = Lutaml::KeyValue::DataModel::Element.new("__root__")
+          # (public contract, TODO.perf 19 keeps it): only the doc's
+          # payload — the merged children or the direct value hash —
+          # is merged into the output.
+          doc = Lutaml::KeyValue::DataModel::Element.new(rule.serialized_name)
           # Custom methods may write children, or doc.value[key]=, or
           # nothing at all (pubid 2.0 regression: an empty scratch
           # flattened to {key => nil} and crashed the merge). Seed the
@@ -363,11 +366,11 @@ register = self.register)
           # its return value is ignored. (A mutation-style handler whose
           # last statement is an assignment returns the assigned inner
           # value; honoring it merged child content at the wrong level —
-          # lutaml-model#892.) Empty docs serialize as nothing, matching
-          # the pre-0.8.74 behavior.
-          merged = doc.to_hash
-          parent.update(merged["__root__"]) if merged.is_a?(::Hash) &&
-            merged["__root__"].is_a?(::Hash)
+          # lutaml-model#892.) A doc whose payload is not a hash — nil
+          # (untouched), a scalar, or an array of primitives — serializes
+          # as nothing, matching the pre-0.8.74 behavior.
+          merged = doc.payload
+          parent.update(merged) if merged.is_a?(::Hash)
           return
         end
 
@@ -539,8 +542,7 @@ converted_from_empty_to_nil: false, converted_from_nil_to_empty: false)
                   value_root = value_transformation.transform(attr_value,
                                                               options)
 
-                  # transform emits the output hash directly now
-                  # (TODO.perf 19) — no __root__ wrapper to unwrap.
+                  # transform emits the output hash directly (TODO.perf 19)
                   parent[key_value.to_s] = value_root
                   next
                 end
@@ -1035,6 +1037,15 @@ child_mappings, options)
       # @param value [Object] The value
       # @param options [Hash] Options
       # @return [Object] The value (could be Hash, primitive, or KeyValueElement)
+      # Child transformations memoized on this transformation instance:
+      # the factory binds this instance's mapping/format/register, so
+      # the memo is register-safe, and building one per serialized node
+      # is a Transformation per nested model per instance.
+      def transformation_for_type(type_class)
+        (@lutaml_type_transformations ||= {})[type_class] ||=
+          build_child_transformation(type_class)
+      end
+
       def create_value_for_item(rule, value, options)
         return nil if value.nil?
 
@@ -1099,9 +1110,7 @@ child_mappings, options)
           if !child_transformation || uses_polymorphism
             # For polymorphic types, use the actual runtime type's mappings
             type_for_mapping = uses_polymorphism ? actual_type : rule.attribute_type
-            mapping = type_for_mapping.mappings_for(format, register_id)
-            child_transformation = self.class.new(type_for_mapping, mapping,
-                                                  format, register)
+            child_transformation = transformation_for_type(type_for_mapping)
           end
 
           if child_transformation
@@ -1147,10 +1156,14 @@ child_mappings, options)
           parsed_content.each do |key, val|
             parent[key.to_s] = val
           end
-        elsif parsed_content.is_a?(::Array)
-          # Graceful handling of unusual map_all content (parity with
-          # the tree's __root__ wrapper)
-          parent["__root__"] = parsed_content
+        elsif !parsed_content.nil?
+          # A raw mapping's content must be a key-value document — it is
+          # merged into the parent by key. Any other shape (an Array, a
+          # scalar) has no representation here; serializing it under a
+          # synthetic key would leak that key into the document.
+          raise ArgumentError,
+                "raw mapping content must parse to a Hash, got " \
+                "#{parsed_content.class}"
         end
       end
 

data/lib/lutaml/model/attribute.rb

@@ -394,6 +394,18 @@ module Lutaml
         @options[:initialize_empty]
       end
 
+      # True when the default is the empty-collection lambda installed by
+      # set_default_for_collection: the one default whose constructor
+      # state (a plain empty Array) the LAZY_EMPTY_COLLECTION sentinel
+      # materializes to on first read, so walk-state seeding can use the
+      # sentinel instead of running the lambda per instance (#1010).
+      # Restricted to plain-Array collections because the lazy reader
+      # materializes []; custom Collection classes would lose their type.
+      def lazy_collection_default?
+        @implicit_collection_default == true && collection? &&
+          collection_class == ::Array && !enum?
+      end
+
       def validations
         @options[:validations]
       end
@@ -1375,8 +1387,9 @@ instance_object = nil)
       def set_default_for_collection
         validate_collection_range
         attr = self
-        if initialize_empty?
-          @options[:default] ||= -> { attr.build_collection }
+        if initialize_empty? && !@options[:default]
+          @options[:default] = -> { attr.build_collection }
+          @implicit_collection_default = true
         end
       end
 

data/lib/lutaml/model/collection.rb

@@ -384,11 +384,7 @@ module Lutaml
         private
 
         def unwrap_unwrapped_data(data)
-          # Convert KeyValueElement to Hash if needed
-          hash = data.is_a?(Hash) ? data : data.to_hash
-          # Handle "__root__" wrapper for key-value formats (created by transformation)
-          hash = hash["__root__"] if hash.key?("__root__")
-          result = Utils.fetch_str_or_sym(hash, instance_name)
+          result = Utils.fetch_str_or_sym(data, instance_name)
 
           # Extract values from nested hashes with empty string keys
           # (created by transformation for simple models with single attribute)

data/lib/lutaml/model/schema/xml_compiler/spec_builder/complex_types.rb

@@ -21,12 +21,17 @@ module Lutaml
               @parent = parent
             end
 
-            # <xs:complexType> -> Definitions::Model.
-            def build(complex_type)
+            # <xs:complexType> -> Definitions::Model. Anonymous types
+            # carry the owning element's name as `root_name` so the
+            # generated class serializes the element, not the internal
+            # CT_ alias.
+            def build(complex_type, root_name: nil)
               model = Definitions::Model.new(
                 class_name: Utils.camel_case(complex_type.name),
-                xml_root: Definitions::XmlRoot.new(kind: :element,
-                                                   name: complex_type.name),
+                xml_root: Definitions::XmlRoot.new(
+                  kind: :element,
+                  name: root_name || complex_type.name,
+                ),
                 mixed: !!complex_type.mixed,
                 namespace_class_name: @parent.namespace_class_name,
               )