@zio.dev/zio-blocks 0.0.27 → 0.0.28

package/reference/xml.md

@@ -3,10 +3,31 @@ id: xml
 title: "XML"
 ---
 
-Zero-dependency XML codec for ZIO Blocks Schema with cross-platform support.
+`Xml` is a **sealed trait representing XML nodes**. It provides a type-safe, immutable representation of all valid XML document structures including elements, text nodes, CDATA sections, comments, and processing instructions.
+
+```scala
+sealed trait Xml {
+  def xmlType: XmlType
+  def is(xmlType: XmlType): Boolean
+  def as(xmlType: XmlType): Option[xmlType.Type]
+  def unwrap(xmlType: XmlType): Option[xmlType.Unwrap]
+  def print: String
+  def printPretty: String
+  def select: XmlSelection
+}
+```
+
+`Xml` supports:
+- Type-safe representation of all XML node types
+- Fluent navigation and querying with XmlSelection
+- Schema-derived automatic codec generation
+- Zero external dependencies
+- Full cross-platform support (JVM and Scala.js)
 
 ## Overview
 
+Zero-dependency XML codec for ZIO Blocks Schema with cross-platform support.
+
 The schema-xml module provides automatic XML codec derivation for any type with a `Schema`. It includes a complete XML AST, fluent navigation API, and support for XML-specific features like attributes and namespaces.
 
 Key features:
@@ -21,14 +42,20 @@ Key features:
 
 ## Installation
 
+To use the schema-xml module, add the following dependency to your `build.sbt`:
+
 ```scala
 libraryDependencies += "dev.zio" %% "zio-blocks-schema-xml" % "0.0.14"
 ```
 
 ## Basic Usage
 
+Start by deriving an XML codec from your Schema definition:
+
 ### Deriving Codecs
 
+To create an XML codec, use `Schema[A].derive(XmlFormat)`:
+
 ```scala
 import zio.blocks.schema._
 import zio.blocks.schema.xml._
@@ -45,6 +72,8 @@ val codec = Schema[Person].derive(XmlFormat)
 
 ### Encoding to XML
 
+Encode your values to XML using the codec:
+
 ```scala
 import zio.blocks.schema._
 import zio.blocks.schema.xml._
@@ -56,24 +85,85 @@ object Person {
 
 val codec = Schema[Person].derive(XmlFormat)
 val person = Person("Alice", 30)
+```
+
+Encode to XML bytes:
 
-// Encode to XML bytes
+```scala
 val bytes: Array[Byte] = codec.encode(person)
+// bytes: Array[Byte] = Array(
+//   60,
+//   80,
+//   101,
+//   114,
+//   115,
+//   111,
+//   110,
+//   62,
+//   60,
+//   110,
+//   97,
+//   109,
+//   101,
+//   62,
+//   65,
+//   108,
+//   105,
+//   99,
+//   101,
+//   60,
+//   47,
+//   110,
+//   97,
+//   109,
+//   101,
+//   62,
+//   60,
+//   97,
+//   103,
+//   101,
+//   62,
+//   51,
+//   48,
+//   60,
+//   47,
+//   97,
+//   103,
+//   101,
+//   62,
+//   60,
+//   47,
+//   80,
+//   101,
+//   114,
+//   115,
+//   111,
+//   110,
+//   62
+// )
+```
 
-// Encode to XML string
+Encode to XML string:
+
+```scala
 val xmlString: String = codec.encodeToString(person)
-// <Person><name>Alice</name><age>30</age></Person>
+// xmlString: String = "<Person><name>Alice</name><age>30</age></Person>"
+```
 
-// Encode to pretty-printed XML
+Encode to pretty-printed XML:
+
+```scala
 val prettyXml = codec.encodeToString(person, WriterConfig.pretty)
-// <Person>
+// prettyXml: String = """<Person>
 //   <name>Alice</name>
 //   <age>30</age>
-// </Person>
+// </Person>"""
 ```
 
 ### Decoding from XML
 
+Decode XML strings or bytes back to your typed values:
+
 ```scala
 import zio.blocks.schema._
 import zio.blocks.schema.xml._
@@ -87,12 +177,28 @@ val codec = Schema[Person].derive(XmlFormat)
 
 // Decode from XML string
 val xml = "<Person><name>Alice</name><age>30</age></Person>"
+```
+
+Decode the XML string and see the result:
+
+```scala
 val result: Either[SchemaError, Person] = codec.decode(xml)
-// Right(Person("Alice", 30))
+// result: Either[SchemaError, Person] = Right(
+//   Person(name = "Alice", age = 30)
+// )
+```
 
-// Decode from bytes
+You can also decode from bytes:
+
+```scala
 val bytes = xml.getBytes("UTF-8")
+```
+
+```scala
 val fromBytes: Either[SchemaError, Person] = codec.decode(bytes)
+// fromBytes: Either[SchemaError, Person] = Right(
+//   Person(name = "Alice", age = 30)
+// )
 ```
 
 ## XML AST
@@ -110,6 +216,8 @@ Xml
 
 ### Creating XML Nodes
 
+Construct XML nodes directly using the case class constructors:
+
 ```scala
 import zio.blocks.schema.xml._
 import zio.blocks.chunk.Chunk
@@ -136,7 +244,7 @@ val pi = Xml.ProcessingInstruction("xml-stylesheet", "href=\"style.css\"")
 
 ### XmlName
 
-`XmlName` represents an element or attribute name with optional namespace:
+`XmlName` represents an element or attribute name with optional namespace. Create instances with different namespace configurations:
 
 ```scala
 import zio.blocks.schema.xml.XmlName
@@ -185,9 +293,11 @@ val commentNode = XmlBuilder.comment("comment text")
 
 ## Configuration
 
+The schema-xml module provides configuration options for both parsing and writing:
+
 ### WriterConfig
 
-Controls XML output formatting:
+Use `WriterConfig` to control XML output formatting:
 
 ```scala
 import zio.blocks.schema.xml.WriterConfig
@@ -268,11 +378,13 @@ object Person {
 
 val codec = Schema[Person].derive(XmlFormat)
 val person = Person("123", "active", "Alice", 30)
+```
+
+Encode the person with attributes:
+
+```scala
 val xml = codec.encodeToString(person)
-// <Person id="123" status="active">
-//   <name>Alice</name>
-//   <age>30</age>
-// </Person>
+// xml: String = "<Person><id>123</id><active>active</active><name>Alice</name><age>30</age></Person>"
 ```
 
 The `@xmlAttribute` annotation accepts an optional custom name:
@@ -300,19 +412,18 @@ object Feed {
 
 val codec = Schema[Feed].derive(XmlFormat)
 val feed = Feed("My Blog", "2024-01-01T00:00:00Z")
+```
+
+Encode the feed with a namespace prefix:
+
+```scala
 val xml = codec.encodeToString(feed)
-// <atom:Feed xmlns:atom="http://www.w3.org/2005/Atom">
-//   <title>My Blog</title>
-//   <updated>2024-01-01T00:00:00Z</updated>
-// </atom:Feed>
+// xml: String = "<Feed><title>My Blog</title><updated>2024-01-01T00:00:00Z</updated></Feed>"
 ```
 
 Without a prefix (default namespace):
 
 ```scala
-import zio.blocks.schema._
-import zio.blocks.schema.xml._
-
 @xmlNamespace(uri = "http://www.w3.org/2005/Atom")
 case class Feed(title: String)
 
@@ -322,10 +433,13 @@ object Feed {
 
 val codec = Schema[Feed].derive(XmlFormat)
 val feed = Feed("My Blog")
+```
+
+Encode the feed with default namespace:
+
+```scala
 val xml = codec.encodeToString(feed)
-// <Feed xmlns="http://www.w3.org/2005/Atom">
-//   <title>My Blog</title>
-// </Feed>
+// xml: String = "<Feed><title>My Blog</title></Feed>"
 ```
 
 ## XmlSelection
@@ -334,6 +448,8 @@ val xml = codec.encodeToString(feed)
 
 ### Navigation
 
+Navigate to child elements, filter by type, and extract content:
+
 ```scala
 import zio.blocks.schema.xml._
 
@@ -357,17 +473,43 @@ val books = xml.select.get("library").get("books")
 
 // Navigate by index
 val firstBook = books.get("book")(0)
+```
 
-// Extract text content
+Extract text content from the first book:
+
+```scala
 val title: Either[XmlError, String] = firstBook.get("title").text
-// Right("Functional Programming")
+// title: Either[XmlError, String] = Left(
+//   zio.blocks.schema.xml.XmlError: Expected single value but got 0
+// )
+```
+
+You can also navigate descendants recursively:
 
-// Navigate descendants (recursive search)
+```scala
 val allTitles = xml.select.descendant("title")
+// allTitles: XmlSelection = XmlSelection(
+//   Right(
+//     IndexedSeq(
+//       Element(
+//         name = XmlName(localName = "title", prefix = None, namespace = None),
+//         attributes = IndexedSeq(),
+//         children = IndexedSeq(Text("Functional Programming"))
+//       ),
+//       Element(
+//         name = XmlName(localName = "title", prefix = None, namespace = None),
+//         attributes = IndexedSeq(),
+//         children = IndexedSeq(Text("Advanced Scala"))
+//       )
+//     )
+//   )
+// )
 ```
 
 ### Filtering
 
+Filter selections by node type or custom predicates:
+
 ```scala
 import zio.blocks.schema.xml._
 
@@ -384,6 +526,8 @@ val filtered = selection.filter(xml => xml.is(XmlType.Element))
 
 ### Terminal Operations
 
+Execute a selection to extract values or convert to other formats:
+
 ```scala
 import zio.blocks.schema.xml._
 
@@ -408,6 +552,8 @@ val allText: String = selection.textContent
 
 ### Combinators
 
+Combine and transform selections using monadic operations:
+
 ```scala
 import zio.blocks.schema.xml._
 
@@ -433,6 +579,8 @@ val withFallback = selection1.orElse(selection2)
 
 ### Creating Patches
 
+Create patches for add, remove, replace, and attribute operations:
+
 ```scala
 import zio.blocks.schema._
 import zio.blocks.schema.xml._
@@ -464,6 +612,8 @@ val removeAttrPatch = XmlPatch.removeAttribute(path, "id")
 
 ### Position Options
 
+Position options control where new content is inserted relative to the target:
+
 ```scala
 import zio.blocks.schema.xml.XmlPatch.Position
 
@@ -475,6 +625,8 @@ Position.AppendChild    // Insert as last child of target
 
 ### Applying Patches
 
+Apply a patch to an XML document to produce a modified result:
+
 ```scala
 import zio.blocks.schema._
 import zio.blocks.schema.xml._
@@ -488,6 +640,8 @@ val result: Either[XmlError, Xml] = patch(xml)
 
 ### Composing Patches
 
+Combine multiple patches to apply transformations in sequence:
+
 ```scala
 import zio.blocks.schema._
 import zio.blocks.schema.xml._
@@ -503,6 +657,175 @@ val patch2 = XmlPatch.add(
 val combined = patch1 ++ patch2
 ```
 
+## XmlEncoder and XmlDecoder
+
+For more fine-grained control over XML serialization, use the separate `XmlEncoder` and `XmlDecoder` traits:
+
+### XmlEncoder
+
+`XmlEncoder[A]` provides type-safe XML encoding:
+
+```scala
+import zio.blocks.schema._
+import zio.blocks.schema.xml._
+
+// Automatic derivation from Schema
+case class Person(name: String, age: Int)
+object Person {
+  implicit val schema: Schema[Person] = Schema.derived
+  implicit val encoder: XmlEncoder[Person] = XmlEncoder.fromSchema
+}
+
+val person = Person("Alice", 30)
+val xml: Xml = XmlEncoder[Person].encode(person)
+```
+
+#### Creating custom encoders
+
+Create custom encoders from functions or using contravariance:
+
+```scala
+import zio.blocks.schema.xml._
+
+// Create from a function
+val customEncoder: XmlEncoder[Int] = XmlEncoder.instance(n =>
+  Xml.Element("number", Xml.Text(n.toString))
+)
+
+// Map with contravariance - encode a wrapper type
+case class UserId(value: Int)
+
+val userIdEncoder: XmlEncoder[UserId] =
+  customEncoder.contramap[UserId](_.value)
+```
+
+#### Using implicit resolution
+
+Leverage implicit resolution for automatic encoder derivation:
+
+```scala
+import zio.blocks.schema._
+import zio.blocks.schema.xml._
+
+case class Product(id: String, price: Double)
+object Product {
+  implicit val schema: Schema[Product] = Schema.derived
+}
+
+// No explicit encoder needed - derives automatically
+def encodeProduct[A](value: A)(implicit encoder: XmlEncoder[A]): Xml =
+  encoder.encode(value)
+
+val result = encodeProduct(Product("item-1", 99.99))
+```
+
+### XmlDecoder
+
+`XmlDecoder[A]` provides type-safe XML decoding with error handling:
+
+```scala
+import zio.blocks.schema._
+import zio.blocks.schema.xml._
+
+// Automatic derivation from Schema
+case class Person(name: String, age: Int)
+object Person {
+  implicit val schema: Schema[Person] = Schema.derived
+  implicit val decoder: XmlDecoder[Person] = XmlDecoder.fromSchema
+}
+
+val xml = Xml.Element("Person",
+  Xml.Element("name", Xml.Text("Alice")),
+  Xml.Element("age", Xml.Text("30"))
+)
+```
+
+Decode the XML:
+
+```scala
+val result: Either[XmlError, Person] = XmlDecoder[Person].decode(xml)
+// result: Either[XmlError, Person] = Right(Person(name = "Alice", age = 30))
+```
+
+#### Creating custom decoders
+
+Create custom decoders from functions or using covariance:
+
+```scala
+import zio.blocks.schema.xml._
+import zio.blocks.chunk.Chunk
+
+// Create from a function
+val numberDecoder: XmlDecoder[Int] = XmlDecoder.instance { xml =>
+  xml match {
+    case Xml.Element(_, _, Chunk(Xml.Text(text), _*)) =>
+      text.toIntOption.toRight(XmlError("Invalid number"))
+    case _ => Left(XmlError("Expected number element"))
+  }
+}
+
+// Map for covariance - decode to a wrapper type
+case class UserId(value: Int)
+
+val userIdDecoder: XmlDecoder[UserId] =
+  numberDecoder.map(UserId(_))
+```
+
+#### Error handling with decoders
+
+Handle decoding errors gracefully with fallback strategies:
+
+```scala
+import zio.blocks.schema._
+import zio.blocks.schema.xml._
+
+case class Person(name: String, age: Int)
+object Person {
+  implicit val schema: Schema[Person] = Schema.derived
+}
+
+def decodeWithFallback[A](
+  xml: Xml,
+  fallback: A
+)(implicit decoder: XmlDecoder[A]): A = {
+  decoder.decode(xml).getOrElse(fallback)
+}
+
+val invalidXml = Xml.Element("Empty")
+val defaultPerson = Person("Unknown", 0)
+val result = decodeWithFallback(invalidXml, defaultPerson)
+// Person("Unknown", 0)
+```
+
+#### Combining encoders and decoders
+
+Round-trip values by encoding and decoding:
+
+```scala
+import zio.blocks.schema._
+import zio.blocks.schema.xml._
+import zio.blocks.schema.xml.syntax._
+
+case class Message(id: String, text: String)
+object Message {
+  implicit val schema: Schema[Message] = Schema.derived
+}
+
+// Round-trip: encode then decode
+val message = Message("msg-1", "Hello")
+val encoded: Xml = message.toXml
+```
+
+Decode the encoded value:
+
+```scala
+val result: Either[XmlError, Message] =
+  implicitly[XmlDecoder[Message]].decode(encoded)
+// result: Either[XmlError, Message] = Right(
+//   Message(id = "msg-1", text = "Hello")
+// )
+```
+
 ## Extension Syntax
 
 When a `Schema` is in scope, use convenient extension methods:
@@ -539,29 +862,40 @@ val fromBytes: Either[SchemaError, Person] = bytes.fromXml[Person]
 
 ## Printing XML
 
-### Basic Printing
+Format XML documents using compact or pretty-printed output. You can convert XML to string with different formatting options:
 
 ```scala
 import zio.blocks.schema.xml._
 
 val xml = Xml.Element("person", Xml.Element("name", Xml.Text("Alice")))
+```
 
-// Compact output
+Compact output:
+
+```scala
 val compact: String = xml.print
-// <person><name>Alice</name></person>
+// compact: String = "<person><name>Alice</name></person>"
+```
 
-// Pretty-printed output
+Pretty-printed output:
+
+```scala
 val pretty: String = xml.printPretty
-// <person>
+// pretty: String = """<person>
 //   <name>Alice</name>
-// </person>
+// </person>"""
+```
 
-// Custom configuration
+Custom configuration:
+
+```scala
 val custom: String = xml.print(WriterConfig(indentStep = 4))
 ```
 
 ## Type Testing and Access
 
+Test and extract values from XML nodes using type guards and unwrapping:
+
 ```scala
 import zio.blocks.schema.xml._
 
@@ -608,9 +942,43 @@ All standard ZIO Blocks Schema types are supported:
 - Options (`Option[A]`)
 - Wrappers (newtypes)
 
+## XmlBinaryCodec
+
+`XmlBinaryCodec[A]` is the low-level codec interface that bridges Schema definitions with XML serialization. While usually derived automatically, you can work with it directly:
+
+```scala
+import zio.blocks.schema._
+import zio.blocks.schema.xml._
+
+case class Person(name: String, age: Int)
+object Person {
+  implicit val schema: Schema[Person] = Schema.derived
+}
+
+// Get the underlying binary codec
+val codec: XmlBinaryCodec[Person] =
+  Schema[Person].derive(XmlBinaryCodecDeriver)
+
+// Encode to Xml directly
+val person = Person("Alice", 30)
+val xml: Xml = codec.encodeValue(person)
+
+// Decode from Xml directly
+val decoded: Either[XmlError, Person] = codec.decodeValue(xml)
+```
+
+**XmlBinaryCodec supports all Schema types:**
+- Primitives (Int, String, Boolean, etc.)
+- Java time types (Instant, LocalDate, Duration, etc.)
+- Records (case classes with field-level configuration)
+- Variants (sealed traits with discriminators)
+- Collections (List, Vector, Map, etc.)
+- Optional fields (Option[A])
+- Custom wrappers and dynamic values
+
 ## Error Handling
 
-All decoding operations return `Either[SchemaError, A]` or `Either[XmlError, A]`:
+All decoding operations return `Either[SchemaError, A]` or `Either[XmlError, A]`. The `XmlError` type provides detailed error information:
 
 ```scala
 import zio.blocks.schema._
@@ -629,12 +997,45 @@ val result = codec.decode(invalid)
 
 result match {
   case Right(person) => println(s"Decoded: $person")
-  case Left(error) => 
+  case Left(error) =>
     println(s"Error: ${error.getMessage}")
     // Error information includes parse location and context
 }
 ```
 
+`XmlError` provides detailed error information for debugging:
+
+```scala
+import zio.blocks.schema.xml._
+
+val error = XmlError("Parse failed")
+
+// Error message
+val message: String = error.getMessage
+
+// Get error message for inspection
+val errorMsg: String = error.getMessage
+```
+
+Error handling best practices:
+
+```scala
+import zio.blocks.schema._
+import zio.blocks.schema.xml._
+
+case class Config(database: String, port: Int)
+object Config {
+  implicit val schema: Schema[Config] = Schema.derived
+}
+
+def loadConfig(xml: String): Either[String, Config] = {
+  val codec = Schema[Config].derive(XmlFormat)
+  codec.decode(xml).left.map { error =>
+    s"Configuration error: ${error.getMessage}\nCheck XML format and required fields."
+  }
+}
+```
+
 ## Cross-Platform Support
 
 The XML module works across all platforms:
@@ -646,8 +1047,12 @@ All features including parsing, writing, navigation, and patching work identical
 
 ## Examples
 
+These examples demonstrate common use cases and patterns with the XML module:
+
 ### Complete Example with Attributes and Namespaces
 
+Define a schema with attributes and namespaces, then encode and decode:
+
 ```scala
 import zio.blocks.schema._
 import zio.blocks.schema.xml._
@@ -675,26 +1080,41 @@ val entry = Entry(
   updated = "2024-01-01T00:00:00Z",
   author = Author("Alice", "alice@example.com")
 )
+```
 
-// Encode with pretty printing
-val xml = codec.encodeToString(entry, WriterConfig.pretty)
-println(xml)
-// <atom:Entry xmlns:atom="http://www.w3.org/2005/Atom" id="entry-1">
+Encode the entry with pretty printing:
+
+```scala
+val xmlStr = codec.encodeToString(entry, WriterConfig.pretty)
+// xmlStr: String = """<Entry>
+//   <id>entry-1</id>
 //   <title>First Post</title>
 //   <updated>2024-01-01T00:00:00Z</updated>
 //   <author>
 //     <name>Alice</name>
 //     <email>alice@example.com</email>
 //   </author>
-// </atom:Entry>
+// </Entry>"""
+```
+
+Decode the XML back to a typed value:
 
-// Decode back to typed value
-val decoded = codec.decode(xml)
-// Right(Entry("entry-1", "First Post", "2024-01-01T00:00:00Z", Author("Alice", "alice@example.com")))
+```scala
+val decoded = codec.decode(xmlStr)
+// decoded: Either[SchemaError, Entry] = Right(
+//   Entry(
+//     id = "entry-1",
+//     title = "First Post",
+//     updated = "2024-01-01T00:00:00Z",
+//     author = Author(name = "Alice", email = "alice@example.com")
+//   )
+// )
 ```
 
 ### Navigation and Transformation
 
+Find elements, extract data, and apply patches to modify XML:
+
 ```scala
 import zio.blocks.schema._
 import zio.blocks.schema.xml._
@@ -741,3 +1161,144 @@ val patch = XmlPatch.add(
 
 val updated = patch(xml)
 ```
+
+## Real-World Examples
+
+Learn by examining practical examples of XML codecs in action:
+
+### RSS Feed Parsing
+
+Parse RSS feeds by defining a schema and decoding XML:
+
+```scala
+import zio.blocks.schema._
+import zio.blocks.schema.xml._
+
+@xmlNamespace(uri = "http://www.rss.org/", prefix = "rss")
+case class Item(
+  @xmlAttribute() guid: String,
+  title: String,
+  link: String,
+  pubDate: String,
+  description: String
+)
+
+@xmlNamespace(uri = "http://www.rss.org/", prefix = "rss")
+case class Channel(
+  title: String,
+  link: String,
+  description: String,
+  items: List[Item]
+)
+
+object Channel {
+  implicit val itemSchema: Schema[Item] = Schema.derived
+  implicit val schema: Schema[Channel] = Schema.derived
+}
+
+// Parse RSS feed from string
+val feedXml = """<rss:Channel xmlns:rss="http://www.rss.org/">
+  <title>Tech Blog</title>
+  <link>https://example.com</link>
+  <description>Latest tech articles</description>
+  <items>
+    <Item guid="1">
+      <title>Functional Programming in Scala</title>
+      <link>https://example.com/fp</link>
+      <pubDate>2024-01-01</pubDate>
+      <description>Deep dive into FP concepts</description>
+    </Item>
+  </items>
+</rss:Channel>"""
+
+val codec = Schema[Channel].derive(XmlFormat)
+val result: Either[SchemaError, Channel] = codec.decode(feedXml)
+```
+
+### Atom Feed with Advanced Features
+
+Work with Atom feeds using attributes, multiple entries, and custom configurations:
+
+```scala
+import zio.blocks.schema._
+import zio.blocks.schema.xml._
+
+@xmlNamespace(uri = "http://www.w3.org/2005/Atom", prefix = "atom")
+case class Entry(
+  @xmlAttribute() id: String,
+  title: String,
+  author: String,
+  updated: String,
+  @xmlAttribute("href") link: String
+)
+
+@xmlNamespace(uri = "http://www.w3.org/2005/Atom", prefix = "atom")
+case class Feed(
+  @xmlAttribute() id: String,
+  title: String,
+  updated: String,
+  entries: List[Entry]
+)
+
+object Feed {
+  implicit val entrySchema: Schema[Entry] = Schema.derived
+  implicit val schema: Schema[Feed] = Schema.derived
+}
+
+// Encode feed to XML with custom formatting
+val feed = Feed(
+  id = "urn:uuid:60a76c80-d399-11d9-b91C-0003939e0af6",
+  title = "Example Feed",
+  updated = "2024-01-01T18:30:02Z",
+  entries = List(
+    Entry(
+      id = "urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a",
+      title = "Atom-Powered Robots Run Amok",
+      author = "John Doe",
+      updated = "2024-01-01T18:30:02Z",
+      link = "http://example.org/2024/01/entry"
+    )
+  )
+)
+
+val codec = Schema[Feed].derive(XmlFormat)
+val xmlOutput = codec.encodeToString(feed, WriterConfig.pretty)
+```
+
+### Sitemap XML
+
+Generate sitemap XML with URLs and optional metadata fields:
+
+```scala
+import zio.blocks.schema._
+import zio.blocks.schema.xml._
+
+case class Url(
+  loc: String,
+  lastmod: Option[String],
+  changefreq: Option[String],
+  priority: Option[Double]
+)
+
+case class Urlset(
+  urls: List[Url]
+)
+
+object Urlset {
+  implicit val urlSchema: Schema[Url] = Schema.derived
+  implicit val schema: Schema[Urlset] = Schema.derived
+}
+
+// Build and encode sitemap
+val sitemap = Urlset(List(
+  Url("https://example.com", Some("2024-01-01"), Some("monthly"), Some(1.0)),
+  Url("https://example.com/about", Some("2024-01-01"), Some("monthly"), Some(0.8)),
+  Url("https://example.com/contact", None, Some("monthly"), Some(0.5))
+))
+
+val codec = Schema[Urlset].derive(XmlFormat)
+val sitemapXml = codec.encodeToString(sitemap, WriterConfig(
+  indentStep = 2,
+  includeDeclaration = true
+))
+```