lutaml-model 0.7.6 → 0.8.0

data/docs/_guides/xml_mappings/05_common_patterns.adoc

@@ -0,0 +1,1803 @@
+---
+title: Common patterns
+nav_order: 5
+parent: XML Mappings Guide
+---
+
+= Common patterns
+
+== Basic element and attribute mapping
+
+=== Simple model with elements
+
+.Basic ceramic model with element mappings
+[example]
+====
+[source,ruby]
+----
+class Ceramic < Lutaml::Model::Serializable
+  attribute :name, :string
+  attribute :description, :string
+  attribute :temperature, :integer
+
+  xml do
+    root 'ceramic'
+    map_element 'name', to: :name
+    map_attribute 'temperature', to: :temperature
+    map_content to: :description
+  end
+end
+----
+
+[source,xml]
+----
+<ceramic temperature="1200">
+  <name>Porcelain Vase</name>
+  with celadon glaze.
+</ceramic>
+----
+
+[source,ruby]
+----
+> Ceramic.from_xml(xml)
+> #<Ceramic @name="Porcelain Vase",
+   @description=" with celadon glaze.",
+   @temperature=1200>
+----
+====
+
+=== Nested models
+
+.Model with nested object
+[example]
+====
+[source,ruby]
+----
+class Glaze < Lutaml::Model::Serializable
+  attribute :color, :string
+  attribute :temperature, :integer
+
+  xml do
+    root 'Glaze'
+    map_element 'color', to: :color
+    map_element 'temperature', to: :temperature
+  end
+end
+
+class Ceramic < Lutaml::Model::Serializable
+  attribute :type, :string
+  attribute :glaze, Glaze
+
+  xml do
+    root 'Ceramic'
+    map_element 'Type', to: :type
+    map_element 'Glaze', to: :glaze
+  end
+end
+----
+
+[source,xml]
+----
+<Ceramic>
+  <Type>Porcelain</Type>
+  <Glaze>
+    <color>Clear</color>
+    <temperature>1050</temperature>
+  </Glaze>
+</Ceramic>
+----
+====
+
+== Namespace patterns
+
+=== Single namespace
+
+.Model with single namespace
+[example]
+====
+[source,ruby]
+----
+class Ceramic < Lutaml::Model::Serializable
+  attribute :type, :string
+  attribute :glaze, :string
+
+  xml do
+    root 'Ceramic'
+    namespace 'http://example.com/ceramic'
+    map_element 'Type', to: :type
+    map_element 'Glaze', to: :glaze
+  end
+end
+----
+
+[source,xml]
+----
+<Ceramic xmlns='http://example.com/ceramic'>
+  <Type>Porcelain</Type>
+  <Glaze>Clear</Glaze>
+</Ceramic>
+----
+====
+
+=== Prefixed namespace
+
+.Model with prefixed namespace
+[example]
+====
+[source,ruby]
+----
+class Ceramic < Lutaml::Model::Serializable
+  attribute :type, :string
+  attribute :glaze, :string
+
+  xml do
+    root 'Ceramic'
+    namespace 'http://example.com/ceramic', 'cer'
+    map_element 'Type', to: :type
+    map_element 'Glaze', to: :glaze
+  end
+end
+----
+
+[source,xml]
+----
+<cer:Ceramic xmlns:cer='http://example.com/ceramic'>
+  <cer:Type>Porcelain</cer:Type>
+  <cer:Glaze>Clear</cer:Glaze>
+</cer:Ceramic>
+----
+====
+
+=== Multi-namespace with XmlNamespace class
+
+.Model using multiple namespaces with XmlNamespace classes
+[example]
+====
+[source,ruby]
+----
+class CeramicNamespace < Lutaml::Model::XmlNamespace
+  uri 'https://example.com/ceramic'
+  prefix_default 'cer'
+end
+
+class GlazeNamespace < Lutaml::Model::XmlNamespace
+  uri 'https://example.com/glaze'
+  prefix_default 'glz'
+end
+
+class Ceramic < Lutaml::Model::Serializable
+  attribute :type, :string
+  attribute :glaze, :string
+
+  xml do
+    element 'ceramic'
+    namespace CeramicNamespace
+
+    map_element 'type', to: :type
+    map_element 'glaze', to: :glaze,
+      namespace: GlazeNamespace
+  end
+end
+----
+
+[source,xml]
+----
+<cer:ceramic xmlns:cer="https://example.com/ceramic"
+             xmlns:glz="https://example.com/glaze">
+  <type>Porcelain</type>
+  <glz:glaze>Celadon</glz:glaze>
+</cer:ceramic>
+----
+====
+
+=== Namespace inheritance pattern
+
+.Element explicitly inheriting parent namespace
+[example]
+====
+[source,ruby]
+----
+class CeramicNamespace < Lutaml::Model::XmlNamespace
+  uri 'https://example.com/ceramic'
+  prefix_default 'cer'
+  element_form_default :unqualified
+end
+
+class SpecialType < Lutaml::Model::Serializable
+  attribute :value, :string
+
+  xml do
+    element 'specialType'
+    namespace CeramicNamespace  # Inherit parent namespace
+    map_content to: :value
+  end
+end
+
+class Ceramic < Lutaml::Model::Serializable
+  attribute :type, :string
+  attribute :special_type, SpecialType
+
+  xml do
+    element 'ceramic'
+    namespace CeramicNamespace
+
+    map_element 'type', to: :type  # Unqualified (follows element_form_default)
+    map_element 'specialType', to: :special_type  # Uses SpecialType's namespace
+  end
+end
+----
+
+[source,xml]
+----
+<cer:ceramic xmlns:cer="https://example.com/ceramic">
+  <type>Porcelain</type>
+  <cer:specialType>Fine</cer:specialType>
+</cer:ceramic>
+----
+====
+
+== Rich content patterns
+
+=== Mixed content
+
+.Model with mixed content (text + elements) -- round-trip example
+[example]
+====
+[source,ruby]
+----
+class MathExpression < Lutaml::Model::Serializable
+  attribute :content, :string
+
+  xml do
+    element "math"
+    map_content to: :content
+  end
+end
+
+class Paragraph < Lutaml::Model::Serializable
+  attribute :text, :string, collection: true     # collection: true required
+  attribute :bold, :string, collection: true
+  attribute :stem, MathExpression, collection: true
+
+  xml do
+    element 'p'
+    mixed_content  # Enable mixed content + ordered round-trip
+
+    map_content to: :text
+    map_element 'bold', to: :bold
+    map_element 'stem', to: :stem
+  end
+end
+----
+
+[source,xml]
+----
+<p>Temperature <stem>T</stem> minus <stem>T<sub>90</sub></stem></p>
+----
+
+[source,ruby]
+----
+parsed = Paragraph.from_xml(xml)
+
+# Access text segments and elements separately
+parsed.text   # => ["Temperature ", " minus "]
+parsed.stem.map(&:content)  # => ["T", "T90"]
+
+# Serialize back -- text and elements appear in their original positions
+parsed.to_xml
+# => "<p>Temperature <stem>T</stem> minus <stem>T<sub>90</sub></stem></p>"
+
+# Iterate in document order to process text and elements interleaved
+parsed.each_mixed_content do |node|
+  case node
+  when String
+    puts "Text: #{node.inspect}"
+  when MathExpression
+    puts "Math: #{node.content}"
+  end
+end
+# Output:
+#   Text: "Temperature "
+#   Math: T
+#   Text: " minus "
+#   Math: T90
+----
+====
+[NOTE]
+.map_content requires collection: true for mixed content
+====
+For mixed content, `map_content` must target an attribute with `collection: true` because XML like:
+[source,xml]
+----
+<hello><element1>hi</element1> ho <element2>he</element2>? Yes!</hello>
+----
+has multiple text segments between elements. Each segment becomes an entry in the content collection.
+
+Without `mixed_content`, serialization groups all text first then all elements
+(or vice versa), losing the original interleaving. This is the most common
+cause of XML round-trip failures in document-processing applications.
+
+=== Builder interface for mixed content
+
+When constructing models with `mixed_content`, the builder interface provides a DSL for
+recording insertion order. The builder tracks element order via `element_order` for
+serialization.
+
+==== Model definitions
+
+[source,ruby]
+----
+class Person < Lutaml::Model::Serializable
+  attribute :name, :string
+
+  xml do
+    element "person"
+    map_content to: :name
+  end
+end
+
+class Group < Lutaml::Model::Serializable
+  attribute :member, Person, collection: true
+  attribute :member_key, :string, collection: true
+  attribute :description, :string, collection: true
+
+  xml do
+    element "group"
+    mixed_content
+    map_element "member", to: :member
+    map_element "member_key", to: :member_key
+    map_content to: :description
+  end
+end
+----
+
+==== NO MAGIC: Explicit receiver
+
+.Builder with explicit receiver
+[example]
+====
+[source,ruby]
+----
+group = Group.new do |g|
+  members.each do |m|
+    g.member(m[:person])
+    g.member_key(m[:key])
+    g.description("\n  " + m[:description] + "\n")
+  end
+end
+----
+====
+
+==== MAGIC: instance_eval (no receiver)
+
+.Builder with instance_eval - no receiver needed
+[example]
+====
+[source,ruby]
+----
+group = Group.new do
+  members.each do |m|
+    member(m[:person])
+    member_key(m[:key])
+    description("\n  " + m[:description] + "\n")
+  end
+end
+----
+====
+
+[NOTE]
+.Both syntaxes track order identically
+====
+The `element_order` array records entries in the order they were added, preserving
+the sequence for XML serialization.
+
+==== Why whitespace is intentional content
+
+In mixed content XML, whitespace between elements *is* content:
+
+[source,xml]
+----
+<group>
+  <member>John Hodges</member>
+  <member_key>john</member_key>
+  He is a good man.
+  <member>Thomas Mellon</member>
+  <member_key>thomas</member_key>
+  He was a strong man.
+</group>
+----
+
+The builder records whitespace strings as first-class content entries:
+
+[source,ruby]
+----
+description("\n  " + m[:description] + "\n")
+#          ↑                            ↑
+#     before whitespace          after whitespace
+----
+====
+
+=== Ordered content
+
+.Model preserving element order
+[example]
+====
+[source,ruby]
+----
+class RootOrderedContent < Lutaml::Model::Serializable
+  attribute :bold, :string
+  attribute :italic, :string
+  attribute :underline, :string
+
+  xml do
+    element "RootOrderedContent"
+    ordered  # Preserve element order
+    map_element :bold, to: :bold
+    map_element :italic, to: :italic
+    map_element :underline, to: :underline
+  end
+end
+----
+
+[source,xml]
+----
+<RootOrderedContent>
+  <underline>Moon</underline>
+  <italic>384,400 km</italic>
+  <bold>bell</bold>
+</RootOrderedContent>
+----
+
+When serialized back, the order is preserved:
+
+[source,ruby]
+----
+> instance = RootOrderedContent.from_xml(xml)
+> instance.to_xml
+> #<RootOrderedContent>
+    <underline>Moon</underline>
+    <italic>384,400 km</italic>
+    <bold>bell</bold>
+  </RootOrderedContent>
+----
+====
+
+=== Iterating mixed content with `each_mixed_content`
+
+When working with mixed content (text interspersed with elements) or ordered content
+(elements in a specific sequence), you often need to iterate in document order to
+process or transform the content. The `each_mixed_content` method provides an
+iterator that yields text nodes and typed model objects in their original document order.
+
+[NOTE]
+====
+`each_mixed_content` is available on any model instance that has `mixed_content` or
+`ordered` enabled in its XML mapping. It returns an empty Enumerator if neither is set.
+====
+
+.Iterating over mixed content in document order
+[example]
+====
+[source,ruby]
+----
+class Docbook::Elements::Para < Lutaml::Model::Serializable
+  attribute :content, :string
+  attribute :emphasis, :string, collection: true
+  attribute :code, :string, collection: true
+
+  xml do
+    element "para"
+    mixed_content
+    map_content to: :content
+    map_element "emphasis", to: :emphasis
+    map_element "code", to: :code
+  end
+end
+----
+
+[source,xml]
+----
+<para>Hello <emphasis role="bold">world</emphasis> and <code>example</code>!</para>
+----
+
+[source,ruby]
+----
+para = Docbook::Elements::Para.from_xml(xml)
+
+# Iterate in document order, yielding text and elements
+para.each_mixed_content do |node|
+  case node
+  when String
+    puts "Text: #{node.inspect}"
+  when String  # emphasis/code are stored as strings in this model
+    puts "Inline element content: #{node.inspect}"
+  end
+end
+# => "Text: \"Hello \""
+# => "Inline element content: \"world\""
+# => "Text: \" and \""
+# => "Inline element content: \"example\""
+# => "Text: \"!\""
+----
+====
+
+.Generating HTML from mixed content
+[example]
+====
+A common use case is converting DocBook or similar XML to HTML:
+
+[source,ruby]
+----
+class HtmlConverter
+  def convert_para(para)
+    html = "<p>"
+
+    para.each_mixed_content do |node|
+      case node
+      when String
+        html += escape_html(node)
+      when Docbook::Elements::Emphasis
+        role = node.role == "bold" ? "strong" : "em"
+        html += "<#{role}>#{escape_html(node.content)}</#{role}>"
+      end
+    end
+
+    html += "</p>"
+    html
+  end
+
+  private
+
+  def escape_html(text)
+    text.gsub("&", "&amp;")
+         .gsub("<", "&lt;")
+         .gsub(">", "&gt;")
+  end
+end
+----
+====
+
+.Return value and chaining
+
+`each_mixed_content` returns:
+
+* `self` when called with a block (for chaining)
+* An `Enumerator` when called without a block -- supports `with_index`, `select`, `map`, etc.
+
+[source,ruby]
+----
+# With block
+para.each_mixed_content { |node| process(node) }
+
+# Without block - returns Enumerator
+enum = para.each_mixed_content
+enum.select { |node| node.is_a?(String) }
+enum.each { |node| process(node) }
+
+# With index - useful for positional processing
+para.each_mixed_content.with_index do |node, index|
+  puts "#{index}: #{node.inspect}"
+end
+# 0: "Temperature "
+# 1: #<MathExpression content="T">
+# 2: " minus "
+# 3: #<MathExpression content="T90">
+----
+
+[NOTE]
+====
+Whitespace-only text fragments are automatically skipped by `each_mixed_content`.
+This matches typical XML processing behavior where insignificant whitespace is ignored.
+====
+
+[IMPORTANT]
+.`each_mixed_content` is XML-specific
+====
+For JSON and YAML formats, rich text uses a *recursive tree pattern* instead of the
+mixed content model used by XML. Each node in the tree knows its type and contains
+its own children. Since the tree IS the content structure, you can iterate using
+natural tree traversal methods.
+
+See the <<Recursive tree pattern for JSON/YAML,next section>> for details.
+====
+
+[[recursive-tree-pattern]]
+=== Recursive tree pattern for JSON/YAML
+
+Unlike XML's mixed content model (which requires `each_mixed_content` to correlate
+text fragments with element collections), JSON and YAML represent rich text using a
+recursive tree structure. Each node knows its type, and container nodes hold a
+`children` array containing child nodes.
+
+[IMPORTANT]
+.These are different data models
+====
+XML mixed content and JSON/YAML recursive tree are fundamentally different data
+structures. They cannot be represented by the same Ruby model class because:
+
+* **XML**: `content` is a String, `emphasis` is a collection
+* **JSON/YAML**: `content` is a collection of nodes, each with `children`
+
+Instead, define separate models for each format family.
+====
+
+.Recursive tree structure for rich text
+[source,json]
+----
+{
+  "type": "para",
+  "content": [
+    { "type": "text", "value": "Hello " },
+    { "type": "emphasis", "role": "bold", "children": [
+      { "type": "text", "value": "world" }
+    ]},
+    { "type": "text", "value": "!" }
+  ]
+}
+----
+
+[NOTE]
+====
+In this pattern:
+- Each node has a `type` field indicating what kind of node it is
+- Container nodes (like `emphasis`) have a `children` array
+- Leaf nodes (like `text`) have a `value` field
+- The tree structure itself preserves order - no separate tracking needed
+====
+
+.XML Model (Mixed Content)
+[example]
+====
+For XML, use `mixed_content` with separate `content` attribute and element collections:
+
+[source,ruby]
+----
+class Docbook::Elements::Para < Lutaml::Model::Serializable
+  attribute :content, :string
+  attribute :emphasis, Docbook::Elements::Emphasis, collection: true
+
+  xml do
+    element "para"
+    mixed_content
+    map_content to: :content
+    map_element "emphasis", to: :emphasis
+    xml_space :preserve
+  end
+end
+
+class Docbook::Elements::Emphasis < Lutaml::Model::Serializable
+  attribute :role, :string
+  attribute :content, :string
+
+  xml do
+    element "emphasis"
+    map_attribute "role", to: :role
+    map_content to: :content
+  end
+end
+----
+
+[source,xml]
+----
+<para>Hello <emphasis role="bold">world</emphasis>!</para>
+----
+====
+
+.JSON/YAML Model (Recursive Tree)
+[example]
+====
+For JSON/YAML, use a polymorphic node structure where inline elements have `children`:
+
+[source,ruby]
+----
+# Base class for all rich text nodes
+class RichText::Node < Lutaml::Model::Serializable
+end
+
+# Leaf node for text
+class RichText::TextNode < Lutaml::Model::Serializable
+  attribute :value, :string
+
+  json do
+    map "value", to: :value
+  end
+
+  yaml do
+    map "value", to: :value
+  end
+end
+
+# Inline element with children
+class RichText::Emphasis < Lutaml::Model::Serializable
+  attribute :role, :string
+  attribute :children, RichText::Node, collection: true
+
+  json do
+    map "type", to: :type
+    map "role", to: :role
+    map "children", to: :children
+  end
+
+  yaml do
+    map "type", to: :type
+    map "role", to: :role
+    map "children", to: :children
+  end
+
+  def type
+    "emphasis"
+  end
+end
+
+# Container with content
+class RichText::Para < Lutaml::Model::Serializable
+  attribute :type, :string
+  attribute :content, RichText::Node, collection: true
+
+  json do
+    map "type", to: :type
+    map "content", to: :content
+  end
+
+  yaml do
+    map "type", to: :type
+    map "content", to: :content
+  end
+
+  def type
+    "para"
+  end
+end
+----
+
+[source,json]
+----
+{
+  "type": "para",
+  "content": [
+    { "type": "text", "value": "Hello " },
+    { "type": "emphasis", "role": "bold", "children": [
+      { "type": "text", "value": "world" }
+    ]},
+    { "type": "text", "value": "!" }
+  ]
+}
+----
+====
+
+.Processing rich text by format
+
+[source,ruby]
+----
+# XML: Use each_mixed_content
+xml_para = Docbook::Elements::Para.from_xml(xml_input)
+xml_para.each_mixed_content do |node|
+  case node
+  when String
+    print node  # Text fragments
+  when Docbook::Elements::Emphasis
+    print "<#{node.role}>#{node.content}</#{node.role}>"
+  end
+end
+
+# JSON/YAML: Use natural tree traversal
+json_para = RichText::Para.from_json(json_input)
+
+def process_node(node)
+  case node
+  when RichText::TextNode
+    print node.value
+  when RichText::Emphasis
+    print "<#{node.role}>"
+    node.children.each { |child| process_node(child) }
+    print "</#{node.role}>"
+  end
+end
+
+json_para.content.each { |node| process_node(node) }
+----
+
+.Comparison: XML vs JSON/YAML for rich text
+
+[cols="1,2,2"]
+|===
+| Aspect | XML Mixed Content | JSON/YAML Recursive Tree
+
+| Ruby model attributes
+| `content` (String), `emphasis` (collection)
+| `content` (collection of Nodes), `children` (collection)
+
+| Text storage
+| Single `content` string attribute
+| Separate `TextNode` objects with `value`
+
+| Element nesting
+| Flat - elements stored in collections
+| Recursive - elements have `children` array
+
+| Order tracking
+| Via `element_order` + `each_mixed_content`
+| Implicit in tree structure
+
+| Iteration method
+| `each_mixed_content`
+| `node.children.each { |child| ... }`
+
+| Whitespace
+| Use `xml_space :preserve`
+| Preserved naturally by tree structure
+|===
+
+.Dual-format serialization: Same content, different models
+
+These are *separate model classes* by design, not one model that does both.
+Each format family (XML vs JSON/YAML) requires a different data structure:
+
+[source,ruby]
+----
+# ============================================
+# XML MODEL: Mixed Content Pattern
+# ============================================
+# Structure: content (String) + emphasis (collection)
+# Use each_mixed_content to iterate in document order
+
+class Docbook::Elements::Para < Lutaml::Model::Serializable
+  attribute :content, :string
+  attribute :emphasis, Docbook::Elements::Emphasis, collection: true
+
+  xml do
+    element "para"
+    mixed_content
+    map_content to: :content
+    map_element "emphasis", to: :emphasis
+    xml_space :preserve
+  end
+end
+
+class Docbook::Elements::Emphasis < Lutaml::Model::Serializable
+  attribute :role, :string
+  attribute :content, :string
+
+  xml do
+    element "emphasis"
+    map_attribute "role", to: :role
+    map_content to: :content
+  end
+end
+
+# ============================================
+# JSON/YAML MODEL: Recursive Tree Pattern
+# ============================================
+# Structure: content (collection of Nodes) + children (in each node)
+# Use natural tree traversal: node.children.each { ... }
+
+class RichText::Node < Lutaml::Model::Serializable
+  # Base class for polymorphic node types
+end
+
+class RichText::TextNode < Lutaml::Model::Serializable
+  attribute :type, :string
+  attribute :value, :string
+
+  def type
+    "text"
+  end
+end
+
+class RichText::Emphasis < Lutaml::Model::Serializable
+  attribute :type, :string
+  attribute :role, :string
+  attribute :children, RichText::Node, collection: true
+
+  def type
+    "emphasis"
+  end
+end
+
+class RichText::Para < Lutaml::Model::Serializable
+  attribute :type, :string
+  attribute :content, RichText::Node, collection: true
+
+  def type
+    "para"
+  end
+end
+
+# Define JSON/YAML mappings separately
+class RichText::TextNode
+  json do map "value", to: :value end
+  yaml do map "value", to: :value end
+end
+
+class RichText::Emphasis
+  json do
+    map "type", to: :type
+    map "role", to: :role
+    map "children", to: :children
+  end
+  yaml do
+    map "type", to: :type
+    map "role", to: :role
+    map "children", to: :children
+  end
+end
+
+class RichText::Para
+  json do
+    map "type", to: :type
+    map "content", to: :content
+  end
+  yaml do
+    map "type", to: :type
+    map "content", to: :content
+  end
+end
+----
+
+.Serialization examples
+
+[source,ruby]
+----
+# XML: Build model and serialize
+xml_para = Docbook::Elements::Para.new(
+  content: "Hello ",
+  emphasis: [
+    Docbook::Elements::Emphasis.new(role: "bold", content: "world")
+  ]
+)
+xml_para.content += "!"  # Append to string
+
+puts xml_para.to_xml
+# => <para xml:space="preserve">Hello <emphasis role="bold">world</emphasis>!</para>
+
+# JSON: Build model and serialize
+json_para = RichText::Para.new(
+  content: [
+    RichText::TextNode.new(value: "Hello "),
+    RichText::Emphasis.new(
+      role: "bold",
+      children: [RichText::TextNode.new(value: "world")]
+    ),
+    RichText::TextNode.new(value: "!")
+  ]
+)
+
+puts json_para.to_json
+# => {"type":"para","content":[
+#      {"type":"text","value":"Hello "},
+#      {"type":"emphasis","role":"bold","children":[
+#        {"type":"text","value":"world"}
+#      ]},
+#      {"type":"text","value":"!"}
+#    ]}
+
+# YAML also works:
+puts json_para.to_yaml
+----
+====
+
+.Whitespace handling for XML
+
+For XML mixed content, use `xml_space :preserve` to maintain whitespace:
+
+[source,ruby]
+----
+class Docbook::Elements::Para < Lutaml::Model::Serializable
+  attribute :content, :string
+  attribute :emphasis, Docbook::Elements::Emphasis, collection: true
+
+  xml do
+    element "para"
+    mixed_content
+    xml_space :preserve  # <-- Critical for rich text
+    map_content to: :content
+    map_element "emphasis", to: :emphasis
+  end
+end
+----
+====
+
+== Sequence patterns
+
+=== Basic sequence
+
+.Model with strict element ordering
+[example]
+====
+[source,ruby]
+----
+class Kiln < Lutaml::Model::Serializable
+  attribute :id, :string
+  attribute :name, :string
+  attribute :type, :string
+  attribute :color, :string
+
+  xml do
+    sequence do
+      map_element :id, to: :id
+      map_element :name, to: :name
+      map_element :type, to: :type
+      map_element :color, to: :color
+    end
+  end
+end
+----
+
+[source,xml]
+----
+<collection>
+  <kiln>
+    <id>1</id>
+    <name>Nick</name>
+    <type>Hard</type>
+    <color>Black</color>
+  </kiln>
+</collection>
+----
+
+If elements appear out of order, an error is raised.
+====
+
+=== Sequence with namespace
+
+.Combining sequence with namespace and XmlNamespace class
+[example]
+====
+[source,ruby]
+----
+class ContactNamespace < Lutaml::Model::XmlNamespace
+  uri 'https://example.com/schemas/contact/v1'
+  prefix_default 'contact'
+  element_form_default :qualified
+end
+
+class Person < Lutaml::Model::Serializable
+  attribute :name, :string
+  attribute :email, :string
+
+  xml do
+    element "person"
+    namespace ContactNamespace
+
+    sequence do
+      map_element "name", to: :name
+      map_element "email", to: :email
+    end
+  end
+end
+----
+
+[source,xml]
+----
+<contact:person xmlns:contact="https://example.com/schemas/contact/v1">
+  <contact:name>John Doe</contact:name>
+  <contact:email>john@example.com</contact:email>
+</contact:person>
+----
+====
+
+== Type-only models (no element)
+
+=== Embedded type pattern
+
+.Type-only model used within parent
+[example]
+====
+[source,ruby]
+----
+# Type-only model - no element() or root() call
+class Address < Lutaml::Model::Serializable
+  attribute :street, :string
+  attribute :city, :string
+  attribute :postal_code, :string
+
+  xml do
+    # No element declaration - this is a type-only model
+    sequence do
+      map_element 'street', to: :street
+      map_element 'city', to: :city
+      map_element 'postalCode', to: :postal_code
+    end
+  end
+end
+
+# Parent model using the type
+class Contact < Lutaml::Model::Serializable
+  attribute :name, :string
+  attribute :address, Address
+
+  xml do
+    element 'contact'
+
+    sequence do
+      map_element 'name', to: :name
+      map_element 'address', to: :address
+    end
+  end
+end
+----
+
+[source,xml]
+----
+<contact>
+  <name>John Doe</name>
+  <address>
+    <street>123 Main St</street>
+    <city>Metropolis</city>
+    <postalCode>12345</postalCode>
+  </address>
+</contact>
+----
+====
+
+== CDATA patterns
+
+=== Forcing CDATA output
+
+.Using cdata option to preserve special characters
+[example]
+====
+[source,ruby]
+----
+class Example < Lutaml::Model::Serializable
+  attribute :name, :string
+  attribute :description, :string
+  attribute :title, :string
+  attribute :note, :string
+
+  xml do
+    root 'example'
+    map_element :name, to: :name, cdata: true
+    map_content to: :description, cdata: true
+    map_element :title, to: :title, cdata: false
+    map_element :note, to: :note, cdata: false
+  end
+end
+----
+
+[source,xml]
+----
+<example>
+  <name><![CDATA[John]]></name>
+  <![CDATA[here is the description]]>
+  <title>Lutaml</title>
+  <note>Careful</note>
+</example>
+----
+====
+
+== XSD generation patterns
+
+=== Basic XSD generation
+
+.Generating XSD from model
+[example]
+====
+[source,ruby]
+----
+class Contact < Lutaml::Model::Serializable
+  attribute :name, :string
+  attribute :email, :string
+
+  xml do
+    element 'contact'
+    map_element 'name', to: :name
+    map_element 'email', to: :email
+  end
+end
+
+# Generate XSD
+xsd = Lutaml::Model::Schema.to_xml(Contact)
+puts xsd
+----
+====
+
+=== XSD with namespace and documentation
+
+.Complete XSD generation with metadata
+[example]
+====
+[source,ruby]
+----
+class ContactNamespace < Lutaml::Model::XmlNamespace
+  uri 'https://example.com/schemas/contact/v1'
+  schema_location 'https://example.com/schemas/contact/v1/contact.xsd'
+  prefix_default 'contact'
+  element_form_default :qualified
+  version '1.0'
+  documentation "Contact information schema"
+end
+
+class Contact < Lutaml::Model::Serializable
+  attribute :name, :string
+  attribute :email, :string
+
+  xml do
+    element 'contact'
+    namespace ContactNamespace
+    documentation "A contact record"
+
+    sequence do
+      map_element 'name', to: :name
+      map_element 'email', to: :email
+    end
+  end
+end
+
+# Generate XSD with options
+xsd = Lutaml::Model::Schema.to_xml(
+  Contact,
+  namespace: ContactNamespace.uri,
+  prefix: ContactNamespace.prefix_default,
+  output_dir: 'schemas',
+  create_files: true
+)
+----
+====
+
+== Qualification patterns
+
+=== Qualified elements pattern
+
+.All elements namespace-qualified
+[example]
+====
+[source,ruby]
+----
+class CeramicNamespace < Lutaml::Model::XmlNamespace
+  uri 'https://example.com/ceramic'
+  prefix_default 'cer'
+  element_form_default :qualified  # All local elements qualified
+end
+
+class Ceramic < Lutaml::Model::Serializable
+  attribute :type, :string
+  attribute :color, :string
+
+  xml do
+    element 'ceramic'
+    namespace CeramicNamespace
+
+    map_element 'type', to: :type
+    map_element 'color', to: :color
+  end
+end
+----
+
+[source,xml]
+----
+<cer:ceramic xmlns:cer="https://example.com/ceramic">
+  <cer:type>Porcelain</cer:type>
+  <cer:color>White</cer:color>
+</cer:ceramic>
+----
+====
+
+=== Selective qualification
+
+.Override qualification for specific elements
+[example]
+====
+[source,ruby]
+----
+class CeramicNamespace < Lutaml::Model::XmlNamespace
+  uri 'https://example.com/ceramic'
+  prefix_default 'cer'
+  element_form_default :unqualified  # Default: unqualified
+end
+
+class Ceramic < Lutaml::Model::Serializable
+  attribute :type, :string
+  attribute :glaze, :string
+  attribute :id, :string
+
+  xml do
+    element 'ceramic'
+    namespace CeramicNamespace
+
+    # Override to qualified
+    map_element 'type', to: :type, form: :qualified
+    # Use default (unqualified)
+    map_element 'glaze', to: :glaze
+    # Force attribute qualified
+    map_attribute 'id', to: :id, form: :qualified
+  end
+end
+----
+
+[source,xml]
+----
+<cer:ceramic xmlns:cer="https://example.com/ceramic" cer:id="C001">
+  <cer:type>Porcelain</cer:type>
+  <glaze>Clear</glaze>
+</cer:ceramic>
+----
+====
+
+== Collection patterns
+
+=== Element collections
+
+.Model with element collection
+[example]
+====
+[source,ruby]
+----
+class CeramicCollection < Lutaml::Model::Serializable
+  attribute :items, Ceramic, collection: true
+
+  xml do
+    root 'ceramics'
+    map_element 'ceramic', to: :items
+  end
+end
+----
+
+[source,xml]
+----
+<ceramics>
+  <ceramic>...</ceramic>
+  <ceramic>...</ceramic>
+  <ceramic>...</ceramic>
+</ceramics>
+----
+====
+
+=== Attribute collections with delimiter
+
+.XML attribute containing delimited values
+[example]
+====
+[source,ruby]
+----
+class TitleCollection < Lutaml::Model::Collection
+  instances :items, :string
+
+  xml do
+    root "titles"
+    map_attribute "title", to: :items, delimiter: "; "
+  end
+end
+----
+
+[source,xml]
+----
+<titles title="Title One; Title Two; Title Three"/>
+----
+
+[source,ruby]
+----
+collection = TitleCollection.from_xml(xml)
+collection.items
+# => ["Title One", "Title Two", "Title Three"]
+----
+====
+
+== Character encoding patterns
+
+=== Per-instance encoding
+
+.Setting encoding on model instance
+[example]
+====
+[source,ruby]
+----
+class JapaneseCeramic < Lutaml::Model::Serializable
+  attribute :glaze_type, :string
+  attribute :description, :string
+
+  xml do
+    root 'JapaneseCeramic'
+    map_attribute 'glazeType', to: :glaze_type
+    map_element 'description', to: :description
+  end
+end
+
+# Create instance with UTF-8 data
+instance = JapaneseCeramic.new(
+  glaze_type: "志野釉",
+  description: "東京国立博物館コレクション"
+)
+
+# Set character encoding to Shift_JIS
+instance.encoding = "Shift_JIS"
+
+# Serialize with specified encoding
+serialization_output = instance.to_xml
+----
+====
+
+=== Per-export encoding
+
+.Setting encoding during serialization
+[example]
+====
+[source,ruby]
+----
+ceramic_instance = Ceramic.new(
+  potter: "John & Jane",
+  description: " A ∑ series of ∏ porcelain µ vases."
+)
+
+# Using default encoding of UTF-8
+ceramic_instance.to_xml
+# => <ceramic><potter>John &amp; Jane</potter> A ∑ series...</ceramic>
+
+# Using ASCII encoding
+ceramic_instance.to_xml(encoding: "ASCII")
+# => <ceramic><potter>John &amp; Jane</potter> A &#8721; series...</ceramic>
+----
+====
+
+== Import patterns with sequence
+
+=== Importing mappings in sequence
+
+.Using import_model_mappings inside sequence
+[example]
+====
+[source,ruby]
+----
+class Address < Lutaml::Model::Serializable
+  attribute :street, :string
+  attribute :city, :string
+  attribute :zip, :string
+
+  xml do
+    no_root
+
+    map_element :street, to: :street
+    map_element :city, to: :city
+    map_element :zip, to: :zip
+  end
+end
+
+class Person < Lutaml::Model::Serializable
+  attribute :name, :string
+  import_model_attributes Address
+
+  xml do
+    root "Person"
+
+    map_element :name, to: :name
+    sequence do
+      import_model_mappings Address
+    end
+  end
+end
+----
+
+[source,xml]
+----
+<Person>
+  <name>John Doe</name>
+  <street>123 Main St</street>
+  <city>Metropolis</city>
+  <zip>12345</zip>
+</Person>
+----
+====
+
+== XSD type override patterns
+
+=== Using xsd_type for IDs
+
+.Specify XSD types for ID/IDREF
+[example]
+====
+[source,ruby]
+----
+class Product < Lutaml::Model::Serializable
+  attribute :product_id, :string, xsd_type: 'xs:ID'
+  attribute :category_ref, :string, xsd_type: 'xs:IDREF'
+
+  xml do
+    element 'product'
+    map_attribute 'id', to: :product_id
+    map_attribute 'categoryRef', to: :category_ref
+  end
+end
+
+# Generated XSD:
+# <xs:attribute name="id" type="xs:ID"/>
+# <xs:attribute name="categoryRef" type="xs:IDREF"/>
+----
+====
+
+=== Using xsd_type for custom types
+
+.Override automatic XSD type inference
+[example]
+====
+[source,ruby]
+----
+class Document < Lutaml::Model::Serializable
+  attribute :language, :string, xsd_type: 'xs:language'
+  attribute :content_type, :string, xsd_type: 'xs:token'
+
+  xml do
+    element 'document'
+    map_attribute 'lang', to: :language
+    map_attribute 'contentType', to: :content_type
+  end
+end
+----
+====
+
+== Type-level namespace pattern
+
+=== Type with own namespace
+
+.Custom type declaring its namespace
+[example]
+====
+[source,ruby]
+----
+# Define namespace for email types
+class EmailNamespace < Lutaml::Model::XmlNamespace
+  uri 'https://example.com/types/email'
+  prefix_default 'email'
+end
+
+# Define type with namespace
+class EmailType < Lutaml::Model::Type::String
+  xml do
+    namespace EmailNamespace  # <1>
+    xsd_type 'EmailAddress'   # <2>
+  end
+
+  def self.cast(value)
+    email = super(value)
+    unless email.match?(/\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i)
+      raise Lutaml::Model::TypeError, "Invalid email: #{email}"
+    end
+    email.downcase
+  end
+end
+
+class Contact < Lutaml::Model::Serializable
+  attribute :email, EmailType
+
+  xml do
+    element 'contact'
+    namespace 'https://example.com/contact', 'c'
+
+    map_element 'email', to: :email  # Uses EmailNamespace from EmailType
+  end
+end
+
+contact = Contact.new(email: "USER@EXAMPLE.COM")
+puts contact.to_xml
+# => <c:contact xmlns:c="https://example.com/contact"
+#               xmlns:email="https://example.com/types/email">
+#      <email:email>user@example.com</email:email>
+#    </c:contact>
+
+# Round-trip deserialization works
+parsed = Contact.from_xml(contact.to_xml)
+parsed.email  # => "user@example.com"
+----
+<1> Namespace directive associates EmailNamespace with this type
+<2> XSD type name for schema generation
+====
+
+=== Multi-namespace document with Type namespaces
+
+.Dublin Core metadata in document
+[example]
+====
+[source,ruby]
+----
+# Define namespaces
+class DocumentNamespace < Lutaml::Model::XmlNamespace
+  uri 'https://example.com/document'
+  prefix_default 'doc'
+end
+
+class DublinCoreNamespace < Lutaml::Model::XmlNamespace
+  uri 'http://purl.org/dc/elements/1.1/'
+  prefix_default 'dc'
+end
+
+# Define DC types with namespaces
+class DcTitleType < Lutaml::Model::Type::String
+  xml do
+    namespace DublinCoreNamespace
+    xsd_type 'titleType'
+  end
+end
+
+class DcCreatorType < Lutaml::Model::Type::String
+  xml do
+    namespace DublinCoreNamespace
+    xsd_type 'creatorType'
+  end
+end
+
+# Use in document model
+class Document < Lutaml::Model::Serializable
+  namespace DocumentNamespace
+  
+  attribute :title, DcTitleType
+  attribute :creator, DcCreatorType
+  attribute :content, :string
+
+  xml do
+    root 'document'
+    
+    map_element 'title', to: :title      # Uses DublinCoreNamespace
+    map_element 'creator', to: :creator  # Uses DublinCoreNamespace
+    map_element 'content', to: :content  # No type namespace
+  end
+end
+
+doc = Document.new(
+  title: 'Example Document',
+  creator: 'John Doe',
+  content: 'Document content'
+)
+
+puts doc.to_xml
+# => <doc:document
+#      xmlns:doc="https://example.com/document"
+#      xmlns:dc="http://purl.org/dc/elements/1.1/">
+#      <dc:title>Example Document</dc:title>
+#      <dc:creator>John Doe</dc:creator>
+#      <content>Document content</content>
+#    </doc:document>
+
+# Round-trip works correctly
+parsed = Document.from_xml(doc.to_xml)
+parsed == doc  # => true
+----
+====
+
+=== Multi-namespace document with consolidated declarations
+
+.Using namespace_scope for cleaner multi-namespace XML
+[example]
+====
+[source,ruby]
+----
+# Define namespaces
+class VcardNamespace < Lutaml::Model::XmlNamespace
+  uri "urn:ietf:params:xml:ns:vcard-4.0"
+  prefix_default "vcard"
+end
+
+class DcNamespace < Lutaml::Model::XmlNamespace
+  uri "http://purl.org/dc/elements/1.1/"
+  prefix_default "dc"
+end
+
+class DctermsNamespace < Lutaml::Model::XmlNamespace
+  uri "http://purl.org/dc/terms/"
+  prefix_default "dcterms"
+end
+
+# Define types with namespaces
+class DcTitleType < Lutaml::Model::Type::String
+  xml do
+    namespace DcNamespace
+  end
+end
+
+class DctermsCreatedType < Lutaml::Model::Type::DateTime
+  xml do
+    namespace DctermsNamespace
+  end
+end
+
+class VcardVersion < Lutaml::Model::Type::String
+  xml do
+    namespace VcardNamespace
+  end
+end
+
+# Use namespace_scope to consolidate declarations
+class Vcard < Lutaml::Model::Serializable
+  namespace VcardNamespace
+
+  attribute :version, VcardVersion
+  attribute :title, DcTitleType
+  attribute :full_name, :string
+  attribute :created, DctermsCreatedType
+
+  xml do
+    root "vCard"
+    namespace_scope [VcardNamespace, DcNamespace, DctermsNamespace]  <1>
+
+    map_element "version", to: :version
+    map_element "title", to: :title
+    map_element "fn", to: :full_name
+    map_element "created", to: :created
+  end
+end
+
+vcard = Vcard.new(
+  version: "4.0",
+  title: "Contact: Dr. John Doe",
+  full_name: "Dr. John Doe",
+  created: DateTime.parse("2024-06-01T12:00:00Z")
+)
+
+puts vcard.to_xml
+# => <vcard:vCard xmlns:vcard="urn:ietf:params:xml:ns:vcard-4.0"
+#                 xmlns:dc="http://purl.org/dc/elements/1.1/"
+#                 xmlns:dcterms="http://purl.org/dc/terms/">
+#      <vcard:version>4.0</vcard:version>
+#      <dc:title>Contact: Dr. John Doe</dc:title>
+#      <vcard:fn>Dr. John Doe</vcard:fn>
+#      <dcterms:created>2024-06-01T12:00:00+00:00</dcterms:created>
+#    </vcard:vCard>
+
+# Round-trip deserialization works
+parsed = Vcard.from_xml(vcard.to_xml)
+parsed == vcard  # => true
+----
+<1> All three namespaces declared at root for cleaner output
+====
+
+== schemaLocation pattern
+
+=== Automatic xsi:schemaLocation
+
+.Using schema_location metadata attribute
+[example]
+====
+[source,ruby]
+----
+class CeramicNamespace < Lutaml::Model::XmlNamespace
+  uri 'http://example.com/ceramic'
+  prefix_default 'cera'
+  element_form_default :qualified
+end
+
+class ColorNamespace < Lutaml::Model::XmlNamespace
+  uri 'http://example.com/color'
+  prefix_default 'clr'
+end
+
+class Ceramic < Lutaml::Model::Serializable
+  attribute :type, :string
+  attribute :glaze, :string
+  attribute :color, :string
+
+  xml do
+    root 'Ceramic'
+    namespace CeramicNamespace
+    map_element 'Type', to: :type  # Inherits parent namespace (qualified)
+    map_element 'Glaze', to: :glaze
+    map_attribute 'color', to: :color  # Per W3C, attributes don't inherit namespace
+  end
+end
+
+xml_content = <<~XML
+<cera:Ceramic
+  xmlns:cera="http://example.com/ceramic"
+  xmlns:clr="http://example.com/color"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  clr:color="navy-blue"
+  xsi:schemaLocation="
+    http://example.com/ceramic http://example.com/ceramic.xsd
+    http://example.com/color http://example.com/color.xsd
+  ">
+  <cera:Type>Porcelain</cera:Type>
+  <Glaze>Clear</Glaze>
+</cera:Ceramic>
+XML
+
+c = Ceramic.from_xml(xml_content)
+schema_loc = c.schema_location  # Automatically captured
+
+# Round-trip with schema location preserved
+new_c = Ceramic.new(
+  type: "Porcelain",
+  glaze: "Clear",
+  color: "navy-blue",
+  schema_location: schema_loc
+)
+puts new_c.to_xml
+# xsi:schemaLocation automatically included
+----
+====