lutaml-model 0.8.15 → 0.8.17

data/lib/lutaml/{jsonld/transform.rb → rdf/linked_data_transform.rb}

@@ -1,34 +1,31 @@
 # frozen_string_literal: true
 
-require "json"
-
 module Lutaml
-  module JsonLd
-    class Transform < Lutaml::Rdf::Transform
-      def model_to_data(instance, _format, options = {})
-        mapping = extract_mapping(options)
+  module Rdf
+    class LinkedDataTransform < Lutaml::Rdf::Transform
+      def model_to_data(instance, format, options = {})
+        mapping = extract_mapping(format, options)
         return {} unless mapping
 
         if mapping.rdf_members.any?
-          build_graph_document(mapping, instance)
+          build_graph_document(mapping, instance, format)
         else
-          build_resource_object(mapping, instance)
+          build_resource_object(mapping, instance, format)
         end
       end
 
-      def data_to_model(data, _format, options = {})
-        mapping = extract_mapping(options)
+      def data_to_model(data, format, options = {})
+        mapping = extract_mapping(format, options)
         return model_class.new unless mapping
 
-        hash = data.is_a?(String) ? JSON.parse(data) : data
+        hash = data.is_a?(Hash) ? data : {}
 
         if hash.key?("@graph") && hash["@graph"].is_a?(Array) && !hash["@graph"].empty?
-          graph_data = hash["@graph"]
-          first = graph_data.first
+          first = hash["@graph"].first
           hash = first.is_a?(Hash) ? first : {}
         end
 
-        hash = strip_jsonld_keywords(hash)
+        hash = strip_linked_data_keywords(hash)
 
         attrs = {}
         mapping.rdf_predicates.each do |rule|
@@ -53,29 +50,29 @@ module Lutaml
 
       private
 
-      def extract_mapping(options)
-        options[:mappings] || mappings_for(:jsonld, lutaml_register)
+      def extract_mapping(format, options)
+        options[:mappings] || mappings_for(format, lutaml_register)
       end
 
-      def build_graph_document(mapping, instance)
-        context = build_merged_context_recursive(mapping, instance)
-        graph = collect_resources(mapping, instance)
+      def build_graph_document(mapping, instance, format)
+        context = build_merged_context_recursive(mapping, instance, format)
+        graph = collect_resources(mapping, instance, format)
 
         { "@context" => context, "@graph" => graph }
       end
 
-      def collect_resources(mapping, instance)
+      def collect_resources(mapping, instance, format)
         graph = []
 
-        resource = build_resource_data(mapping, instance)
+        resource = build_resource_data(mapping, instance, format)
         graph << resource unless resource.empty?
 
         mapping.rdf_members.each do |member_rule|
           each_member(instance, member_rule) do |member|
-            member_mapping = member_mapping_for(member, :jsonld)
+            member_mapping = member_mapping_for(member, format)
             next unless member_mapping
 
-            child_resources = collect_resources(member_mapping, member)
+            child_resources = collect_resources(member_mapping, member, format)
             graph.concat(child_resources)
           end
         end
@@ -83,17 +80,18 @@ module Lutaml
         graph
       end
 
-      def build_merged_context_recursive(mapping, instance)
+      def build_merged_context_recursive(mapping, instance, format)
         context_hash = build_context_from_mapping(mapping).to_hash
 
         mapping.rdf_members.each do |member_rule|
           each_member(instance, member_rule) do |member|
-            member_mapping = member_mapping_for(member, :jsonld)
+            member_mapping = member_mapping_for(member, format)
             next unless member_mapping
 
             context_hash.merge!(build_context_from_mapping(member_mapping).to_hash)
 
-            child_ctx = build_merged_context_recursive(member_mapping, member)
+            child_ctx = build_merged_context_recursive(member_mapping, member,
+                                                       format)
             context_hash.merge!(child_ctx)
           end
         end
@@ -134,13 +132,13 @@ module Lutaml
         end
       end
 
-      def build_resource_object(mapping, instance)
+      def build_resource_object(mapping, instance, format)
         context = build_context_from_mapping(mapping).to_hash
-        data = build_resource_data(mapping, instance)
+        data = build_resource_data(mapping, instance, format)
         { "@context" => context }.merge(data)
       end
 
-      def build_resource_data(mapping, instance)
+      def build_resource_data(mapping, instance, format)
         result = {}
 
         if mapping.rdf_type.any?
@@ -166,10 +164,10 @@ module Lutaml
         mapping.rdf_members.each do |member_rule|
           next unless member_rule.linked?
 
-          member_refs = collect_member_references(instance, member_rule)
+          member_refs = collect_member_references(instance, member_rule, format)
           next if member_refs.empty?
 
-          key = jsonld_member_key(member_rule)
+          key = member_key(member_rule)
           result[key] = member_refs
         end
 
@@ -178,10 +176,10 @@ module Lutaml
         result
       end
 
-      def collect_member_references(instance, member_rule)
+      def collect_member_references(instance, member_rule, format)
         refs = []
         each_member(instance, member_rule) do |member|
-          member_mapping = member_mapping_for(member, :jsonld)
+          member_mapping = member_mapping_for(member, format)
           next unless member_mapping
 
           refs << { "@id" => resolve_subject_uri(member_mapping, member) }
@@ -189,7 +187,7 @@ module Lutaml
         refs
       end
 
-      def jsonld_member_key(member_rule)
+      def member_key(member_rule)
         if member_rule.predicate_name
           member_rule.predicate_name.to_s
         elsif member_rule.link.is_a?(String)
@@ -241,7 +239,7 @@ module Lutaml
         end
       end
 
-      def strip_jsonld_keywords(data)
+      def strip_linked_data_keywords(data)
         return data unless data.is_a?(Hash)
 
         data.reject { |key, _| key.start_with?("@") }

data/lib/lutaml/{jsonld → rdf}/term_definition.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Lutaml
-  module JsonLd
+  module Rdf
     class TermDefinition
       attr_reader :name, :id, :type, :container, :language, :reverse
 

data/lib/lutaml/rdf.rb

@@ -15,5 +15,8 @@ module Lutaml
     autoload :MemberRule, "#{__dir__}/rdf/member_rule"
     autoload :Namespaces, "#{__dir__}/rdf/namespaces"
     autoload :Transform, "#{__dir__}/rdf/transform"
+    autoload :Context, "#{__dir__}/rdf/context"
+    autoload :TermDefinition, "#{__dir__}/rdf/term_definition"
+    autoload :LinkedDataTransform, "#{__dir__}/rdf/linked_data_transform"
   end
 end

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/adapter_element.rb

@@ -129,7 +129,7 @@ module Lutaml
           next if attr_is_namespace?(attr)
 
           ns_prefix = attr.namespace&.prefix
-          ns_prefix = nil if ns_prefix&.empty?
+          ns_prefix = nil if ns_prefix && ns_prefix.empty?
 
           attr_name = ns_prefix ? "#{ns_prefix}:#{attr.name}" : attr.name
 
@@ -150,7 +150,7 @@ module Lutaml
           next if attr_is_namespace?(attr)
 
           ns_prefix = attr.namespace&.prefix
-          ns_prefix = nil if ns_prefix&.empty?
+          ns_prefix = nil if ns_prefix && ns_prefix.empty?
 
           attr_name = ns_prefix ? "#{ns_prefix}:#{attr.name}" : attr.name
           order << attr_name

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
@@ -253,18 +251,6 @@ child_transformation)
             value.xml_namespace_prefix = ns_prefix
           end
 
-          # Also set @__xml_namespace_prefix on the XmlElement for doubly-defined case.
-          # This is read by NamespaceCollector to set NamespaceUsage.used_prefix.
-          # For doubly-defined: parent has no ns, child's ns_prefix is from @__xml_ns_prefixes
-          # (not from parent's @__xml_namespace_prefix).
-          # For mixed content: parent's XmlElement already has @__xml_namespace_prefix set.
-          if parent_ns_class.nil? && ns_prefix && !ns_prefix.empty? && !child_ns_class
-            # Doubly-defined case: parent has no ns, child has ns class.
-            # Set on XmlElement so NamespaceCollector reads it.
-            # The value will be set on the model instance above (via @__xml_namespace_prefix)
-            # and we'll set it on XmlElement too so collection phase picks it up.
-          end
-
           child_element = child_transformation.transform(value, child_options)
 
           # Dual-namespace support: when the child model was deserialized from an element
@@ -306,15 +292,10 @@ child_transformation)
             child_element.name = rule.serialized_name
           end
 
-          # W3C elementFormDefault: unqualified override
-          # When parent's namespace has element_form_default :unqualified and the child's
-          # namespace is the same as the parent's, override to blank namespace.
-          # This ensures local elements are not namespace-qualified per W3C spec.
-          if parent_element_form_default == :unqualified &&
-              parent_ns_class &&
-              child_element.namespace_class == parent_ns_class
-            child_element.namespace_class = nil
-          end
+          propagate_form(child_element, rule)
+          apply_unqualified_form_default(
+            child_element, rule, parent_ns_class, parent_element_form_default
+          )
 
           child_element
         end
@@ -358,7 +339,7 @@ child_transformation)
             element.xml_namespace_prefix = model_ns_prefix
           end
 
-          element.form = rule.form if rule.form
+          propagate_form(element, rule)
           text = serialize_value(value, rule, rule.attribute_type, nil)
           element.text_content = text if text
           element
@@ -492,7 +473,7 @@ register_id)
             element.xml_namespace_prefix = ns_prefix
           end
 
-          element.form = rule.form if rule.form
+          propagate_form(element, rule)
 
           # Handle Hash type - expand hash into child elements
           if value.is_a?(::Hash) && rule.attribute_type == Lutaml::Model::Type::Hash
@@ -525,6 +506,38 @@ register_id)
           end
         end
 
+        # Copy the rule's form option onto the produced element so downstream
+        # rules (ElementFormOptionRule) can read it. Without this propagation
+        # the form option would be lost on transformed/fallback/simple paths.
+        #
+        # @param element [::Lutaml::Xml::DataModel::XmlElement] The element to update
+        # @param rule [CompiledRule] The rule carrying the form option
+        def propagate_form(element, rule)
+          element.form = rule.form if rule.form_set?
+        end
+
+        # W3C elementFormDefault: unqualified override.
+        #
+        # When the parent schema declares elementFormDefault="unqualified" and
+        # a locally-declared child lives in the same namespace as the parent,
+        # the child MUST NOT be namespace-qualified (XSD spec). An explicit
+        # form: :qualified on the rule is the user's per-element opt-out and
+        # takes precedence over the schema default.
+        #
+        # @param element [::Lutaml::Xml::DataModel::XmlElement] The element to update
+        # @param rule [CompiledRule] The rule (checked for explicit form override)
+        # @param parent_ns_class [Class, nil] Parent's namespace class
+        # @param parent_form_default [Symbol, nil] Parent's element_form_default
+        def apply_unqualified_form_default(element, rule, parent_ns_class,
+                                           parent_form_default)
+          return if rule.form == :qualified
+          return if parent_form_default != :unqualified
+          return unless parent_ns_class
+          return unless element.namespace_class == parent_ns_class
+
+          element.namespace_class = nil
+        end
+
         # Apply nil marker to element if needed
         #
         # @param element [XmlElement] The element

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