lutaml-model 0.8.11 → 0.8.13

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

@@ -7,10 +7,8 @@ module Lutaml
             super(:toml)
           end
 
-          def deep_dup
-            self.class.new.tap do |new_mapping|
-              new_mapping.mappings = duplicate_mappings
-            end
+          def dup_instance
+            self.class.new
           end
 
           def validate!(key, to, with, render_nil, render_empty)

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

@@ -7,10 +7,8 @@ module Lutaml
             super(:yaml)
           end
 
-          def deep_dup
-            self.class.new.tap do |new_mapping|
-              new_mapping.mappings = duplicate_mappings
-            end
+          def dup_instance
+            self.class.new
           end
         end
       end

data/lib/lutaml/key_value/adapter/yamls/mapping.rb

@@ -7,10 +7,8 @@ module Lutaml
             super(:yaml)
           end
 
-          def deep_dup
-            self.class.new.tap do |new_mapping|
-              new_mapping.mappings = duplicate_mappings
-            end
+          def dup_instance
+            self.class.new
           end
         end
       end

data/lib/lutaml/key_value/mapping.rb

@@ -21,20 +21,45 @@ module Lutaml
         @finalized
       end
 
+      # Set the wrapper key for key-value serialization (JSON, YAML, TOML).
+      #
+      # When set, serialized output wraps all instances under this key
+      # (e.g., `key "items"` produces `{"items": [...]}`).
+      # When not called (or called with nil), instances are serialized directly
+      # at the top level (e.g., `[...]`).
+      #
+      # @param name [String, nil] the wrapper key name
+      def key(name = nil)
+        @key = name
+      end
+
+      def key_name
+        @key
+      end
+
+      # @deprecated Use {#key} instead. In key-value formats, the wrapper is a key, not a root.
       def root(name = nil)
-        @root = name
+        @key = name
       end
 
+      # @deprecated Omit key call instead. Not calling key means no wrapper key.
       def no_root
-        @root = nil
+        @key = nil
+      end
+
+      # Returns true when no wrapper key is set (instances serialized at top level).
+      def no_key?
+        @key.nil?
       end
 
+      # @deprecated Use {#no_key?} instead.
       def no_root?
-        @root.nil?
+        no_key?
       end
 
+      # @deprecated Use {#key_name} instead.
       def root_name
-        @root
+        @key
       end
 
       def map(
@@ -104,7 +129,7 @@ module Lutaml
 
       def map_instances(to:, polymorphic: {})
         @instance = to
-        map(root_name || to, to: to, polymorphic: polymorphic)
+        map(key_name || to, to: to, polymorphic: polymorphic)
         map_to_instance
       end
 
@@ -125,7 +150,7 @@ module Lutaml
       def map_to_instance
         return if !instance_mapping?
 
-        mapping_name = name_for_mapping(nil, root_name || @instance)
+        mapping_name = name_for_mapping(nil, key_name || @instance)
         @mappings[mapping_name].child_mappings = @key_mapping.merge(@value_mapping)
       end
 
@@ -218,17 +243,17 @@ module Lutaml
       end
 
       # Writers for deep_dup in subclasses
-      attr_writer :mappings, :register_mappings
+      attr_writer :register_mappings
 
       def deep_dup
-        self.class.new(@format).tap do |new_mapping|
+        dup_instance.tap do |new_mapping|
           new_mapping.mappings = duplicate_mappings
           new_mapping.register_mappings = Lutaml::Model::Utils.deep_dup(@register_mappings)
         end
       end
 
-      def duplicate_mappings
-        Lutaml::Model::Utils.deep_dup(@mappings)
+      def dup_instance
+        self.class.new(@format)
       end
 
       def find_by_to(to)

data/lib/lutaml/model/adapter_resolver.rb

@@ -370,15 +370,12 @@ module Lutaml
 
         # Detect available XML adapter.
         #
-        # @return [Symbol, nil] :nokogiri, :ox, :oga, :rexml, or nil
+        # Delegates to moxml which is the authority on XML adapter
+        # availability and platform constraints (Opal, MRI, etc.).
+        #
+        # @return [Symbol] adapter type name
         def detect_xml_adapter
-          return :oga if RuntimeCompatibility.opal?
-          return :nokogiri if Utils.safe_load("nokogiri", :Nokogiri)
-          return :ox if Utils.safe_load("ox", :Ox)
-          return :oga if Utils.safe_load("oga", :Oga)
-          return :rexml if Utils.safe_load("rexml", :REXML)
-
-          nil
+          Moxml::Config.runtime_default_adapter
         end
 
         # Detect available TOML adapter.

data/lib/lutaml/model/collection.rb

@@ -310,8 +310,8 @@ module Lutaml
         def to(format, instance, options = {})
           mappings = mappings_for(format)
 
-          if mappings.no_root? && collection_no_root_to?(format)
-            collection_no_root_to(format, mappings, instance, options)
+          if mappings.no_root? && collection_unwrapped_to?(format)
+            collection_unwrapped_to(format, mappings, instance, options)
           else
             super(format, instance, options.merge(collection: true))
           end
@@ -322,7 +322,7 @@ module Lutaml
           data = super
 
           if !collection_structured_format?(format) && mappings.no_root? && !mappings.root_mapping
-            unwrap_no_root_data(data)
+            unwrap_unwrapped_data(data)
           else
             data
           end
@@ -332,7 +332,7 @@ module Lutaml
           mappings = mappings_for(format)
 
           if collection_structured_format?(format) && mappings.no_root?
-            data = wrap_no_root_input(format, mappings, data)
+            data = wrap_unwrapped_input(format, mappings, data)
           end
 
           super(format, data, options.merge(from_collection: true))
@@ -355,21 +355,21 @@ module Lutaml
           false
         end
 
-        # Hook: returns true if this format handles no_root serialization specially.
+        # Hook: returns true if this format handles unwrapped serialization specially.
         # XML overrides to return true for :xml format.
-        def collection_no_root_to?(_format)
+        def collection_unwrapped_to?(_format)
           false
         end
 
-        # Hook for structured-format no_root serialization (e.g., XML).
+        # Hook for unwrapped serialization (e.g., XML).
         # XML overrides to serialize each mapping separately.
-        def collection_no_root_to(_format, _mappings, _instance, _options)
+        def collection_unwrapped_to(_format, _mappings, _instance, _options)
           raise NotImplementedError
         end
 
-        # Hook for structured-format no_root input wrapping (e.g., XML).
+        # Hook for wrapping unwrapped input (e.g., XML).
         # XML overrides to wrap raw data in a fake root tag.
-        def wrap_no_root_input(_format, _mappings, data)
+        def wrap_unwrapped_input(_format, _mappings, data)
           data
         end
 
@@ -379,7 +379,7 @@ module Lutaml
 
         private
 
-        def unwrap_no_root_data(data)
+        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)

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

@@ -1,9 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "type_only_mapping_error"
+
 module Lutaml
   module Model
-    class NoRootMappingError < Error
-      def initialize(model)
-        super("#{model} has `no_root`, it allowed only for reusable models")
-      end
-    end
+    # @deprecated Use {TypeOnlyMappingError} instead.
+    NoRootMappingError = TypeOnlyMappingError
   end
 end

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

@@ -1,9 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "type_only_namespace_error"
+
 module Lutaml
   module Model
-    class NoRootNamespaceError < Error
-      def to_s
-        "Cannot assign namespace to `no_root`"
-      end
-    end
+    # @deprecated Use {TypeOnlyNamespaceError} instead.
+    NoRootNamespaceError = TypeOnlyNamespaceError
   end
 end

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

@@ -0,0 +1,13 @@
+module Lutaml
+  module Model
+    class TypeOnlyMappingError < Error
+      def initialize(model)
+        super("#{model} is a type-only model (no element declared), " \
+              "it can only be used as an embedded type through a parent model.")
+      end
+    end
+
+    # @deprecated Use {TypeOnlyMappingError} instead.
+    NoRootMappingError = TypeOnlyMappingError
+  end
+end

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

@@ -0,0 +1,12 @@
+module Lutaml
+  module Model
+    class TypeOnlyNamespaceError < Error
+      def to_s
+        "Cannot assign namespace to a type-only model (no element declared)."
+      end
+    end
+
+    # @deprecated Use {TypeOnlyNamespaceError} instead.
+    NoRootNamespaceError = TypeOnlyNamespaceError
+  end
+end

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

@@ -3,6 +3,8 @@ module Lutaml
     class Mapping
       include DeepDupable
 
+      attr_writer :mappings
+
       def initialize
         @mappings = []
         @listeners = {} # target => [Listener, ...]
@@ -11,6 +13,16 @@ module Lutaml
         @mappings_imported = ::Hash.new { |h, k| h[k] = false }
       end
 
+      def deep_dup
+        duped = self.class.new
+        duped.mappings = duplicate_mappings
+        duped
+      end
+
+      def duplicate_mappings
+        Lutaml::Model::Utils.deep_dup(@mappings)
+      end
+
       # Get listeners for a specific target (element name/key).
       #
       # @param target [String, Symbol] The element name or key

data/lib/lutaml/model/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Model
-    VERSION = "0.8.11"
+    VERSION = "0.8.13"
   end
 end

data/lib/lutaml/model.rb

@@ -149,6 +149,7 @@ module Lutaml
              "#{__dir__}/model/error/incorrect_sequence_error"
     autoload :ChoiceUpperBoundError,
              "#{__dir__}/model/error/choice_upper_bound_error"
+    autoload :TypeOnlyMappingError, "#{__dir__}/model/error/type_only_mapping_error"
     autoload :NoRootMappingError, "#{__dir__}/model/error/no_root_mapping_error"
     autoload :ImportModelWithRootError,
              "#{__dir__}/model/error/import_model_with_root_error"
@@ -160,6 +161,8 @@ module Lutaml
              "#{__dir__}/model/error/choice_lower_bound_error"
     autoload :NoMappingFoundError,
              "#{__dir__}/model/error/no_mapping_found_error"
+    autoload :TypeOnlyNamespaceError,
+             "#{__dir__}/model/error/type_only_namespace_error"
     autoload :NoRootNamespaceError,
              "#{__dir__}/model/error/no_root_namespace_error"
     autoload :PolymorphicError, "#{__dir__}/model/error/polymorphic_error"

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

@@ -8,10 +8,8 @@ module Lutaml
           super(:toml)
         end
 
-        def deep_dup
-          self.class.new.tap do |new_mapping|
-            new_mapping.mappings = duplicate_mappings
-          end
+        def dup_instance
+          self.class.new
         end
 
         def validate!(key, to, with, render_nil, render_empty)

data/lib/lutaml/xml/adapter/base_adapter.rb

@@ -1,14 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "../document"
-require_relative "../declaration_handler"
-require_relative "../doctype_extractor"
-require_relative "../polymorphic_value_handler"
-require_relative "xml_parser"
-require_relative "xml_serializer"
-require_relative "plan_based_builder"
-require_relative "namespace_uri_collector"
-
 module Lutaml
   module Xml
     module Adapter

data/lib/lutaml/xml/adapter/nokogiri_adapter.rb

@@ -2,7 +2,6 @@
 
 require "moxml"
 require "moxml/adapter/nokogiri"
-require_relative "base_adapter"
 
 module Lutaml
   module Xml

data/lib/lutaml/xml/adapter/oga_adapter.rb

@@ -2,7 +2,6 @@
 
 require "oga"
 require "moxml/adapter/oga"
-require_relative "base_adapter"
 
 module Lutaml
   module Xml

data/lib/lutaml/xml/adapter/ox_adapter.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "moxml/adapter/ox"
-require_relative "base_adapter"
 
 module Lutaml
   module Xml

data/lib/lutaml/xml/adapter/rexml_adapter.rb

@@ -3,7 +3,6 @@
 require "rexml/document"
 require "moxml"
 require "moxml/adapter/rexml"
-require_relative "base_adapter"
 
 module Lutaml
   module Xml

data/lib/lutaml/xml/adapter/xml_serializer.rb

@@ -49,6 +49,35 @@ module Lutaml
           encoding = determine_encoding(options)
           builder_options = {}
           builder_options[:encoding] = encoding if encoding
+          builder_options[:line_ending] = options[:line_ending] if options.key?(:line_ending)
+          builder_options[:indent] = options[:indent] if options.key?(:indent)
+
+          # Pass doctype to builder for document-level insertion
+          doctype_to_use = options[:doctype] || @doctype
+          if doctype_to_use && !options[:omit_doctype]
+            builder_options[:doctype] = doctype_to_use
+          end
+
+          # Pass declaration info to builder
+          if should_include_declaration?(options)
+            builder_options[:include_declaration] = true
+            builder_options[:xml_declaration] = @xml_declaration || {}
+            if options.key?(:standalone)
+              if options[:standalone] == :preserve
+                # Keep original standalone from parsed declaration (may be nil)
+              else
+                builder_options[:xml_declaration][:standalone] = standalone_value(options[:standalone])
+              end
+            end
+            if options[:declaration].is_a?(String)
+              builder_options[:xml_declaration][:version] = options[:declaration]
+            elsif options[:declaration] == true
+              builder_options[:xml_declaration][:version] = "1.0"
+            end
+            builder_options[:xml_declaration][:encoding] = encoding if options.key?(:encoding) && encoding
+          elsif options[:encoding] && !options[:encoding].nil?
+            builder_options[:force_declaration] = true
+          end
 
           builder = self.class::BUILDER_CLASS.build(builder_options) do |xml|
             if root.is_a?(self.class::PARSED_ELEMENT_CLASS)
@@ -58,7 +87,7 @@ module Lutaml
             end
           end
 
-          finalize_adapter_xml(builder.to_xml, encoding, options)
+          builder.to_xml
         end
 
         def build_serializable_xml(xml, options)
@@ -95,6 +124,14 @@ module Lutaml
 
         private
 
+        def standalone_value(value)
+          case value
+          when true then "yes"
+          when false then "no"
+          else value.to_s
+          end
+        end
+
         def transformable_xml_element(options)
           return root if root.is_a?(Lutaml::Xml::DataModel::XmlElement)
 
@@ -183,27 +220,8 @@ module Lutaml
           options_with_original_ns
         end
 
-        def finalize_adapter_xml(xml_data, encoding, options)
-          result = ""
-          if (options[:encoding] && !options[:encoding].nil?) ||
-              should_include_declaration?(options)
-            result += generate_declaration(options)
-          end
-
-          doctype_to_use = options[:doctype] || @doctype
-          if doctype_to_use && !options[:omit_doctype]
-            result += generate_doctype_declaration(doctype_to_use)
-          end
-
-          result += xml_data
-          if encoding && result.encoding.to_s.upcase != encoding.to_s.upcase
-            result = result.encode(encoding)
-          end
-          result
-        end
-
         def text_content_for_xml(value)
-          ::Moxml::Adapter::Base.preprocess_entities(value.to_s)
+          ::Moxml.preprocess_entities(value.to_s)
         end
 
         def build_plan_node(xml, xml_element, element_node, plan: nil,
@@ -212,7 +230,9 @@ module Lutaml
           attributes = {}
 
           original_ns_uris = plan&.original_namespace_uris || {}
-          element_node.hoisted_declarations.each do |key, uri|
+          element_node.hoisted_declarations.sort_by do |prefix, _uri|
+            prefix.nil? ? "" : prefix.to_s
+          end.each do |key, uri|
             next if uri == "http://www.w3.org/XML/1998/namespace"
 
             effective_uri = if self.class.fpi?(uri)

data/lib/lutaml/xml/adapter.rb

@@ -7,6 +7,10 @@ module Lutaml
       autoload :AdapterHelpers, "#{__dir__}/adapter/adapter_helpers"
       autoload :BaseAdapter, "#{__dir__}/adapter/base_adapter"
       autoload :NamespaceData, "#{__dir__}/adapter/namespace_data"
+      autoload :XmlParser, "#{__dir__}/adapter/xml_parser"
+      autoload :XmlSerializer, "#{__dir__}/adapter/xml_serializer"
+      autoload :PlanBasedBuilder, "#{__dir__}/adapter/plan_based_builder"
+      autoload :NamespaceUriCollector, "#{__dir__}/adapter/namespace_uri_collector"
       autoload :OgaAdapter, "#{__dir__}/adapter/oga_adapter"
       Lutaml::Model::RuntimeCompatibility.autoload_native(
         self,

data/lib/lutaml/xml/builder/base.rb

@@ -7,15 +7,63 @@ module Lutaml
     module Builder
       # Base builder for XML construction using moxml.
       # All adapter-specific builders inherit from this class.
+      #
+      # The builder creates XML documents through moxml's document model.
+      # Declaration, doctype, indentation, and line endings are handled
+      # by moxml — no manual string assembly.
       class Base
         def self.build(options = {})
           context = Moxml.new(moxml_backend)
           if Lutaml::Model::RuntimeCompatibility.opal?
             context.config.namespace_validation_mode = :lenient
           end
+
+          encoding_value = options.delete(:encoding)
+          context.config.default_indent = options.delete(:indent) if options.key?(:indent)
+          context.config.default_line_ending = options.delete(:line_ending) if options.key?(:line_ending)
+
           doc = context.create_document
+
+          # Capture doctype — added after root to avoid Ox incompatibility
+          doctype = options.delete(:doctype)
+
           instance = new(doc, context, options)
+          instance.encoding = encoding_value if encoding_value
           yield(instance) if block_given?
+
+          # Add doctype before root (after build block sets root)
+          if doctype && doc.root
+            dt = doc.create_doctype(
+              doctype[:name],
+              doctype[:public_id],
+              doctype[:system_id],
+            )
+            doc.add_child(dt)
+          end
+
+          # Handle declaration — configure it on the document so moxml
+          # serializes it natively (works across all adapters)
+          xml_decl = options.delete(:xml_declaration) || {}
+          include_decl = options.delete(:include_declaration)
+          force_decl = options.delete(:force_declaration)
+
+          if include_decl
+            version = xml_decl[:version] || "1.0"
+            encoding = xml_decl[:encoding]
+            encoding ||= "UTF-8" unless xml_decl[:had_declaration]
+            standalone = xml_decl[:standalone]
+            decl = doc.create_declaration(version, encoding, standalone)
+            doc.add_child(decl)
+            instance.declaration_mode = :default
+          elsif force_decl
+            decl_encoding = encoding_value || "UTF-8"
+            decl = doc.create_declaration("1.0", decl_encoding, nil)
+            doc.add_child(decl)
+            instance.declaration_mode = :default
+          else
+            instance.declaration_mode = :none
+          end
+
           instance
         end
 
@@ -24,13 +72,15 @@ module Lutaml
           nil
         end
 
-        attr_reader :doc, :encoding
+        attr_reader :doc
+        attr_accessor :encoding, :declaration_mode
 
         def initialize(doc, context, options = {})
           @doc = doc
           @context = context
           @encoding = options[:encoding]
           @current_stack = [doc]
+          @declaration_mode = :none
         end
 
         def current_element
@@ -116,33 +166,15 @@ module Lutaml
           add_cdata(current_element, content)
         end
 
-        def to_s
+        def to_xml
           return "" unless @doc.root
 
-          # Serialize full document content (including PIs before root)
-          # Check if there are any nodes before the root element
-          doc_children = @doc.children
-          has_pi_or_comment = doc_children.any? do |child|
-            child.is_a?(Moxml::ProcessingInstruction) || child.is_a?(Moxml::Comment)
-          end
-
-          if has_pi_or_comment
-            # Serialize each top-level node individually
-            parts = doc_children.map do |child|
-              if child == @doc.root
-                child.to_xml(declaration: false, expand_empty: false)
-              else
-                child.to_xml
-              end
-            end
-            parts.join("\n")
-          else
-            @doc.root.to_xml(declaration: false, expand_empty: false)
-          end
-        end
+          result = if @declaration_mode == :none && !has_document_level_nodes?
+                     @doc.root.to_xml(declaration: false, expand_empty: false)
+                   else
+                     @doc.to_xml(declaration: @declaration_mode == :default, expand_empty: false)
+                   end
 
-        def to_xml
-          result = to_s
           result = result.encode(encoding) if encoding && result.encoding.to_s != encoding
           result
         end
@@ -158,6 +190,13 @@ module Lutaml
 
         private
 
+        def has_document_level_nodes?
+          @doc.children.any? do |child|
+            child != @doc.root &&
+              !child.is_a?(Moxml::Text)
+          end
+        end
+
         def resolve_target(element)
           element.is_a?(self.class) || element.is_a?(Base) ? element.current_element : element
         end

data/lib/lutaml/xml/builder/nokogiri.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "base"
-
 module Lutaml
   module Xml
     module Builder

data/lib/lutaml/xml/builder/oga.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "base"
-
 module Lutaml
   module Xml
     module Builder

data/lib/lutaml/xml/builder/ox.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "base"
-
 module Lutaml
   module Xml
     module Builder