Overview

Lutaml::Model uses an adapter pattern to support multiple serialization libraries. You must configure which adapters to use for each format.

Basic configuration

Use Lutaml::Model::Config.configure to set adapters:

require 'lutaml/model'

Lutaml::Model::Config.configure do |config|
  config.xml_adapter_type = :nokogiri
  config.json_adapter_type = :standard_json
  config.yaml_adapter_type = :standard_yaml
  config.toml_adapter_type = :toml_rb
  config.hash_adapter_type = :standard_hash
end

Available adapters

XML adapters

Adapter Description

:nokogiri (default)

Most compatible, based on libxml2. Requires native extensions.

:ox

Fastest performance. Native C extensions.

:oga

Pure Ruby. No compilation needed. Opal-compatible.

JSON adapters

Adapter Description

:standard_json (default)

Ruby standard library. No extra gems needed.

:multi_json

Common interface wrapper for multiple JSON libraries.

:oj

Fast C-based parser. Excellent performance.

YAML adapter

Adapter Description

:standard_yaml (default)

Psych (Ruby standard library). No extra gems needed.

TOML adapters

Adapter Description

:tomlib (default on non-Windows)

Enhanced fork. Better performance on non-Windows platforms.

:toml_rb (default on Windows)

Pure Ruby. TOML v1.0.0 compatible. Required on Windows.
The :tomlib adapter is not available on Windows due to segmentation fault issues. On Windows, :toml_rb is automatically used as the default.

Configuration with class references

For advanced use, specify adapter classes directly:

require 'lutaml/model'
require 'lutaml/xml/adapter/nokogiri_adapter'
require 'lutaml/json/adapter/standard_adapter'
require 'lutaml/yaml/adapter/standard_adapter'
require 'lutaml/toml/adapter/toml_rb_adapter'

Lutaml::Model::Config.configure do |config|
  config.xml_adapter = Lutaml::Xml::Adapter::NokogiriAdapter
  config.json_adapter = Lutaml::Json::Adapter::StandardAdapter
  config.yaml_adapter = Lutaml::Yaml::Adapter::StandardAdapter
  config.toml_adapter = Lutaml::Toml::Adapter::TomlRbAdapter
end

Default configuration

If not configured, Lutaml::Model uses these defaults:

  • XML: :nokogiri

  • JSON: :standard (or :standard_json as an alias)

  • YAML: :standard (or :standard_yaml as an alias)

  • Hash: :standard (or :standard_hash as an alias)

  • TOML: :tomlib on non-Windows, :toml_rb on Windows

When to configure

Configure adapters in one of these locations:

For applications

In an initializer or early-loading file

For gems

Let end users configure adapters (document the requirement)

For testing

In spec_helper.rb or test setup

Example 1. RSpec configuration example
# spec/spec_helper.rb
require 'lutaml/model'

Lutaml::Model::Config.configure do |config|
  config.xml_adapter_type = :nokogiri
  config.json_adapter_type = :standard_json
  config.yaml_adapter_type = :standard_yaml
  config.toml_adapter_type = :toml_rb
end

Adapter selection guide

Choose XML adapter based on

  • Nokogiri: Most projects (default, best compatibility)

  • Ox: Performance-critical applications

  • Oga: Pure Ruby environments, Opal/JavaScript compilation

Choose JSON adapter based on

  • Standard JSON: Most projects (default, built-in)

  • Oj: High-performance requirements

  • MultiJson: Legacy codebases using MultiJson

Choose TOML adapter based on

  • Tomlib: Most projects on non-Windows (better performance)

  • TomlRb: Windows platforms (required due to tomlib incompatibility)

See also