Introduction to yaml

The hardware and bandwidth for this mirror is donated by dogado GmbH, the Webhosting and Full Service-Cloud Provider. Check out our Wordpress Tutorial.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]dogado.de.

What is YAML?

YAML is a human-readable data serialization language. With it, you can create easily readable documents that can be consumed by a variety of programming languages.

For example, here’s a map of baseball teams per league:

american:
- Boston Red Sox
- Detroit Tigers
- New York Yankees
national:
- New York Mets
- Chicago Cubs
- Atlanta Braves

And a data dictionary specification:

- field: ID
  description: primary identifier
  type: integer
  primary key: yes
- field: DOB
  description: date of birth
  type: date
  format: yyyy-mm-dd
- field: State
  description: state of residence
  type: string

Parsing YAML

yaml.load() parses a YAML document from a string:

yaml.load("
- 1
- 2
- 3
")
#> [1] 1 2 3

yaml.load_file() and read_yaml() read YAML from a file or connection.

Scalars

A YAML scalar is the basic building block of YAML documents. The parser automatically determines the type:

yaml.load("1.2345")
#> [1] 1.2345
yaml.load("true")
#> [1] TRUE
yaml.load("hello")
#> [1] "hello"

Sequences

A YAML sequence is a list of elements. If all elements are uniform, yaml.load() returns a vector of that type. Otherwise, it returns a list:

# Uniform sequence -> vector
yaml.load("
- 1
- 2
- 3
")
#> [1] 1 2 3

# Mixed sequence -> list
yaml.load("
- 1
- hello
- true
")
#> [[1]]
#> [1] 1
#> 
#> [[2]]
#> [1] "hello"
#> 
#> [[3]]
#> [1] TRUE

Maps

A YAML map is a list of paired keys and values. By default, yaml.load() returns a named list:

yaml.load("
one: 1
two: 2
three: 3
")
#> $one
#> [1] 1
#> 
#> $two
#> [1] 2
#> 
#> $three
#> [1] 3

Since YAML map keys can be almost anything (not just strings), you can preserve the data type of keys with as.named.list = FALSE. This creates a keys attribute instead of coercing keys to strings:

yaml.load("
1: one
2: two
", as.named.list = FALSE)
#> [[1]]
#> [1] "one"
#> 
#> [[2]]
#> [1] "two"
#> 
#> attr(,"keys")
#> attr(,"keys")[[1]]
#> [1] 1
#> 
#> attr(,"keys")[[2]]
#> [1] 2

Custom handlers

You can customize parsing with handler functions. Handlers are passed to yaml.load() as a named list, where each name is the YAML type to handle:

# Add 100 to all integers
yaml.load("123", handlers = list(int = function(x) as.integer(x) + 100))
#> [1] 223

Sequence handlers

Sequence handlers receive a list and can transform it:

yaml.load("
- 1
- 2
- 3
", handlers = list(seq = function(x) sum(as.numeric(x))))
#> [1] 6

Map handlers

Map handlers receive a named list (or a list with a keys attribute):

yaml.load("
a:
- 1
- 2
b:
- 3
- 4
", handlers = list(map = function(x) as.data.frame(x)))
#>   a b
#> 1 1 3
#> 2 2 4

Emitting YAML

as.yaml() converts R objects to YAML strings:

cat(as.yaml(1:5))
#> - 1
#> - 2
#> - 3
#> - 4
#> - 5

write_yaml() writes the result directly to a file or connection.

Formatting options

indent

Control indentation depth (default is 2):

cat(as.yaml(list(foo = list(bar = "baz")), indent = 4))
#> foo:
#>     bar: baz

indent.mapping.sequence

By default, sequences within a mapping are not indented:

cat(as.yaml(list(foo = 1:3)))
#> foo:
#> - 1
#> - 2
#> - 3

Set indent.mapping.sequence = TRUE to indent them:

cat(as.yaml(list(foo = 1:3), indent.mapping.sequence = TRUE))
#> foo:
#>   - 1
#>   - 2
#>   - 3

column.major

Controls how data frames are converted. When TRUE (default), data frames are emitted column-wise:

x <- data.frame(a = 1:2, b = 3:4)
cat(as.yaml(x, column.major = TRUE))
#> a:
#> - 1
#> - 2
#> b:
#> - 3
#> - 4

When FALSE, data frames are emitted row-wise:

cat(as.yaml(x, column.major = FALSE))
#> - a: 1
#>   b: 3
#> - a: 2
#>   b: 4

Custom handlers

Specify custom handler functions for R object classes:

cat(as.yaml(
  Sys.Date(),
  handlers = list(Date = function(x) format(x, "%Y/%m/%d"))
))
#> 2025/12/08

YAML 1.2 logical handling

For YAML 1.2-like logical output, use verbatim_logical:

cat(as.yaml(c(TRUE, FALSE), handlers = list(logical = verbatim_logical)))
#> - true
#> - false

Verbatim text

Character vectors with class "verbatim" are not quoted except when required by the YAML specification:

result <- c("true", "false")
class(result) <- "verbatim"
cat(as.yaml(result))
#> - true
#> - false

Quoted strings

Force quoting with the "quoted" attribute:

port <- "80:80"
attr(port, "quoted") <- TRUE
cat(as.yaml(list(ports = list(port))))
#> ports:
#> - "80:80"

Custom tags

Set YAML tags with the "tag" attribute:

x <- 1:3
attr(x, "tag") <- "!custom"
cat(as.yaml(x))
#> !custom
#> - 1
#> - 2
#> - 3

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.
Health stats visible at Monitor.