lutaml-model 0.8.130 → 0.8.131

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 600c15c36628ae5051c4c447ebd9f6b8fe7e2b5b5c70dc894e2de663f2725a32
-  data.tar.gz: a5bcfd67b0416116fdfe806123ce7c679866fc292d19eb6eb1c6ea8849ac2e72
+  metadata.gz: 411fee08073d8c3578b1071024486fa23ed6f1c3b93e918f7c47e175b9a95f90
+  data.tar.gz: 80e702fd74cda828374ffc7b5367311a2b49ce5ba2d5580e8038e13b6b9269ca
 SHA512:
-  metadata.gz: 46d83e87714efcd4d5c60f552eaf94aac748b5c121f458008a07eeece815e1121a00ad95623dc85bad3cab77204de675c0cd876ca0745fe9dfcb63655304ae67
-  data.tar.gz: be9904e6941df96b90c3feed829f399475a247ecc1900d86787d8dba224d1ef0a7ad8d68838ad13d5c4136df54d034dccb10bb72988424a95cf6541205243739
+  metadata.gz: d48928bc46206f2067989a4637ace150fcf71db4df6c18e1df93de5c621c088db0490bf85d860ec6861ad08d208218553a5d2ae7806ea4b5e88067b0032d51ed
+  data.tar.gz: 8d0127e8139146f8d1df26a488904d7e48202e4c5b75a49f67a895f87d372507f9217253590496c44513677653bd8516f009d59f7889a41832c2e12333987585

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

data/lib/lutaml/key_value/transformation.rb

@@ -221,9 +221,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 +342,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 +363,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 +539,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
@@ -1147,10 +1146,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,
               )

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

@@ -110,8 +110,11 @@ module Lutaml
               end
 
               local = Utils.last_of_split(raw_type)
-              Definitions::TypeRef.new(kind: :symbol,
-                                       value: Utils.snake_case(local))
+              primitive = SupportedDataTypes.primitive_symbol(local)
+              Definitions::TypeRef.new(
+                kind: :symbol,
+                value: primitive || Utils.snake_case(local),
+              )
             end
 
             private
@@ -169,8 +172,10 @@ module Lutaml
                                                       element.simple_type)
               end
               if element.complex_type
-                return register_anonymous_complex_type("CT_#{element.name}",
-                                                       element.complex_type)
+                return register_anonymous_complex_type(
+                  "CT_#{element.name}", element.complex_type,
+                  root_name: element.name
+                )
               end
 
               "string"
@@ -184,8 +189,10 @@ module Lutaml
               end
 
               if item.respond_to?(:complex_type) && item.complex_type
-                register_anonymous_complex_type("CT_#{item.name}",
-                                                item.complex_type)
+                register_anonymous_complex_type(
+                  "CT_#{item.name}", item.complex_type,
+                  root_name: item.name
+                )
               end
             end
 
@@ -196,10 +203,10 @@ module Lutaml
               anon_name
             end
 
-            def register_anonymous_complex_type(anon_name, anon_node)
+            def register_anonymous_complex_type(anon_name, anon_node, root_name: nil)
               anon_node.name = anon_name
               @parent.complex_types[anon_name] =
-                @parent.build_complex_type(anon_node)
+                @parent.build_complex_type(anon_node, root_name: root_name)
               anon_name
             end
 

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

@@ -156,8 +156,8 @@ module Lutaml
             @simple_types_builder.build(simple_type)
           end
 
-          def build_complex_type(complex_type)
-            @complex_types_builder.build(complex_type)
+          def build_complex_type(complex_type, root_name: nil)
+            @complex_types_builder.build(complex_type, root_name: root_name)
           end
 
           private

data/lib/lutaml/model/schema/xml_compiler/supported_data_types.rb

@@ -83,6 +83,16 @@ module Lutaml
           def skippable?(value)
             SKIPPABLE_NAMES.include?(value.to_s)
           end
+
+          # Lutaml primitive symbol for a skippable XSD type
+          # (`"int"` -> `:integer`, `"dateTime"` -> `:date_time`); nil
+          # when the name is not a skippable built-in.
+          def primitive_symbol(value)
+            info = TABLE[value.to_sym]
+            return nil unless info && info[:skippable]
+
+            Utils.snake_case(info[:class_name].split("::").last)
+          end
         end
       end
     end

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

@@ -142,6 +142,7 @@ module Lutaml
           marks = {}
           simple = []
           complex = []
+          lazy = []
           attrs.each do |name, attr|
             next if attr.derived?
 
@@ -154,8 +155,17 @@ module Lutaml
             # per-attribute code, so its state is identical by
             # construction.
             marks[name] = false
-            if attr.default_kind == :none && attr.options[:values].nil? &&
-                name.to_s.match?(PLAIN_NAME)
+            plain_name = name.to_s.match?(PLAIN_NAME)
+            if plain_name && attr.lazy_collection_default?
+              # The implicit empty-collection default: the constructor
+              # ends at `[]` + a default mark, and the LAZY sentinel
+              # answers `[]` from the reader — so seed the sentinel and
+              # skip the per-instance lambda (#1010). The false mark is
+              # what the XML unmatched-rule contract reads: a seeded
+              # collection must not render as a mid-parse default.
+              lazy << name
+            elsif attr.default_kind == :none && attr.options[:values].nil? &&
+                plain_name
               simple << name
             else
               complex << name
@@ -169,6 +179,9 @@ module Lutaml
                          "@using_default = { #{pairs.join(', ')} }"
                        end
           simple_lines = simple.map { |n| "@#{n} = nil" }
+          lazy_lines = lazy.map do |n|
+            "@#{n} = Lutaml::Model::Serialize::LAZY_EMPTY_COLLECTION"
+          end
           complex_lines = complex.map do |n|
             "initialize_single_attribute({}, #{n.inspect}, " \
               "self.class.attributes(@lutaml_register)[#{n.inspect}], " \
@@ -179,6 +192,11 @@ module Lutaml
             define_method(method_name) do
               @using_default = marks
               simple.each { |n| IVAR_SET.bind_call(self, :"@#{n}", nil) }
+              lazy.each do |n|
+                IVAR_SET.bind_call(
+                  self, :"@#{n}", Lutaml::Model::Serialize::LAZY_EMPTY_COLLECTION
+                )
+              end
               complex.each do |n|
                 initialize_single_attribute(
                   {}, n, self.class.attributes(@lutaml_register)[n],
@@ -193,6 +211,7 @@ module Lutaml
             def #{method_name}
               #{marks_line}
               #{simple_lines.join("\n")}
+              #{lazy_lines.join("\n")}
               #{complex_lines.join("\n")}
             end
           RUBY
@@ -452,7 +471,7 @@ module Lutaml
 
           if !AttributeDefinition.source_compilation?
             define_block_attribute_setters(name, attr)
-          elsif attr.collection?
+          elsif attr.collection? && !attr.lazy_collection_default?
             # class_eval interpolates, e.g.:
             #   def items=(value)
             #     value_set_for(:items)
@@ -493,6 +512,25 @@ module Lutaml
                 record_mutation_collection(:#{name}, value)
               end
             RUBY
+          elsif attr.collection?
+            # Lazy-seeded default collections (#1010): a nil write is a
+            # real state here (initialize_empty reads nil after an
+            # explicit nil value), so it must land over the sentinel
+            # instead of preserving it.
+            class_eval(<<~RUBY, __FILE__, __LINE__ + 1) # rubocop:disable Style/DocumentDynamicEvalDefinition
+              def #{name}=(value)
+                value_set_for(:#{name})
+                value = __attribute_definition_#{name}.cast_value(value, lutaml_register)
+                @#{name} = value
+                record_mutation_collection(:#{name}, value)
+              end
+
+              def __assign_parsed_#{name}=(value)
+                value_set_for(:#{name})
+                @#{name} = value
+                record_mutation_collection(:#{name}, value)
+              end
+            RUBY
           else
             class_eval(<<~RUBY, __FILE__, __LINE__ + 1) # rubocop:disable Style/DocumentDynamicEvalDefinition
               def #{name}=(value)
@@ -551,7 +589,7 @@ module Lutaml
           name = name.to_sym # the compiled form passes :name literals
           ivar = :"@#{name}"
           handle = :"__attribute_definition_#{name}"
-          if attr.collection?
+          if attr.collection? && !attr.lazy_collection_default?
             assign = lambda do |model, value|
               current = IVAR_GET.bind_call(model, ivar)
               unless current.equal?(Lutaml::Model::Serialize::LAZY_EMPTY_COLLECTION) &&
@@ -568,6 +606,21 @@ module Lutaml
               value_set_for(name)
               assign.call(self, value)
             end
+          elsif attr.collection?
+            # Lazy-seeded default collections (#1010): nil lands over the
+            # sentinel — see the source-compiled branch.
+            assign = lambda do |model, value|
+              IVAR_SET.bind_call(model, ivar, value)
+              SEND.bind_call(model, :record_mutation_collection, name, value)
+            end
+            define_method(:"#{name}=") do |value|
+              value_set_for(name)
+              assign.call(self, SEND.bind_call(self, handle).cast_value(value, lutaml_register))
+            end
+            define_method(:"__assign_parsed_#{name}=") do |value|
+              value_set_for(name)
+              assign.call(self, value)
+            end
           else
             define_method(:"#{name}=") do |value|
               value_set_for(name)

data/lib/lutaml/model/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Model
-    VERSION = "0.8.130"
+    VERSION = "0.8.131"
   end
 end

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

@@ -19,13 +19,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/toml/adapter/tomlib_adapter.rb

@@ -34,13 +34,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/xml/builder/base.rb

@@ -116,7 +116,9 @@ module Lutaml
 
         def add_xml_fragment(element, content)
           target = resolve_target(element)
-          parsed = @context.parse("<__root__>#{content}</__root__>")
+          # The wrapper tag only gives the parser a root; its name is
+          # discarded — only the parsed children are adopted.
+          parsed = @context.parse("<fragment>#{content}</fragment>")
           parsed.root&.children&.each { |child| target.add_child(child) }
         rescue Moxml::ParseError
           target.add_child(@doc.create_text(content.to_s))

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

@@ -64,8 +64,8 @@ module Lutaml
           # This ensures root namespace is included in all_namespaces
           if mapping_dsl.namespace_class
             rules << ::Lutaml::Model::CompiledRule.new(
-              attribute_name: :__root_namespace__,
-              serialized_name: "__root__",
+              attribute_name: :root_namespace,
+              serialized_name: "root_namespace",
               namespace_class: mapping_dsl.namespace_class,
               mapping_type: :root_namespace,
             )

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

@@ -25,13 +25,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/yaml/adapter/yeptris_adapter.rb

@@ -91,13 +91,7 @@ module Lutaml
         private_class_method :syntax_error
 
         def to_yaml(_options = {})
-          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
 
           # Generation must match the standard (Psych) adapter's output
           # byte-for-byte: document separator, quoting of digit-leading

data/lib/lutaml/yamlld/adapter.rb

@@ -12,12 +12,7 @@ module Lutaml
       end
 
       def to_yamlld(options = {})
-        attributes_to_serialize =
-          if @attributes.is_a?(Lutaml::KeyValue::DataModel::Element)
-            @attributes.to_hash["__root__"]
-          else
-            @attributes
-          end
+        attributes_to_serialize = @attributes
         YAML.dump(attributes_to_serialize, options)
       end
     end

data/spec/lutaml/key_value/adapter/toml/teptris_adapter_spec.rb

@@ -54,12 +54,12 @@ RSpec.describe(TEPTRIS_AVAILABLE ? Lutaml::KeyValue::Adapter::Toml::TeptrisAdapt
         .to include("name", "[nested]", "a = [1, 2]")
     end
 
-    it "unwraps the __root__ KeyValueElement wrapper" do
-      element = Lutaml::KeyValue::DataModel::Element.new("__root__")
+    it "serializes Element children through their keyed hash shape" do
+      element = Lutaml::KeyValue::DataModel::Element.new("doc")
       name_child = Lutaml::KeyValue::DataModel::Element.new("name")
       name_child.value = "x"
       element.add_child(name_child)
-      expect(described_class.new(element).to_toml).to include("name")
+      expect(element.to_hash).to eq("doc" => { "name" => "x" })
     end
   end
 

data/spec/lutaml/key_value/transformation_spec.rb

@@ -69,14 +69,11 @@ RSpec.describe Lutaml::KeyValue::Transformation do
         transformation = described_class.new(KVSimpleModel, mapping, :json, nil)
 
         result = transformation.transform(model)
-        hash = { "__root__" => result }
-
-        # Remove __root__ wrapper
-        expect(hash["__root__"]).to eq({
-                                         "name" => "John",
-                                         "age" => 30,
-                                         "active" => true,
-                                       })
+        expect(result).to eq({
+                               "name" => "John",
+                               "age" => 30,
+                               "active" => true,
+                             })
       end
 
       it "handles nil values based on render_nil" do
@@ -85,10 +82,8 @@ RSpec.describe Lutaml::KeyValue::Transformation do
         transformation = described_class.new(KVSimpleModel, mapping, :json, nil)
 
         result = transformation.transform(model)
-        hash = { "__root__" => result }
-
         # nil values should be rendered by default
-        expect(hash["__root__"]["age"]).to be_nil
+        expect(result["age"]).to be_nil
       end
     end
 
@@ -101,16 +96,14 @@ RSpec.describe Lutaml::KeyValue::Transformation do
         transformation = described_class.new(KVPerson, mapping, :json, nil)
 
         result = transformation.transform(person)
-        hash = { "__root__" => result }
-
-        expect(hash["__root__"]).to eq({
-                                         "name" => "John",
-                                         "address" => {
-                                           "street" => "123 Main St",
-                                           "city" => "NYC",
-                                           "zip" => "10001",
-                                         },
-                                       })
+        expect(result).to eq({
+                               "name" => "John",
+                               "address" => {
+                                 "street" => "123 Main St",
+                                 "city" => "NYC",
+                                 "zip" => "10001",
+                               },
+                             })
       end
 
       it "handles nil nested model" do
@@ -119,10 +112,8 @@ RSpec.describe Lutaml::KeyValue::Transformation do
         transformation = described_class.new(KVPerson, mapping, :json, nil)
 
         result = transformation.transform(person)
-        hash = { "__root__" => result }
-
         # nil nested model should be in output (based on default render_nil)
-        expect(hash["__root__"]["address"]).to be_nil
+        expect(result["address"]).to be_nil
       end
     end
 
@@ -135,13 +126,11 @@ RSpec.describe Lutaml::KeyValue::Transformation do
         transformation = described_class.new(KVTeam, mapping, :json, nil)
 
         result = transformation.transform(team)
-        hash = { "__root__" => result }
-
-        expect(hash["__root__"]).to eq({
-                                         "name" => "Dev Team",
-                                         "members" => ["Alice", "Bob",
-                                                       "Charlie"],
-                                       })
+        expect(result).to eq({
+                               "name" => "Dev Team",
+                               "members" => ["Alice", "Bob",
+                                             "Charlie"],
+                             })
       end
 
       it "handles empty collection" do
@@ -150,10 +139,8 @@ RSpec.describe Lutaml::KeyValue::Transformation do
         transformation = described_class.new(KVTeam, mapping, :json, nil)
 
         result = transformation.transform(team)
-        hash = { "__root__" => result }
-
         # Empty collections are not rendered by default (render_empty defaults to false)
-        expect(hash["__root__"]["members"]).to be_nil
+        expect(result["members"]).to be_nil
       end
 
       it "handles nil collection" do
@@ -162,10 +149,8 @@ RSpec.describe Lutaml::KeyValue::Transformation do
         transformation = described_class.new(KVTeam, mapping, :json, nil)
 
         result = transformation.transform(team)
-        hash = { "__root__" => result }
-
         # nil collection should be nil by default
-        expect(hash["__root__"]["members"]).to be_nil
+        expect(result["members"]).to be_nil
       end
     end
 
@@ -188,9 +173,7 @@ RSpec.describe Lutaml::KeyValue::Transformation do
                                              nil)
 
         result = transformation.transform(model)
-        hash = { "__root__" => result }
-
-        expect(hash["__root__"]["name"]).to eq("JOHN")
+        expect(result["name"]).to eq("JOHN")
       end
     end
 
@@ -211,10 +194,8 @@ RSpec.describe Lutaml::KeyValue::Transformation do
         transformation = described_class.new(KVRenderModel, mapping, :json, nil)
 
         result = transformation.transform(model)
-        hash = { "__root__" => result }
-
         # optional should be omitted
-        expect(hash["__root__"].keys).not_to include("optional")
+        expect(result.keys).not_to include("optional")
       end
 
       it "omits default values when render_default: false" do
@@ -223,10 +204,8 @@ RSpec.describe Lutaml::KeyValue::Transformation do
         transformation = described_class.new(KVRenderModel, mapping, :json, nil)
 
         result = transformation.transform(model)
-        hash = { "__root__" => result }
-
         # defaulted should be omitted
-        expect(hash["__root__"].keys).not_to include("defaulted")
+        expect(result.keys).not_to include("defaulted")
       end
     end
   end
@@ -239,9 +218,6 @@ RSpec.describe Lutaml::KeyValue::Transformation do
 
       result = transformation.transform(model)
 
-      # Hash-direct emission: the __root__ Element tree (write-only in
-      # production, immediately flattened by every consumer) is gone;
-      # transform produces the output hash itself.
       expect(result).to be_a(Hash)
       expect(result).to eq("name" => "John", "age" => 30, "active" => true)
     end
@@ -257,7 +233,6 @@ RSpec.describe Lutaml::KeyValue::Transformation do
       expect(result).to be_a(Lutaml::KeyValue::DataModel::Element)
 
       # Presentation happens via to_hash, not during transformation
-      hash = { "__root__" => result }
       expect(hash).to be_a(Hash)
     end
   end
@@ -350,6 +325,31 @@ RSpec.describe Lutaml::KeyValue::Transformation do
       expect(model.to_hash).to eq("code" => "X")
     end
 
+    it "builds nested structures through chained Element writes" do
+      # glossarist's Citation#locality_to_yaml pattern: assign an empty
+      # hash child, then write into it through the hash-like reader —
+      # the reader must return the child's own value object.
+      klass = Class.new(Lutaml::Model::Serializable) do
+        attribute :type, :string
+        attribute :reference_from, :string
+
+        key_value do
+          map "locality", to: :type, with: { to: :locality_to_yaml }
+        end
+
+        def locality_to_yaml(model, doc)
+          doc["locality"] = {}
+          doc["locality"]["type"] = model.type
+          doc["locality"]["reference_from"] = model.reference_from
+        end
+      end
+
+      model = klass.new(type: "clause", reference_from: "§3")
+      expect(model.to_hash).to eq(
+        "locality" => { "type" => "clause", "reference_from" => "§3" },
+      )
+    end
+
     it "ignores a custom method's return value (mutation-only contract)" do
       # A method returning a hash without touching the doc serializes
       # as nothing — honoring returns merged child content at the

data/spec/lutaml/model/collection_spec.rb

@@ -416,6 +416,49 @@ RSpec.describe Lutaml::Model::Collection do
       expect(model.to_yaml).to eq(expected_yaml)
     end
 
+    # #1010: implicit-default collections are walk-seeded as the lazy
+    # sentinel instead of running the default lambda per instance. The
+    # sentinel answers [] on first read, and an explicit nil value must
+    # land over it — including through the deserialization fast path,
+    # whose writers otherwise preserve the sentinel.
+    it "reads nil when a parsed nil lands on the deserialization seed" do
+      klass = Class.new(Lutaml::Model::Serializable) do
+        attribute :items, :string, collection: true, initialize_empty: true
+        yaml { map "items", to: :items }
+      end
+
+      instance = klass.allocate_for_deserialization
+      instance.__assign_parsed_items = nil
+
+      expect(instance.items).to be_nil
+    end
+
+    it "materializes [] for untouched lazy-seeded collections" do
+      klass = Class.new(Lutaml::Model::Serializable) do
+        attribute :items, :string, collection: true, initialize_empty: true
+        yaml { map "items", to: :items }
+      end
+
+      parsed = klass.from_yaml("---\n{}\n")
+
+      expect(parsed.items).to eq([])
+      first = parsed.items
+      expect(parsed.items).to equal(first)
+    end
+
+    it "keeps an explicit default over the implicit empty collection" do
+      klass = Class.new(Lutaml::Model::Serializable) do
+        attribute :items, :integer,
+                  collection: true, initialize_empty: true,
+                  default: -> { [1, 2] }
+        yaml { map "items", to: :items }
+      end
+
+      parsed = klass.from_yaml("---\n{}\n")
+
+      expect(parsed.items).to eq([1, 2])
+    end
+
     it "raises StandardError for initialize_empty without collection" do
       expect do
         Class.new(Lutaml::Model::Serializable) do

data/spec/lutaml/model/schema/xml_compiler_runtime_spec.rb

@@ -49,4 +49,85 @@ RSpec.describe "runtime XSD class loading" do
       expect(doc.to_xml).to include('id="e1"')
     end
   end
+
+  # Anonymous (inline) complexTypes get CT_-prefixed internal names;
+  # the generated classes must still (a) map skippable XSD built-ins
+  # like xs:int to Lutaml primitives and (b) serialize the owning
+  # element name, not the internal alias (#1014).
+  describe "inline anonymous complexTypes" do
+    let(:catalogue_xsd) do
+      <<~XSD
+        <?xml version="1.0" encoding="UTF-8"?>
+        <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
+                   elementFormDefault="qualified">
+          <xs:element name="catalogue">
+            <xs:complexType>
+              <xs:sequence>
+                <xs:element name="title" type="xs:string"/>
+                <xs:element name="entry" maxOccurs="unbounded">
+                  <xs:complexType>
+                    <xs:sequence>
+                      <xs:element name="name" type="xs:string"/>
+                      <xs:element name="year" type="xs:int"/>
+                    </xs:sequence>
+                    <xs:attribute name="id" type="xs:string" use="required"/>
+                  </xs:complexType>
+                </xs:element>
+              </xs:sequence>
+            </xs:complexType>
+          </xs:element>
+        </xs:schema>
+      XSD
+    end
+
+    let(:catalogue_xml) do
+      <<~XML
+        <catalogue>
+          <title>Test</title>
+          <entry id="e1"><name>Alpha</name><year>2024</year></entry>
+          <entry id="e2"><name>Beta</name><year>2025</year></entry>
+        </catalogue>
+      XML
+    end
+
+    it "maps xs:int to :integer and parses the instance" do
+      Dir.mktmpdir do |dir|
+        Lutaml::Model::Schema.from_xml(
+          catalogue_xsd, output_dir: File.join(dir, "anon_ct_models"),
+                         load_classes: true
+        )
+
+        entry_class = AnonCtModels::CTEntry
+        expect(entry_class.attributes[:year].type).to eq(
+          Lutaml::Model::Type::Integer,
+        )
+
+        doc = AnonCtModels::CTCatalogue.from_xml(catalogue_xml)
+
+        expect(doc.title).to eq("Test")
+        expect(doc.entry.map(&:name)).to eq(["Alpha", "Beta"])
+        expect(doc.entry.map(&:year)).to eq([2024, 2025])
+        expect(doc.entry.map(&:id)).to eq(%w[e1 e2])
+      end
+    end
+
+    it "serializes the owning element name, not the CT_ alias" do
+      Dir.mktmpdir do |dir|
+        Lutaml::Model::Schema.from_xml(
+          catalogue_xsd, output_dir: File.join(dir, "anon_ct_models2"),
+                         load_classes: true
+        )
+
+        entry = AnonCtModels2::CTEntry.from_xml(
+          '<entry id="z9"><name>Gamma</name><year>1999</year></entry>',
+        )
+
+        expect(entry.name).to eq("Gamma")
+        expect(entry.year).to eq(1999)
+        expect(entry.id).to eq("z9")
+        expect(entry.to_xml).to include('<entry id="z9">')
+        expect(entry.to_xml).not_to include("CT_entry")
+      end
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lutaml-model
 version: !ruby/object:Gem::Version
-  version: 0.8.130
+  version: 0.8.131
 platform: ruby
 authors:
 - Ribose Inc.