YAML

The YAML module provides utilities for parsing and generating YAML (YAML Ain’t Markup Language) data. It’s part of Ruby’s standard library and serves as an interface to the Psych library, which is the actual YAML engine for Ruby.

Overview

YAML is a human-friendly data serialization format commonly used for configuration files, data exchange, and object persistence. Ruby’s YAML module converts between Ruby objects and YAML strings:

• Parse: Convert YAML strings into Ruby objects
• Generate: Convert Ruby objects into YAML strings

Loading YAML

YAML.load converts a YAML string into Ruby data structures.

require 'yaml'

yaml_string = <<~YAML
  name: Alice
  age: 30
  active: true
  tags:
    - ruby
    - developer
YAML

hash = YAML.load(yaml_string)
hash["name"]    # => "Alice"
hash["age"]     # => 30
hash["tags"]    # => ["ruby", "developer"]

YAML.load Parameters

Parameter	Type	Default	Description
string	String	Required	The YAML string to parse
filename	String	nil	Filename for error messages
fallback	Object	false	Value to return if string is nil/empty

Load Options

# Load multiple documents (returns array)
YAML.load("---\nfoo\n---\nbar\n", permitted_classes: [Date])

# Safe loading (Ruby 3.1+)
YAML.load(yaml_string, permitted_classes: [Date], permitted_symbols: [], aliases: false)

Security Warning: Never use YAML.load with untrusted data. This can execute arbitrary code. Use YAML.safe_load instead for untrusted input.

YAML.safe_load

require 'yaml'

# Safe loading with whitelist
safe_yaml = YAML.safe_load(untrusted_input, 
  permitted_classes: [Date, Symbol],
  permitted_symbols: [],
  aliases: false
)

Parameter	Type	Default	Description
string	String	Required	The YAML string to parse
permitted_classes	Array	[]	Whitelist of allowed classes
permitted_symbols	Array	[]	Whitelist of allowed symbols
aliases	Boolean	false	Whether to allow aliases

Dumping to YAML

YAML.dump converts Ruby objects into YAML strings.

require 'yaml'

data = { 
  name: "Bob", 
  age: 25, 
  skills: ["ruby", "rails"] 
}

yaml_string = YAML.dump(data)
# => "---\n:name: Bob\n:age: 25\n:skills:\n- ruby\n- rails\n"

YAML.dump Parameters

Parameter	Type	Default	Description
object	Object	Required	Ruby object to convert
io	IO	nil	Output stream (optional)
opts	Hash	{}	Dumping options

Dump Options

# Pretty-printed output
puts YAML.dump({ name: "Carol", items: [1, 2, 3] })
# => ---
# :name: Carol
# :items:
# - 1
# - 2
# - 3

# Indentation
YAML.dump({ a: { b: { c: 1 } } }, indent: 4)

You can also use the alias YAML.generate:

YAML.dump({ key: "value" })
YAML.generate({ key: "value" })  # Same thing

Parsing YAML

YAML.parse parses YAML into a generic AST representation rather than Ruby objects.

require 'yaml'

ast = YAML.parse("{ name: Alice, age: 30 }")
# => #<Psych::Nodes::Mapping ...>

ast.children[0].value  # => "name"
ast.children[1].value  # => "Alice"

This is useful when you need to inspect the YAML structure without converting to Ruby objects.

YAML.parse Parameters

Parameter	Type	Default	Description
string	String	Required	The YAML string to parse
filename	String	nil	Filename for error messages

Practical Examples

Configuration Files

require 'yaml'

# Read config
config = YAML.load_file('config.yml')

# Write config
File.write('config.yml', YAML.dump({ database: { host: "localhost", port: 5432 } }))

Object Serialization

require 'yaml'

class User
  attr_accessor :name, :email
  
  def initialize(name, email)
    @name = name
    @email = email
  end
end

user = User.new("Dan", "dan@example.com")
yaml_string = YAML.dump(user)
# => !ruby/object:User
# :name: Dan
# :email: dan@example.com

# Load back
loaded = YAML.load(yaml_string)
loaded.name  # => "Dan"

Loading Multiple Documents

require 'yaml'

multi_doc = <<~YAML
  ---
  name: First
  ---
  name: Second
  ---
  name: Third
YAML

documents = YAML.load_stream(multi_doc)
documents.each { |doc| puts doc["name"] }
# First
# Second
# Third

Ruby Version History

• Ruby 1.8: Introduced YAML module with Syck engine
• Ruby 2.0: Removed Syck, Psych became the default
• Ruby 3.1: Added permitted_classes and permitted_symbols parameters to safe_load

See Also

• Date
• Time
• JSON