lutaml-model 0.8.15 → 0.8.16

data/lib/lutaml/model/attribute.rb

@@ -665,6 +665,10 @@ instance_object = nil)
       def process_options!
         validate_options!(@options)
         @raw = !!@options[:raw]
+        if @raw
+          warn "[DEPRECATED] attribute :#{name}, :string, raw: true is deprecated. " \
+               "Use map_element \"name\", to: :#{name}, raw: :content instead."
+        end
         @validations = @options[:validations]
         set_default_for_collection if collection?
       end

data/lib/lutaml/model/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Model
-    VERSION = "0.8.15"
+    VERSION = "0.8.16"
   end
 end

data/lib/lutaml/model.rb

@@ -149,7 +149,8 @@ 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 :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"

data/lib/lutaml/turtle/transform.rb

@@ -66,7 +66,8 @@ module Lutaml
           emit_type_statements(graph, subject_uri, mapping)
           emit_predicate_statements(graph, subject_uri, instance, mapping)
           emit_member_link_statements(graph, subject_uri, instance, mapping)
-          additional_resource_triples(instance, subject_uri, mapping).each do |stmt|
+          additional_resource_triples(instance, subject_uri,
+                                      mapping).each do |stmt|
             graph << stmt
           end
         end

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

@@ -332,6 +332,8 @@ module Lutaml
                                     xml_mapping: xml_mapping)
                 when Lutaml::Xml::DataModel::XmlComment
                   inner_xml.add_comment(child.content)
+                when Lutaml::Xml::DataModel::XmlRawFragment
+                  inner_xml.add_xml_fragment(inner_xml, child.content)
                 when String
                   if element.cdata
                     inner_xml.cdata(child.to_s)
@@ -764,7 +766,7 @@ module Lutaml
             xml.create_and_add_element(rule.name,
                                        attributes: attributes.empty? ? nil : attributes,
                                        prefix: resolved_prefix)
-          elsif rule.raw_mapping?
+          elsif rule.raw_mapping? || rule.raw == :element
             xml.add_xml_fragment(xml, value)
           elsif value.is_a?(::Hash) && attribute&.type(register) == Lutaml::Model::Type::Hash
             xml.create_and_add_element(rule.name,

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

@@ -49,7 +49,10 @@ 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)
+          if options.key?(:line_ending)
+            builder_options[:line_ending] =
+              options[:line_ending]
+          end
           builder_options[:indent] = options[:indent] if options.key?(:indent)
 
           # Pass doctype to builder for document-level insertion
@@ -66,15 +69,20 @@ module Lutaml
               if options[:standalone] == :preserve
                 # Keep original standalone from parsed declaration (may be nil)
               else
-                builder_options[:xml_declaration][:standalone] = standalone_value(options[:standalone])
+                builder_options[:xml_declaration][:standalone] =
+                  standalone_value(options[:standalone])
               end
             end
             if options[:declaration].is_a?(String)
-              builder_options[:xml_declaration][:version] = options[:declaration]
+              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
+            if options.key?(:encoding) && encoding
+              builder_options[:xml_declaration][:encoding] =
+                encoding
+            end
           elsif options[:encoding] && !options[:encoding].nil?
             builder_options[:force_declaration] = true
           end
@@ -287,6 +295,8 @@ module Lutaml
                 previous_child_had_xmlns_blank ||= child_node.needs_xmlns_blank
               when Lutaml::Xml::DataModel::XmlComment
                 xml.add_comment(xml_child.content)
+              when Lutaml::Xml::DataModel::XmlRawFragment
+                xml.add_xml_fragment(xml, xml_child.content)
               when String
                 if xml_element.cdata
                   xml.cdata(xml_child.to_s)

data/lib/lutaml/xml/adapter.rb

@@ -10,7 +10,8 @@ module Lutaml
       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 :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

@@ -172,7 +172,8 @@ module Lutaml
           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)
+                     @doc.to_xml(declaration: @declaration_mode == :default,
+                                 expand_empty: false)
                    end
 
           result = result.encode(encoding) if encoding && result.encoding.to_s != encoding

data/lib/lutaml/xml/data_model.rb

@@ -87,10 +87,10 @@ module Lutaml
         # @raise [TypeError] if child is not a supported type
         def add_child(child)
           unless child.is_a?(XmlElement) || child.is_a?(String) ||
-              child.is_a?(XmlComment)
+              child.is_a?(XmlComment) || child.is_a?(XmlRawFragment)
             raise TypeError,
-                  "XmlElement#add_child expects XmlElement, String, or " \
-                  "XmlComment, got #{child.class}"
+                  "XmlElement#add_child expects XmlElement, String, " \
+                  "XmlComment, or XmlRawFragment, got #{child.class}"
           end
 
           @children << child
@@ -261,6 +261,22 @@ module Lutaml
         end
       end
 
+      # Represents a raw XML fragment that should be serialized as-is.
+      #
+      # Used by raw_element mappings to embed complete XML elements (e.g., SVG,
+      # MathML) without parsing, wrapping, or escaping.
+      class XmlRawFragment
+        attr_reader :content
+
+        def initialize(content)
+          @content = content.to_s
+        end
+
+        def to_s
+          @content
+        end
+      end
+
       # Represents an XML comment in the data model tree.
       # Stored as a child of XmlElement alongside String (text) and XmlElement children.
       class XmlComment

data/lib/lutaml/xml/mapping.rb

@@ -510,7 +510,8 @@ module Lutaml
       form: nil,
       documentation: nil,
       xsd_type: (xsd_type_provided = false
-                 nil)
+                 nil),
+      raw: nil
       )
         validate!(
           name, to, with, render_nil, render_empty, type: TYPES[:element]
@@ -562,6 +563,7 @@ module Lutaml
           value_map: value_map,
           form: form,
           documentation: documentation,
+          raw: raw,
         )
         # Store rules with the same element name in an array to support
         # multiple mapping rules for the same element name with different target types

data/lib/lutaml/xml/mapping_rule.rb

@@ -10,7 +10,8 @@ module Lutaml
                   :as_list,
                   :delimiter,
                   :form,
-                  :documentation
+                  :documentation,
+                  :raw
 
       # Writers for deep_dup (preserves exact object references)
       attr_accessor :namespace, :prefix, :namespace_class
@@ -39,7 +40,8 @@ module Lutaml
       as_list: nil,
       delimiter: nil,
       form: nil,
-      documentation: nil
+      documentation: nil,
+      raw: nil
       )
         super(
           name,
@@ -76,6 +78,7 @@ module Lutaml
         @delimiter = delimiter
         @form = validate_form(form)
         @documentation = documentation
+        @raw = validate_raw(raw)
 
         # Memoize prefixed_name at initialization for performance
         # This is safe because prefix and name are immutable after initialization
@@ -103,6 +106,10 @@ module Lutaml
         @static_namespace_option ||= { default_namespace: namespace }.freeze
       end
 
+      def raw_element?
+        @raw == :element
+      end
+
       def content_mapping?
         name.nil?
       end
@@ -225,6 +232,7 @@ module Lutaml
           delimiter: @delimiter,
           form: @form,
           documentation: @documentation,
+          raw: @raw,
         ).tap do |dup_rule|
           # Manually preserve the exact @namespace_class object to avoid
           # recreating anonymous classes (which would have different object_ids)
@@ -573,6 +581,24 @@ form_default = :unqualified)
 
         form
       end
+
+      def validate_raw(raw)
+        return nil if raw.nil? || raw == false
+
+        valid_raw = %i[element content]
+        if raw == true
+          warn "[DEPRECATED] raw: true on map_element is deprecated, " \
+               "use raw: :element instead."
+          return :element
+        end
+
+        unless valid_raw.include?(raw)
+          raise ArgumentError,
+                "raw must be :element or :content, got #{raw.inspect}"
+        end
+
+        raw
+      end
     end
   end
 end

data/lib/lutaml/xml/model_transform.rb

@@ -668,6 +668,12 @@ _effective_register)
             !child_ns_prefix && rule_names.any? do |rn|
               ((colon = rn.rindex(":")) ? rn[(colon + 1)..] : rn) == child.unprefixed_name
             end
+          elsif !rule_namespace_set && (!child_ns_prefix || rule.raw == :element)
+            # For simple types (String, etc.) with no namespace constraint,
+            # match by unprefixed name. Handles elements in foreign namespaces
+            # (e.g., SVG inside <image>). raw_element rules match regardless
+            # of prefix — the intent is to capture any element with that name.
+            child.unprefixed_name == rule_name_str
           else
             false
           end
@@ -765,7 +771,9 @@ _effective_register)
             end
 
             values << cast_result
-          elsif attr.raw?
+          elsif rule.raw == :element
+            values << child.to_xml
+          elsif rule.raw == :content || attr.raw?
             values << inner_xml_of(child)
           else
             return nil if rule.render_nil_as_nil? && child.nil_element?

data/lib/lutaml/xml/serialization/instance_methods.rb

@@ -155,23 +155,30 @@ module Lutaml
           # Using ::Hash to avoid conflict with Lutaml::Model::Hash
           collection_indices = ::Hash.new(0)
 
+          content_is_mixed = mixed?
+
           element_order.each do |el|
             if el.text?
-              # Text node - yield the text content (skip whitespace-only)
               text = el.text_content
-              yield(text) if text && !text.strip.empty?
+              if text && !text.empty? && (content_is_mixed || !text.strip.empty?)
+                # Mixed content: all text is significant (e.g. "Hello " before <b>)
+                # Ordered-only: skip whitespace-only text (indentation between elements)
+                yield(text)
+              end
             elsif el.element?
               # Element node - look up mapped collection and get next item
               attr_name = element_to_attr[el.name]
               next unless attr_name
 
-              collection = send(attr_name)
-              next unless collection.is_a?(Array)
-
-              index = collection_indices[attr_name]
-              collection_indices[attr_name] += 1
-
-              obj = collection[index]
+              val = send(attr_name)
+              obj = if val.is_a?(Array)
+                      index = collection_indices[attr_name]
+                      collection_indices[attr_name] += 1
+                      val[index]
+                    elsif val.is_a?(Lutaml::Model::Serializable)
+                      collection_indices[attr_name] += 1
+                      collection_indices[attr_name] == 1 ? val : nil
+                    end
               yield(obj) if obj
             end
           end

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

@@ -112,8 +112,6 @@ parent_element_form_default)
           end
         end
 
-        private
-
         # Create element for nested model
         #
         # @param rule [CompiledRule] The rule
@@ -212,7 +210,7 @@ child_transformation)
           #   with different URIs) -> child has its own ns, use child's prefix_default
           # - Child's namespace is self-declared through its attribute TYPE (different from parent)
           #   -> child's XmlElement gets its own ns, use child's prefix_default
-          child_ns_class = if value.class.respond_to?(:mappings_for)
+          child_ns_class = if value.is_a?(::Lutaml::Model::Serialize)
                              value.class.mappings_for(:xml)&.namespace_class
                            end
           ns_prefix = nil

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

@@ -84,6 +84,12 @@ register_id, register)
             return
           end
 
+          # raw: :element — value is a complete XML element string, inject directly
+          if rule.raw == :element
+            add_raw_element_fragments(parent, value)
+            return
+          end
+
           # Extract parent's namespace info for element_form_default inheritance
           parent_ns_class = parent.namespace_class
           # Only pass element_form_default VALUE if it was explicitly set
@@ -201,6 +207,21 @@ register_id)
 
         private
 
+        # Add raw element fragments to parent, handling single values and collections.
+        #
+        # @param parent [XmlElement] Parent element
+        # @param value [Object, Array] Raw XML string(s)
+        def add_raw_element_fragments(parent, value)
+          return if value.nil?
+
+          items = value.is_a?(Array) ? value : [value]
+          items.each do |item|
+            next if item.nil? || item.to_s.empty?
+
+            parent.add_child(::Lutaml::Xml::DataModel::XmlRawFragment.new(item.to_s))
+          end
+        end
+
         # Check if rule is custom-method-only (no real attribute)
         #
         # @param rule [CompiledRule] The rule

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

@@ -253,6 +253,15 @@ _register)
 
         private
 
+        # Resolve the unified raw mode from mapping rule and attribute
+        #
+        # @param mapping_rule [Xml::MappingRule] The mapping rule
+        # @param attr [Attribute, nil] The attribute (nil for custom methods)
+        # @return [Symbol, nil] :element, :content, or nil
+        def resolve_raw_mode(mapping_rule, attr)
+          mapping_rule.raw || (attr&.raw? ? :content : nil)
+        end
+
         # Infer attribute name from mapping rule or custom methods
         #
         # @param mapping_rule [Xml::MappingRule] The mapping rule
@@ -321,7 +330,7 @@ register_id, register, attr_name, custom_methods_value)
             mapping_type: :element,
             cdata: mapping_rule.cdata,
             mixed_content: mapping_rule.mixed_content?,
-            raw: attr.raw?,
+            raw: resolve_raw_mode(mapping_rule, attr),
             render_default: mapping_rule.render_default,
             value_map: value_map,
             custom_methods: custom_methods_value,
@@ -350,7 +359,7 @@ custom_methods_value)
             mapping_type: :element,
             cdata: mapping_rule.cdata,
             mixed_content: mapping_rule.mixed_content?,
-            raw: false,
+            raw: mapping_rule.raw,
             render_default: mapping_rule.render_default,
             value_map: value_map,
             custom_methods: custom_methods_value,
@@ -401,7 +410,7 @@ register_id, register, custom_methods_value)
             mapping_type: :element,
             cdata: mapping_rule.cdata,
             mixed_content: mapping_rule.mixed_content?,
-            raw: attr.raw?,
+            raw: resolve_raw_mode(mapping_rule, attr),
             render_default: mapping_rule.render_default,
             value_map: value_map,
             custom_methods: custom_methods_value,

data/spec/lutaml/jsonld/transform_spec.rb

@@ -492,7 +492,9 @@ RSpec.describe Lutaml::JsonLd::Transform do
         ],
       )
       parsed = JSON.parse(parent.to_jsonld)
-      parent_resource = parsed["@graph"].find { |r| r["@type"] == "skos:Collection" }
+      parent_resource = parsed["@graph"].find do |r|
+        r["@type"] == "skos:Collection"
+      end
       expect(parent_resource["member"]).to eq([
                                                 { "@id" => "http://example.org/item/a" },
                                                 { "@id" => "http://example.org/item/b" },

data/spec/lutaml/model/mixed_content_spec.rb

@@ -1111,19 +1111,22 @@ RSpec.describe "MixedContent" do
         expect(enum).to be_a(Enumerator)
       end
 
-      it "skips whitespace-only text nodes" do
+      it "yields whitespace text nodes in mixed content" do
         parsed = MixedContentSpec::RootMixedContent.from_xml(xml)
 
         results = []
         parsed.each_mixed_content do |node|
-          results << node if node.is_a?(String) && node.strip.empty?
+          results << node if node.is_a?(String)
         end
 
-        expect(results).to eq([])
+        expect(results).not_to be_empty
+        text_joined = results.join
+        expect(text_joined).to include("Hello")
+        expect(text_joined).to include("and")
+        expect(text_joined).to include("!")
       end
 
       context "with ordered-only content (no mixed)" do
-        # Test that ordered content (elements only, no text) works
         let(:xml) do
           <<~XML
             <RootMixedContentNested id="outer">
@@ -1134,15 +1137,17 @@ RSpec.describe "MixedContent" do
           XML
         end
 
-        it "yields element objects in document order" do
+        it "yields element values in document order" do
           parsed = MixedContentSpec::RootMixedContentNested.from_xml(xml)
 
           results = []
           parsed.content.each_mixed_content { |node| results << node }
 
-          # Should yield element objects in order (bold, italic strings)
+          # RootMixedContent has mixed_content, so whitespace text nodes
+          # ARE yielded alongside element values
           string_results = results.grep(String)
-          expect(string_results.length).to eq(2)
+          expect(string_results).to include("first")
+          expect(string_results).to include("second")
         end
       end
 
@@ -1152,6 +1157,42 @@ RSpec.describe "MixedContent" do
           expect(parsed.each_mixed_content.to_a).to eq([])
         end
       end
+
+      context "with ordered-only model (no mixed_content)" do
+        before do
+          stub_const("OrderedOnlyContainer", Class.new(Lutaml::Model::Serializable) do
+            attribute :items, :string, collection: true
+
+            xml do
+              element "container"
+              ordered
+              map_element "item", to: :items
+            end
+          end)
+        end
+
+        it "skips whitespace-only text nodes between elements" do
+          xml = <<~XML
+            <container>
+              <item>first</item>
+              <item>second</item>
+            </container>
+          XML
+
+          parsed = OrderedOnlyContainer.from_xml(xml)
+          results = []
+          parsed.each_mixed_content { |node| results << node }
+
+          # Ordered-only: whitespace between elements is formatting noise, not content
+          whitespace_only = results.select do |n|
+            n.is_a?(String) && n.strip.empty?
+          end
+          expect(whitespace_only).to eq([])
+
+          string_results = results.grep(String)
+          expect(string_results).to eq(%w[first second])
+        end
+      end
     end
 
     # Issue #630: Mutation after deserialization should update serialization output