lutaml-model 0.8.14 → 0.8.16

data/docs/_guides/xml-mapping.adoc

@@ -1097,42 +1097,184 @@ end
 ====
 
 
-[[xml-map-all]]
-==== Mapping entire XML element into an attribute
 
-The `map_all` tag in XML mapping captures and maps all content within an XML
-element into a single attribute in the target Ruby object.
+[[xml-raw-element]]
+==== Capturing raw XML content
 
-The use case for `map_all` is to tell Lutaml::Model to not parse the content of
-the XML element at all, and instead handle it as an XML string.
+Lutaml::Model provides several mechanisms for capturing XML content as raw strings.
+Use these when you need to embed foreign XML vocabularies (SVG, MathML, XSL-FO) or
+preserve markup that your model doesn't need to parse.
 
-NOTE: The corresponding method for key-value formats is at <<key-value-map-all>>.
+===== `raw: :element` on `map_element` -- full element capture (recommended)
 
-WARNING: Notice that usage of mapping all will lead to incompatibility between
-serialization formats, i.e. the raw string content will not be portable as
-objects are across different formats.
+The `raw: :element` option captures a specific mapped element as a complete XML
+string, including its opening tag, attributes, children, and closing tag.
+This provides **lossless round-trip** fidelity -- the captured string is
+self-contained and serialized verbatim.
 
-This is useful in the case where the content of an XML element is not to be
-handled by a Lutaml::Model::Serializable object.
+.Syntax
+[source,ruby]
+----
+xml do
+  map_element "svg", to: :svg_data, raw: :element
+end
+----
 
-This feature is commonly used with custom methods or a custom model object to
-handle the content.
+.Capturing an SVG element as raw XML
+[example]
+====
+[source,ruby]
+----
+class SvgContainer < Lutaml::Model::Serializable
+  attribute :name, :string
+  attribute :svg_data, :string
 
-This includes:
+  xml do
+    element "container"
+    map_element "name", to: :name
+    map_element "svg", to: :svg_data, raw: :element
+  end
+end
+----
 
-* nested tags
-* attributes
-* text nodes
+[source,xml]
+----
+<container>
+  <name>diagram</name>
+  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
+    <rect x="0" y="0" width="100" height="100" fill="red"/>
+  </svg>
+</container>
+----
 
-The `map_all` tag is **exclusive** and cannot be combined with other mappings
-(`map_element`, `map_content`) except for `map_attribute` for the same element,
-ensuring it captures the entire inner XML content.
+[source,ruby]
+----
+> doc = SvgContainer.from_xml(xml)
+> doc.name
+# => "diagram"
+> doc.svg_data
+# => "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 100 100\">\n  <rect x=\"0\" y=\"0\" width=\"100\" height=\"100\" fill=\"red\"/>\n</svg>"
+----
 
-NOTE: An error is raised if `map_all` is defined alongside any other mapping in
-the same XML mapping context.
+The captured string round-trips correctly -- serializing the model back to XML
+outputs the raw element verbatim without escaping or wrapping.
 
-Syntax:
+`raw: :element` also works with collection attributes:
 
+[source,ruby]
+----
+class MultiFragment < Lutaml::Model::Serializable
+  attribute :fragments, :string, collection: true
+
+  xml do
+    element "container"
+    map_element "fragment", to: :fragments, raw: :element
+  end
+end
+----
+====
+
+===== `raw: :content` on `map_element` -- inner content capture
+
+The `raw: :content` option captures only the *inner XML* of the matched element,
+without the wrapper tags. The wrapper element is reconstructed from the mapping rule
+during serialization.
+
+.Syntax
+[source,ruby]
+----
+xml do
+  map_element "street", to: :street, raw: :content
+end
+----
+
+.Capturing inner XML content
+[example]
+====
+[source,ruby]
+----
+class Address < Lutaml::Model::Serializable
+  attribute :street, :string
+
+  xml do
+    element "address"
+    map_element "street", to: :street, raw: :content
+  end
+end
+----
+
+[source,xml]
+----
+<address><street><b>123</b> Main St</street></address>
+----
+
+[source,ruby]
+----
+> doc = Address.from_xml(xml)
+> doc.street
+# => "<b>123</b> Main St"
+----
+====
+
+NOTE: `raw: :content` is **lossy** -- namespace prefixes declared on the wrapper
+element are not captured. For lossless capture, use `raw: :element` instead.
+
+===== Namespace behavior
+
+Both `raw: :element` and `raw: :content` match elements by local name regardless
+of namespace or prefix:
+
+* Elements with no namespace (`<svg>`)
+* Elements with an `xmlns` declaration on themselves (`<svg xmlns="...">`)
+* Elements inheriting a default namespace from a parent
+* Elements with an explicit namespace prefix (`<ns:svg>`)
+
+This is intentional -- raw capture is designed to handle foreign XML vocabularies
+without needing model classes for them.
+
+===== Round-trip fidelity comparison
+
+| Aspect | `raw: :element` | `raw: :content` |
+|--------|----------------|-----------------|
+| Element name | Preserved (in string) | Reconstructed from rule |
+| Element attributes | Preserved (in string) | Lost unless separately mapped |
+| Inner content | Preserved (in string) | Preserved (in string) |
+| Namespace prefixes | Safe (declared in string) | May break if declared on wrapper |
+| Fidelity | **Lossless** | **Lossy** |
+
+===== Wrapper model pattern for attribute extraction
+
+Raw capture stores the element as a string. If you need to inspect or modify
+attributes on the captured element, use a wrapper model with `map_all`:
+
+[source,ruby]
+----
+class SvgInner < Lutaml::Model::Serializable
+  attribute :raw, :string
+
+  xml do
+    element "svg"
+    map_all to: :raw
+  end
+end
+
+class Container < Lutaml::Model::Serializable
+  attribute :svg_data, SvgInner
+
+  xml do
+    element "container"
+    map_element "svg", to: :svg_data
+  end
+end
+----
+
+===== `map_all` -- root inner XML capture
+
+The `map_all` directive captures the entire inner XML of the root element into
+a single attribute. It is **exclusive** -- it cannot be combined with other
+`map_element` or `map_content` mappings (only `map_attribute` is allowed).
+
+.Syntax
 [source,ruby]
 ----
 xml do
@@ -1167,6 +1309,18 @@ end
 ----
 ====
 
+===== Deprecated: `attribute :x, :string, raw: true`
+
+[WARNING]
+====
+`attribute :name, :string, raw: true` is deprecated. Use
+`map_element "name", to: :name, raw: :content` instead.
+====
+
+This legacy syntax captures the inner XML of the matched element.
+It is equivalent to `raw: :content` on the mapping. Existing code continues
+to work but emits a deprecation warning.
+
 
 ==== Mapping CDATA nodes
 

data/docs/_pages/importable_models.adoc

@@ -546,7 +546,13 @@ the current value is the same as the default value.
 
 
 
-=== Attribute as raw string
+=== Attribute as raw string (deprecated)
+
+[WARNING]
+====
+`attribute :name, :string, raw: true` is deprecated.
+Use `map_element "name", to: :name, raw: :content` instead.
+====
 
 An attribute can be set to read the value as raw string for XML, by using the `raw: true` option.
 

data/lib/lutaml/jsonld/transform.rb

@@ -45,6 +45,12 @@ module Lutaml
         build_instance(attrs, options)
       end
 
+      protected
+
+      def additional_resource_data(_instance, _mapping)
+        {}
+      end
+
       private
 
       def extract_mapping(options)
@@ -52,28 +58,32 @@ module Lutaml
       end
 
       def build_graph_document(mapping, instance)
-        context = build_merged_context(mapping, instance)
+        context = build_merged_context_recursive(mapping, instance)
+        graph = collect_resources(mapping, instance)
+
+        { "@context" => context, "@graph" => graph }
+      end
+
+      def collect_resources(mapping, instance)
         graph = []
 
-        if mapping.rdf_subject
-          resource = build_resource_data(mapping, instance)
-          graph << resource unless resource.empty?
-        end
+        resource = build_resource_data(mapping, instance)
+        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)
             next unless member_mapping
 
-            resource = build_resource_data(member_mapping, member)
-            graph << resource unless resource.empty?
+            child_resources = collect_resources(member_mapping, member)
+            graph.concat(child_resources)
           end
         end
 
-        { "@context" => context, "@graph" => graph }
+        graph
       end
 
-      def build_merged_context(mapping, instance)
+      def build_merged_context_recursive(mapping, instance)
         context_hash = build_context_from_mapping(mapping).to_hash
 
         mapping.rdf_members.each do |member_rule|
@@ -82,6 +92,9 @@ module Lutaml
             next unless member_mapping
 
             context_hash.merge!(build_context_from_mapping(member_mapping).to_hash)
+
+            child_ctx = build_merged_context_recursive(member_mapping, member)
+            context_hash.merge!(child_ctx)
           end
         end
 
@@ -100,9 +113,14 @@ module Lutaml
         mapping.rdf_members.each do |member_rule|
           next unless member_rule.linked?
 
-          context.term(member_rule.predicate_name.to_s,
-                       id: member_rule.linked_predicate_uri,
-                       type: "@id")
+          predicate_uri = if member_rule.predicate_name
+                            member_rule.linked_predicate_uri
+                          end
+          if predicate_uri
+            context.term(member_rule.predicate_name.to_s,
+                         id: predicate_uri,
+                         type: "@id")
+          end
         end
 
         context
@@ -151,9 +169,12 @@ module Lutaml
           member_refs = collect_member_references(instance, member_rule)
           next if member_refs.empty?
 
-          result[member_rule.predicate_name.to_s] = member_refs
+          key = jsonld_member_key(member_rule)
+          result[key] = member_refs
         end
 
+        result.merge!(additional_resource_data(instance, mapping))
+
         result
       end
 
@@ -168,6 +189,16 @@ module Lutaml
         refs
       end
 
+      def jsonld_member_key(member_rule)
+        if member_rule.predicate_name
+          member_rule.predicate_name.to_s
+        elsif member_rule.link.is_a?(String)
+          member_rule.link.split(":").last
+        else
+          member_rule.attr_name.to_s
+        end
+      end
+
       def serialize_value(value, rule)
         case rule.kind
         when :uri_reference then serialize_uri_reference(value)

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

@@ -54,6 +54,15 @@ module Lutaml
                           value.to_liquid
                         end
                       end
+
+                      def liquid_method_missing(method)
+                        if @object.is_a?(::Lutaml::Model::Liquid::IndexedAccess)
+                          result = @object.liquid_fetch(method)
+                          result.nil? ? super : liquefy_value(result)
+                        else
+                          super
+                        end
+                      end
                     end)
         end
 

data/lib/lutaml/model/liquid/indexed_access.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Model
+    module Liquid
+      # Module for Lutaml::Model objects that support bracket-based
+      # lookup in Liquid templates (e.g., collections with index or key access).
+      #
+      # Include this module in any Serializable subclass that supports
+      # +self[key]+ so that its auto-generated Liquid drop can delegate
+      # +drop[key]+ through to the underlying object.
+      #
+      # Example:
+      #   class Glossarist::Collections::LocalizationCollection
+      #     include Lutaml::Model::Liquid::IndexedAccess
+      #     # ...
+      #   end
+      #
+      #   drop['eng']  #=> calls drop.liquid_method_missing('eng')
+      #               #=> calls @object.liquid_fetch('eng')
+      #               #=> calls @object['eng']
+      #               #=> returns the localized concept drop
+      module IndexedAccess
+        # Called by the auto-generated Liquid drop via +liquid_method_missing+.
+        # Delegates to +self[key]+ by default. Override in specific classes
+        # for custom lookup behavior.
+        def liquid_fetch(key)
+          self[key]
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/model/liquid.rb

@@ -3,6 +3,7 @@
 module Lutaml
   module Model
     module Liquid
+      autoload :IndexedAccess, "#{__dir__}/liquid/indexed_access"
       autoload :Mapping, "#{__dir__}/liquid/mapping"
     end
   end

data/lib/lutaml/model/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Model
-    VERSION = "0.8.14"
+    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/rdf/mapping.rb

@@ -27,6 +27,14 @@ module Lutaml
         @rdf_type = Array(value)
       end
 
+      def types(*values)
+        @rdf_type = values.flatten
+      end
+
+      def has_types_or_predicates?
+        @rdf_type.any? || @rdf_predicates.any?
+      end
+
       def predicate(name, namespace:, to:, lang_tagged: false,
                     uri_reference: false)
         @rdf_predicates << Lutaml::Rdf::MappingRule.new(
@@ -38,11 +46,12 @@ module Lutaml
         )
       end
 
-      def members(attr_name, predicate_name: nil, namespace: nil)
+      def members(attr_name, predicate_name: nil, namespace: nil, link: nil)
         @rdf_members << Lutaml::Rdf::MemberRule.new(
           attr_name,
           predicate_name: predicate_name,
           namespace: namespace,
+          link: link,
         )
       end
 

data/lib/lutaml/rdf/member_rule.rb

@@ -3,28 +3,53 @@
 module Lutaml
   module Rdf
     class MemberRule
-      attr_reader :attr_name, :predicate_name, :namespace
+      attr_reader :attr_name, :predicate_name, :namespace, :link
 
-      def initialize(attr_name, predicate_name: nil, namespace: nil)
+      def initialize(attr_name, predicate_name: nil, namespace: nil, link: nil)
         if predicate_name && !namespace
           raise ArgumentError,
                 "namespace is required when predicate_name is provided"
         end
 
+        if predicate_name && link
+          raise ArgumentError,
+                "predicate_name and link are mutually exclusive"
+        end
+
         @attr_name = attr_name.to_sym
         @predicate_name = predicate_name
         @namespace = namespace
+        @link = link
       end
 
       def linked?
-        !!@predicate_name
+        !!(@predicate_name || @link)
       end
 
       def linked_predicate_uri
-        return nil unless linked?
+        return nil unless @predicate_name
 
         @namespace[@predicate_name]
       end
+
+      def link_predicate_for(member, resolver)
+        return nil unless @link
+
+        case @link
+        when String
+          resolver.call(@link)
+        when Proc
+          resolver.call(@link.call(member))
+        end
+      end
+
+      def resolve_link_uri(member, resolver)
+        if @predicate_name
+          linked_predicate_uri
+        elsif @link
+          link_predicate_for(member, resolver)
+        end
+      end
     end
   end
 end