Introduction

XML is a widely used structured serialization format standardized by the W3C. This tutorial will guide you through your first XML serialization using Lutaml::Model.

At a high level, XML defines the following primitives:

  • XML element (<element-name>content</element-name>)

  • XML attribute (<element-name …​ attribute-name="attribute value">)

Defining a basic model for XML

Setting the element name

In Lutaml::Model, XML serialization mappings are defined using the xml block.

Syntax:

class Example < Lutaml::Model::Serializable
  xml do
    element 'element-name'
  end
end

The element method declares the XML element name (tag name) for your model.

Example 1. Setting the element name to ceramic
class Ceramic < Lutaml::Model::Serializable
  attribute :type, :string

  xml do
    element 'ceramic'
    map_element 'type', to: :type
  end
end

puts Ceramic.new(type: "Porcelain").to_xml
# => <ceramic><type>Porcelain</type></ceramic>

Mapping XML elements

The map_element method maps an XML element to a model attribute.

Syntax:

xml do
  map_element 'xml_element_name', to: :attribute_name
end
Example 2. Complete example: Mapping elements
class Example < Lutaml::Model::Serializable
  attribute :name, :string

  xml do
    root 'example'
    map_element 'name', to: :name
  end
end
<example><name>John Doe</name></example>
> Example.from_xml(xml)
> #<Example:0x0000000104ac7240 @name="John Doe">
> Example.new(name: "John Doe").to_xml
> #<example><name>John Doe</name></example>

Mapping XML attributes

The map_attribute method maps an XML attribute to a model attribute.

Syntax:

xml do
  map_attribute 'xml_attribute_name', to: :attribute_name
end
Example 3. Mapping XML attributes
class Example < Lutaml::Model::Serializable
  attribute :value, :integer

  xml do
    root 'example'
    map_attribute 'value', to: :value
  end
end
<example value="12"></example>
> Example.from_xml(xml)
> #<Example:0x0000000104ac7240 @value=12>
> Example.new(value: 12).to_xml
> #<example value="12"></example>

Mapping element content

The map_content method maps the text content inside an XML element.

Syntax:

xml do
  map_content to: :attribute_name
end
Example 4. Mapping element content
class Example < Lutaml::Model::Serializable
  attribute :description, :string

  xml do
    root 'example'
    map_content to: :description
  end
end
<example>John Doe is my moniker.</example>
> Example.from_xml(xml)
> #<Example:0x0000000104ac7240 @description="John Doe is my moniker.">
> Example.new(description: "John Doe is my moniker.").to_xml
> #<example>John Doe is my moniker.</example>

Complete example

Putting it all together - a model with elements, attributes, and content:

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
<ceramic temperature="1200"><name>Porcelain Vase</name> with celadon glaze.</ceramic>
> Ceramic.from_xml(xml)
> #<Ceramic:0x0000000104ac7240 @name="Porcelain Vase", @description=" with celadon glaze.", @temperature=1200>
> Ceramic.new(name: "Porcelain Vase", description: " with celadon glaze.", temperature: 1200).to_xml
> #<ceramic temperature="1200"><name>Porcelain Vase</name> with celadon glaze.</ceramic>

Next steps

Now that you understand basic XML mapping, you can: