lutaml-model 0.8.15 → 0.8.17

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8d6ce7467101e1a845bcd0bfb98b0e878d55d440065a12481576a8aa5c050c98
-  data.tar.gz: e534138d7ca3848eaa33681e286584ea385386734617f37c5fa89a7c3f752f79
+  metadata.gz: 8296b9832eb080f64ba1344b7fa929b179fedc1c4265d9743d6636cd408720f6
+  data.tar.gz: 533255e9702cd82fc93cacc78bf88fb90dba17b8543b5ecf22bb223eaacfa9a1
 SHA512:
-  metadata.gz: 8e872c659c1e147598fffe00ea015ed07dbd16b795c254f4aed6df30d2c6f2c91ab51740f5112b93e67d113d5b7d7f4edef755a2d6fa848053ab885533ac1336
-  data.tar.gz: 22a484ca450a64ff4b3b0d426f1982e0e17d90eb422534158cf02ca65b96cc5293f401fec9cbbaa39a0ccaa06c0ef987b9a7f0f02312bc6fd55233b1666191ad
+  metadata.gz: 936d9c1ff8eefb9f2b861d3c29c4d032462f9f6f5624bb2d669ebfc77d49ade62ce2859f171052f3b473a00d0a83a88955ee1c4cbd47f5bbddfe2a625e62d1f8
+  data.tar.gz: 79f9f3b4cea4bff89c06df360e6a316507f62af37f2a277cd10dc54b38f72c374cadba6b4b995234e4c67f82dbaa71ecf751d3ec8ed280bf5fe0e64dca42534f

data/.github/workflows/release.yml

@@ -23,9 +23,6 @@ jobs:
     uses: metanorma/ci/.github/workflows/rubygems-release.yml@main
     with:
       next_version: ${{ github.event.inputs.next_version }}
-      post_install: |
-        git status
-        cat .bundle/config
     secrets:
       rubygems-api-key: ${{ secrets.LUTAML_CI_RUBYGEMS_API_KEY }}
       pat_token: ${{ secrets.LUTAML_CI_PAT_TOKEN }}

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-08 11:45:37 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,39 +11,45 @@ Gemspec/RequiredRubyVersion:
   Exclude:
     - 'lutaml-model.gemspec'
 
-# Offense count: 2
+# Offense count: 1
 # 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'
+    - 'lib/lutaml/rdf/linked_data_transform.rb'
 
-# Offense count: 1
+# Offense count: 2
 # This cop supports safe autocorrection (--autocorrect).
-Layout/ClosingParenthesisIndentation:
+# Configuration parameters: EnforcedStyleAlignWith.
+# SupportedStylesAlignWith: either, start_of_block, start_of_line
+Layout/BlockAlignment:
   Exclude:
-    - 'spec/lutaml/model/opal_smoke_spec.rb'
+    - 'spec/lutaml/model/choice_restrict_spec.rb'
 
-# Offense count: 1
+# Offense count: 2
 # 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:
+Layout/BlockEndNewline:
   Exclude:
-    - 'spec/lutaml/model/opal_smoke_spec.rb'
+    - 'spec/lutaml/model/choice_restrict_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:
+# Configuration parameters: EnforcedStyle, IndentationWidth.
+# SupportedStyles: special_inside_parentheses, consistent, align_brackets
+Layout/FirstArrayElementIndentation:
+  Exclude:
+    - 'spec/lutaml/model/choice_restrict_spec.rb'
+
+# Offense count: 4
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: Width, EnforcedStyleAlignWith, AllowedPatterns.
+# SupportedStylesAlignWith: start_of_line, relative_to_receiver
+Layout/IndentationWidth:
   Exclude:
-    - 'spec/lutaml/model/opal_smoke_spec.rb'
+    - 'spec/lutaml/model/choice_restrict_spec.rb'
 
-# Offense count: 3022
+# Offense count: 3071
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, AllowRBSInlineAnnotation, AllowCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https
@@ -54,16 +60,16 @@ Layout/LineLength:
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyle.
 # SupportedStyles: symmetrical, new_line, same_line
-Layout/MultilineMethodCallBraceLayout:
+Layout/MultilineArrayBraceLayout:
   Exclude:
-    - 'spec/lutaml/model/opal_smoke_spec.rb'
+    - 'spec/lutaml/model/choice_restrict_spec.rb'
 
 # Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: AllowInHeredoc.
 Layout/TrailingWhitespace:
   Exclude:
-    - 'spec/lutaml/model/opal_smoke_spec.rb'
+    - 'lib/lutaml/rdf/linked_data_transform.rb'
 
 # Offense count: 21
 # Configuration parameters: AllowedMethods.
@@ -76,21 +82,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 +156,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 +177,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 +190,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 +285,7 @@ RSpec/BeforeAfterAll:
 RSpec/ContextWording:
   Enabled: false
 
-# Offense count: 98
+# Offense count: 102
 # Configuration parameters: IgnoredMetadata.
 RSpec/DescribeClass:
   Enabled: false
@@ -302,7 +296,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: 1343
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
   Max: 68
@@ -377,7 +371,7 @@ RSpec/MultipleDescribes:
     - 'spec/lutaml/xml/namespace_resolution_strategy_spec.rb'
     - 'spec/lutaml/xml/xml_space_type_spec.rb'
 
-# Offense count: 1515
+# Offense count: 1576
 RSpec/MultipleExpectations:
   Max: 21
 
@@ -425,7 +419,7 @@ RSpec/RepeatedExampleGroupDescription:
   Exclude:
     - 'spec/lutaml/model/mixed_content_spec.rb'
 
-# Offense count: 40
+# Offense count: 39
 # Configuration parameters: CustomTransform, IgnoreMethods, IgnoreMetadata, InflectorPath, EnforcedInflector.
 # SupportedInflectors: default, active_support
 RSpec/SpecFilePathFormat:
@@ -451,6 +445,17 @@ Security/MarshalLoad:
   Exclude:
     - 'scripts-xmi-profile/profile_xmi.rb'
 
+# Offense count: 3
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, ProceduralMethods, FunctionalMethods, AllowedMethods, AllowedPatterns, AllowBracesOnProceduralOneLiners, BracesRequiredMethods.
+# SupportedStyles: line_count_based, semantic, braces_for_chaining, always_braces
+# ProceduralMethods: benchmark, bm, bmbm, create, each_with_object, measure, new, realtime, tap, with_object
+# FunctionalMethods: let, let!, subject, watch
+# AllowedMethods: lambda, proc, it
+Style/BlockDelimiters:
+  Exclude:
+    - 'spec/lutaml/model/choice_restrict_spec.rb'
+
 # Offense count: 2
 # This cop supports unsafe autocorrection (--autocorrect-all).
 # Configuration parameters: AllowedMethods, AllowedPatterns.
@@ -543,11 +548,3 @@ Style/StringConcatenation:
     - 'lib/lutaml/model/schema/xml_compiler/complex_type.rb'
     - 'lib/lutaml/model/schema/xml_compiler/simple_type.rb'
     - 'lib/lutaml/model/schema/xml_compiler/xml_namespace_class.rb'
-
-# Offense count: 1
-# 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'

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/namespace-semantics.adoc

@@ -13,6 +13,8 @@ parent: XML namespaces
 Lutaml::Model implements W3C XML Namespace specification with a focus on
 **attribute-based namespace resolution**. Each XML element's namespace is
 determined by its attribute's type and parent context, following clear and
+
+NOTE: This document covers the *core namespace resolution principles*. For the `form:` override option, the full qualification precedence ladder, and `form:` behavior on nested `Serializable` children, see the companion guide: link:../xml-namespace-qualification[XML Namespace Qualification and Prefix Control].
 consistent rules.
 
 This document explains the core namespace principles that govern how namespaces