lutaml-model 0.8.15 → 0.8.16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8d6ce7467101e1a845bcd0bfb98b0e878d55d440065a12481576a8aa5c050c98
-  data.tar.gz: e534138d7ca3848eaa33681e286584ea385386734617f37c5fa89a7c3f752f79
+  metadata.gz: 0b419ac1cce55a5e56ca59dd217042047801d2420751f89ce0b875558e517f44
+  data.tar.gz: ed7c6b7dcd749c35d7fa434d2adf4b9e036c7329afd80c2420ef75f57f65895f
 SHA512:
-  metadata.gz: 8e872c659c1e147598fffe00ea015ed07dbd16b795c254f4aed6df30d2c6f2c91ab51740f5112b93e67d113d5b7d7f4edef755a2d6fa848053ab885533ac1336
-  data.tar.gz: 22a484ca450a64ff4b3b0d426f1982e0e17d90eb422534158cf02ca65b96cc5293f401fec9cbbaa39a0ccaa06c0ef987b9a7f0f02312bc6fd55233b1666191ad
+  metadata.gz: c923ed6933f06ca678d4b76c19b46553f1196e0b30c0f202113a792619c91c0e6b3e3885963f4b910d101722d0cee22df8bf71c0c593fc7de4f0832d9062d87d
+  data.tar.gz: cfc1cc06ebeb1affa7875ecc522d8625147f70ed81aa6ae2feb2b4debd92f652ce2cf565f9984e52170e65559a75f23139c85762df5018545b60187cb5974744

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-05-27 05:02:01 UTC using RuboCop version 1.86.0.
+# on 2026-06-05 08:01:07 UTC using RuboCop version 1.87.0.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
@@ -11,60 +11,13 @@ Gemspec/RequiredRubyVersion:
   Exclude:
     - 'lutaml-model.gemspec'
 
-# Offense count: 2
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle, IndentationWidth.
-# SupportedStyles: with_first_argument, with_fixed_indentation
-Layout/ArgumentAlignment:
-  Exclude:
-    - 'spec/lutaml/model/opal_smoke_spec.rb'
-
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-Layout/ClosingParenthesisIndentation:
-  Exclude:
-    - 'spec/lutaml/model/opal_smoke_spec.rb'
-
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle, IndentationWidth.
-# SupportedStyles: consistent, consistent_relative_to_receiver, special_for_inner_method_call, special_for_inner_method_call_in_parentheses
-Layout/FirstArgumentIndentation:
-  Exclude:
-    - 'spec/lutaml/model/opal_smoke_spec.rb'
-
-# Offense count: 2
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AllowMultipleStyles, EnforcedHashRocketStyle, EnforcedColonStyle, EnforcedLastArgumentHashStyle.
-# SupportedHashRocketStyles: key, separator, table
-# SupportedColonStyles: key, separator, table
-# SupportedLastArgumentHashStyles: always_inspect, always_ignore, ignore_implicit, ignore_explicit
-Layout/HashAlignment:
-  Exclude:
-    - 'spec/lutaml/model/opal_smoke_spec.rb'
-
-# Offense count: 3022
+# Offense count: 3052
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, AllowRBSInlineAnnotation, AllowCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https
 Layout/LineLength:
   Enabled: false
 
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle.
-# SupportedStyles: symmetrical, new_line, same_line
-Layout/MultilineMethodCallBraceLayout:
-  Exclude:
-    - 'spec/lutaml/model/opal_smoke_spec.rb'
-
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AllowInHeredoc.
-Layout/TrailingWhitespace:
-  Exclude:
-    - 'spec/lutaml/model/opal_smoke_spec.rb'
-
 # Offense count: 21
 # Configuration parameters: AllowedMethods.
 # AllowedMethods: enums
@@ -76,21 +29,15 @@ Lint/ConstantDefinitionInBlock:
     - 'spec/lutaml/xml/type_namespace_prefix_spec.rb'
     - 'spec/lutaml/xml/xml_space_type_spec.rb'
 
-# Offense count: 36
+# Offense count: 35
 # Configuration parameters: IgnoreLiteralBranches, IgnoreConstantBranches, IgnoreDuplicateElseBranch.
 Lint/DuplicateBranch:
   Enabled: false
 
-# Offense count: 22
+# Offense count: 3
 Lint/DuplicateMethods:
   Exclude:
     - 'lib/lutaml/xml/mapping.rb'
-    - 'spec/lutaml/model/liquid_compatibility_spec.rb'
-    - 'spec/lutaml/xml/namespace_no_hoisting_spec.rb'
-    - 'spec/lutaml/xml/namespace_scope_declare_spec.rb'
-    - 'spec/lutaml/xml/namespace_scope_vcard_spec.rb'
-    - 'spec/lutaml/xml/prefix_control_spec.rb'
-    - 'spec/lutaml/xml/type_namespace_examples_spec.rb'
 
 # Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
@@ -156,18 +103,12 @@ Lint/UnusedMethodArgument:
     - 'lib/lutaml/xml/unqualified_inheritance_strategy.rb'
     - 'spec/support/xml/xsd/code_example_validator.rb'
 
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-Lint/UselessAssignment:
-  Exclude:
-    - 'spec/lutaml/xml/opal_xml_spec.rb'
-
 # Offense count: 1
 Lint/UselessConstantScoping:
   Exclude:
     - 'lib/lutaml/xml/mapping_rule.rb'
 
-# Offense count: 345
+# Offense count: 346
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Enabled: false
@@ -183,12 +124,12 @@ Metrics/BlockLength:
 Metrics/BlockNesting:
   Max: 6
 
-# Offense count: 308
+# Offense count: 307
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
   Enabled: false
 
-# Offense count: 553
+# Offense count: 554
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
   Max: 514
@@ -196,10 +137,10 @@ Metrics/MethodLength:
 # Offense count: 81
 # Configuration parameters: CountKeywordArgs.
 Metrics/ParameterLists:
-  Max: 24
   MaxOptionalParameters: 5
+  Max: 25
 
-# Offense count: 262
+# Offense count: 261
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/PerceivedComplexity:
   Enabled: false
@@ -291,7 +232,7 @@ RSpec/BeforeAfterAll:
 RSpec/ContextWording:
   Enabled: false
 
-# Offense count: 98
+# Offense count: 101
 # Configuration parameters: IgnoredMetadata.
 RSpec/DescribeClass:
   Enabled: false
@@ -302,7 +243,7 @@ RSpec/DescribeMethod:
     - 'spec/lutaml/xml/schema/xsd/schema_helper_methods_spec.rb'
     - 'spec/lutaml/xml/serializable_namespace_spec.rb'
 
-# Offense count: 1301
+# Offense count: 1328
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
   Max: 68
@@ -377,7 +318,7 @@ RSpec/MultipleDescribes:
     - 'spec/lutaml/xml/namespace_resolution_strategy_spec.rb'
     - 'spec/lutaml/xml/xml_space_type_spec.rb'
 
-# Offense count: 1515
+# Offense count: 1560
 RSpec/MultipleExpectations:
   Max: 21
 
@@ -544,10 +485,10 @@ Style/StringConcatenation:
     - 'lib/lutaml/model/schema/xml_compiler/simple_type.rb'
     - 'lib/lutaml/model/schema/xml_compiler/xml_namespace_class.rb'
 
-# Offense count: 1
+# Offense count: 3
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyleForMultiline.
 # SupportedStylesForMultiline: comma, consistent_comma, diff_comma, no_comma
 Style/TrailingCommaInArguments:
   Exclude:
-    - 'spec/lutaml/model/opal_smoke_spec.rb'
+    - 'spec/lutaml/model/raw_element_spec.rb'

data/README.adoc

@@ -3554,7 +3554,14 @@ 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.
+See <<xml-raw-element>> for the full raw XML capture documentation.
+====
 
 An attribute can be set to read the value as raw string for XML, by using the `raw: true` option.
 
@@ -7969,42 +7976,186 @@ 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.
+
+.Syntax
+[source,ruby]
+----
+xml do
+  map_element "svg", to: :svg_data, raw: :element
+end
+----
+
+.Capturing an SVG element as raw XML
+[example]
+====
+[source,ruby]
+----
+class SvgContainer < Lutaml::Model::Serializable
+  attribute :name, :string
+  attribute :svg_data, :string
+
+  xml do
+    element "container"
+    map_element "name", to: :name
+    map_element "svg", to: :svg_data, raw: :element
+  end
+end
+----
 
-This is useful in the case where the content of an XML element is not to be
-handled by a Lutaml::Model::Serializable object.
+[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>
+----
 
-This feature is commonly used with custom methods or a custom model object to
-handle the 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>"
+----
 
-This includes:
+The captured string round-trips correctly -- serializing the model back to XML
+outputs the raw element verbatim without escaping or wrapping.
 
-* nested tags
-* attributes
-* text nodes
+`raw: :element` also works with collection attributes:
 
-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]
+----
+class MultiFragment < Lutaml::Model::Serializable
+  attribute :fragments, :string, collection: true
 
-NOTE: An error is raised if `map_all` is defined alongside any other mapping in
-the same XML mapping context.
+  xml do
+    element "container"
+    map_element "fragment", to: :fragments, raw: :element
+  end
+end
+----
+====
 
-Syntax:
+===== `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).
+
+NOTE: The corresponding method for key-value formats is at <<key-value-map-all>>.
+
+.Syntax
 [source,ruby]
 ----
 xml do
@@ -8039,6 +8190,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/_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.