lutaml-model 0.8.15 → 0.8.17

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/_guides/xml-namespace-qualification.adoc

@@ -509,6 +509,148 @@ Parent.new(child: Child.new(value: "test")).to_xml(prefix: true)
 
 All three elements (`parent`, `child`, `value`) use the prefix because all are qualified via `element_form_default: :qualified`.
 
+=== Form Override on Serializable Children
+
+The `form:` option works on attributes of any type — including attributes whose value type is another `Serializable` model, not only simple types like `:string`. This matters when the parent's namespace declares `element_form_default :unqualified` (the W3C default) and you need a specific nested model element to be qualified anyway.
+
+.Worked example: form: :qualified on a Serializable child
+[example]
+====
+[source,ruby]
+----
+NS = Class.new(Lutaml::Model::XmlNamespace) do
+  uri "https://example.com/ns"
+  prefix_default "ex"
+  element_form_default :unqualified  # W3C default for local elements
+end
+
+class Child < Lutaml::Model::Serializable
+  attribute :label, :string
+  xml do
+    element "child"
+    namespace NS
+    map_element "label", to: :label
+  end
+end
+
+class Parent < Lutaml::Model::Serializable
+  attribute :child, Child
+  xml do
+    element "item"
+    namespace NS
+    map_element "child", to: :child, form: :qualified  # Force prefix
+  end
+end
+
+Parent.new(child: Child.new(label: "x")).to_xml
+----
+
+*Output*:
+[source,xml]
+----
+<item xmlns="https://example.com/ns" xmlns:ex="https://example.com/ns">
+  <ex:child>
+    <label>x</label>
+  </ex:child>
+</item>
+----
+
+The `ex:` prefix on `<child>` is forced by `form: :qualified`, overriding the parent's `:unqualified` schema default. The inner `<label>` remains unprefixed because the `Child` model's own mapping rule for `label` has no `form:` override — see the next section.
+====
+
+=== Form Scope: Per-Rule, Not Transitive
+
+`form:` is a per-mapping-rule override. It does **not** propagate transitively to grandchildren. Each level of the model tree applies its own rule against its own parent's `element_form_default`.
+
+.Worked example: form on parent does not cascade to grandchild
+[example]
+====
+[source,ruby]
+----
+NS = Class.new(Lutaml::Model::XmlNamespace) do
+  uri "https://example.com/ns"
+  prefix_default "ex"
+  element_form_default :unqualified
+end
+
+class Grandchild < Lutaml::Model::Serializable
+  attribute :value, :string
+  xml do
+    element "grandchild"
+    namespace NS
+    map_element "value", to: :value
+  end
+end
+
+class Child < Lutaml::Model::Serializable
+  attribute :inner, Grandchild
+  xml do
+    element "child"
+    namespace NS
+    map_element "grandchild", to: :inner  # NO form: override
+  end
+end
+
+class Parent < Lutaml::Model::Serializable
+  attribute :child, Child
+  xml do
+    element "item"
+    namespace NS
+    map_element "child", to: :child, form: :qualified  # Parent's rule only
+  end
+end
+
+Parent.new(child: Child.new(inner: Grandchild.new(value: "x"))).to_xml
+----
+
+*Output*:
+[source,xml]
+----
+<item xmlns="https://example.com/ns" xmlns:ex="https://example.com/ns">
+  <ex:child>
+    <grandchild>
+      <value>x</value>
+    </grandchild>
+  </ex:child>
+</item>
+----
+
+* `<ex:child>` is qualified because the *Parent* rule has `form: :qualified`.
+* `<grandchild>` is unprefixed because the *Child* rule has no `form:` and the Child's namespace is `:unqualified`.
+* The Parent's `form: :qualified` does **not** cascade.
+====
+
+To qualify every level, either set `form: :qualified` on each mapping rule that needs it, or set `element_form_default :qualified` on the namespace so inheritance handles it.
+
+== Qualification Precedence
+
+When serializing an element, the namespace is resolved by checking the following sources in priority order. The first match wins.
+
+[cols="1,4", options="header"]
+|===
+|Priority |Source
+
+|1 (highest)
+|Type-level namespace: the attribute's value type (a `Type::Value` subclass) declares `xml_namespace`. Wins over everything else.
+
+|2
+|Rule-level namespace: the mapping rule has an explicit `namespace:` option. *However*, if the parent's `element_form_default` is `:unqualified` AND the rule's namespace matches the parent's, the namespace is overridden to blank — W3C unqualified semantics for local elements.
+
+|3
+|`form: :unqualified` on the rule: force the element into no namespace.
+
+|4
+|Parent's `element_form_default :qualified` inheritance: the child inherits the parent's namespace — but only if the child model itself declares a namespace (W3C: `elementFormDefault` applies to locally-declared elements only).
+
+|5
+|`form: :qualified` on the rule: inherit the parent's namespace.
+
+|6 (lowest)
+|No namespace.
+|===
+
+This ladder is implemented in `Lutaml::Xml::Transformation::ElementBuilder#determine_element_namespace`. The `ElementFormOptionRule` decision rule reads the propagated `form` value during the planning phase and forces prefix (`:qualified`) or default (`:unqualified`) format accordingly.
+
 == Type Namespaces
 
 Value types can define their own namespaces:

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/docs/_tutorials/xml-element-attribute-namespace-guide.adoc

@@ -9,6 +9,8 @@ This guide explains how XML namespaces work, particularly the distinction betwee
 - **Qualified**: Element/attribute needs a namespace declared in the XML
 - **Unqualified**: Element/attribute does not need a namespace declared (uses parent's namespace)
 
+> **Authoritative reference:** For the `element_form_default` / `form:` system, the full qualification precedence ladder, and `form:` behavior on nested `Serializable` children, see [docs/_guides/xml-namespace-qualification.adoc](../_guides/xml-namespace-qualification.adoc). This tutorial is a conceptual introduction.
+
 ## Default Namespace Inheritance
 
 **Critical Rule:** Default namespace inheritance ONLY applies to elements, NOT attributes.

data/docs/_tutorials/xml-schema-primer-style-guide.adoc

@@ -441,6 +441,8 @@ end
 
 NOTE: The `<comment>` element uses `xmlns=""` to explicitly declare blank namespace (form: :unqualified override).
 
+TIP: The `form:` option also works on attributes whose value type is a nested `Serializable` model, not just simple types like `:string`. It is a per-rule override and does not propagate transitively to grandchildren. For the full qualification precedence ladder and worked nested-model examples, see link:../_guides/xml-namespace-qualification/#form-override-on-serializable-children[XML Namespace Qualification and Prefix Control].
+
 == Section 3: Type Namespaces
 
 === General

data/docs/namespace-management.adoc

@@ -6,6 +6,8 @@
 
 This guide provides comprehensive information about XML namespace management in Lutaml::Model, including the `namespace_scope` directive, W3C compliance, and best practices for multi-namespace documents.
 
+NOTE: This guide focuses on namespace *declaration* and *scope*. For the `element_form_default` / `form:` qualification system — including the precedence ladder and `form:` behavior on nested `Serializable` children — see the companion guide: link:./_guides/xml-namespace-qualification[XML Namespace Qualification and Prefix Control].
+
 == Understanding XML Namespaces
 
 XML namespaces provide a method to avoid element name conflicts by qualifying names used in XML documents through a URI reference.

data/docs/xml-schema-qualification.md

@@ -13,6 +13,12 @@ declared in the XML, "unqualified" means the ELEMENT/ATTRIBUTE does not need a
 namespace declared in the XML (i.e. we look to its parent's namespace to find
 its namespace).
 
+> **Authoritative reference:** For the full qualification precedence ladder,
+> `form:` behavior on nested `Serializable` children, per-rule vs transitive
+> scope, and worked examples, see
+> [docs/_guides/xml-namespace-qualification.adoc](./_guides/xml-namespace-qualification.adoc).
+> This document is a conceptual overview; the guide is the canonical reference.
+
 When there is no XML Schema present:
 * element "acts like" unqualified (because of default namespace inheritance, does not need prefix)
 * attribute "acts like" qualified (because of no default namespace inheritance, requires prefix)

data/lib/lutaml/jsonld.rb

@@ -5,9 +5,6 @@ require_relative "rdf"
 
 module Lutaml
   module JsonLd
-    autoload :Context, "#{__dir__}/jsonld/context"
-    autoload :TermDefinition, "#{__dir__}/jsonld/term_definition"
-    autoload :Transform, "#{__dir__}/jsonld/transform"
     autoload :Adapter, "#{__dir__}/jsonld/adapter"
   end
 end
@@ -16,7 +13,7 @@ Lutaml::Model::FormatRegistry.register(
   :jsonld,
   mapping_class: Lutaml::Rdf::Mapping,
   adapter_class: Lutaml::JsonLd::Adapter,
-  transformer: Lutaml::JsonLd::Transform,
+  transformer: Lutaml::Rdf::LinkedDataTransform,
   key_value: false,
   rdf: true,
   error_types: ["JSON::ParserError"],

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

@@ -36,6 +36,36 @@ module Lutaml
         @attributes << @model.attribute(name, type, options)
       end
 
+      # Restrict options on a predefined or imported attribute within this choice
+      #
+      # @param name [Symbol] The attribute name to restrict
+      # @param options [Hash] New options to merge
+      # @return [Symbol] The attribute name
+      def restrict(name, options = {})
+        @model.restrict(name, options)
+        attr = @model.attributes[name]
+        unless @attributes.include?(attr)
+          attr.options[:choice] = self
+          @attributes << attr
+        end
+        invalidate_cache!
+        name
+      end
+
+      # Remove an attribute from this choice block
+      #
+      # @param name [Symbol] The attribute name to remove
+      # @return [Boolean] true if the attribute was removed
+      def remove_attribute(name)
+        attr = @attributes.find { |a| !a.is_a?(Choice) && a.name == name }
+        return nil unless attr
+
+        @attributes.delete(attr)
+        attr.options.delete(:choice)
+        invalidate_cache!
+        attr
+      end
+
       def choice(min: 1, max: 1, &block)
         @attributes << Choice.new(@model, min, max, format: @format).tap do |c|
           c.instance_eval(&block)
@@ -163,6 +193,10 @@ register = nil)
 
       private
 
+      def invalidate_cache!
+        @flat_attributes = nil
+      end
+
       def raise_errors(choices_hash)
         flat_attr_names = flat_attributes.map { |attr| attr.name.to_s }
         choices_hash.each do |choice_attr, count|

data/lib/lutaml/model/compiled_rule.rb

@@ -98,6 +98,13 @@ module Lutaml
         !custom_methods.empty?
       end
 
+      # Check if form is explicitly set
+      #
+      # @return [Boolean] true if form option was provided
+      def form_set?
+        !form.nil?
+      end
+
       # Check if a name matches this rule (including alias names for multiple mappings)
       #
       # @param name [String, Symbol] The name to check

data/lib/lutaml/model/version.rb

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

data/lib/lutaml/model.rb

@@ -11,6 +11,7 @@ module Lutaml
   autoload :Yamls, "#{__dir__}/yamls"
   autoload :Xml, "#{__dir__}/xml"
   autoload :JsonLd, "#{__dir__}/jsonld"
+  autoload :YamlLd, "#{__dir__}/yamlld"
   autoload :Turtle, "#{__dir__}/turtle"
 
   module Model
@@ -149,7 +150,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/{jsonld → rdf}/context.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Lutaml
-  module JsonLd
+  module Rdf
     class Context
       attr_reader :prefixes, :terms