YAML Language Tutorial

Introduction

YAML is a recursive acronym for "YAML Ain't a Markup Language." When this language was being developed, YAML originally stood for "Yet Another Markup Language."

YAML's syntax is similar to other high-level languages, and it can simply express data structures such as lists, hash tables, and scalars. It uses whitespace indentation and relies heavily on visual appearance, making it particularly suitable for expressing or editing data structures, configuration files, debug dumps, and document outlines (for example, many email header formats are very similar to YAML).

YAML configuration files use the .yml extension, such as: runoob.yml.

YAML is commonly used as a configuration file format, similar to JSON.

Basic Syntax

• Case-sensitive

• Uses indentation to represent hierarchy

• Tabs are not allowed for indentation; only spaces

• The number of indentation spaces doesn't matter, as long as elements at the same level are left-aligned

• '#' denotes a comment

Data Types

YAML supports the following data types:

• Objects: Collections of key-value pairs, also known as mappings / hashes / dictionaries
• Arrays: A set of values arranged in order, also known as sequences / lists
• Scalars: Single, indivisible values

YAML Objects

Several ways to represent objects:

1. Object key-value pairs use colon syntax key: value, with a space after the colon.

key: value

2. You can also use key:{key1: value1, key2: value2, ...}.

key:{child-key1:value1,child-key2:value2}

3. Indentation can also represent hierarchy:

key:
    child-key1: value1
    child-key2: value2

Same as 2, just a different representation.

4. For more complex object formats, use a question mark followed by a space to represent a complex key, paired with a colon and space for the value:

?
    - complexkey1
    - complexkey2
:
    - complexvalue1
    - complexvalue2

This means the object's property is an array [complexkey1,complexkey2], and the corresponding value is also an array [complexvalue1,complexvalue2].

YAML Arrays

Lines beginning with - form an array:

- A
- B
- C

YAML supports multi-dimensional arrays, which can be expressed inline:

key: [value1, value2, ...]

When a data structure's child member is an array, indent one space under that item:

-
 - A
 - B
 - C

A more complex example:

companies:
    -
        id: 1
        name: company1
        price: 200W
    -
        id: 2
        name: company2
        price: 500W

This means the companies property is an array, where each element is composed of three properties: id, name, and price.

Arrays can also be expressed using flow style:

companies: [{id: 1,name: company1,price: 200W},{id: 2,name: company2,price: 500W}]

Compound Structures (Objects and Arrays Combined)

Arrays and objects can form compound structures, for example:

languages:
  - Ruby
  - Perl
  - Python
websites:
  YAML: yaml.org
  Ruby: ruby-lang.org
  Python: python.org
  Perl: use.perl.org

Converted to JS:

{
  languages: [ 'Ruby', 'Perl', 'Python'],
  websites: {
    YAML: 'yaml.org',
    Ruby: 'ruby-lang.org',
    Python: 'python.org',
    Perl: 'use.perl.org'
  }
}

Scalars

Scalars are the most basic, indivisible values, including:

• Strings
• Booleans
• Integers
• Floating-point numbers
• Null
• Times
• Dates

A quick overview of basic scalar usage:

boolean: # Boolean
    - TRUE  #true, True also work
    - FALSE  #false, False also work
float: # Floating-point
    - 3.14
    - 6.8523015e+5  #Scientific notation is supported
int: # Integer
    - 123
    - 0b1010_0111_0100_1010_1110    #Binary representation
null: # Null
    nodeName: 'node'
    parent: ~  #Use ~ to represent null
string: # String
    - hello # Strings don't require quotes by default
    - 'Hello world'  #Use double or single quotes to wrap special characters
    - newline
      newline2    #Strings can span multiple lines; each line is converted to a space
date:
    - 2018-02-17    #Dates must use ISO 8601 format: yyyy-MM-dd
datetime:
    -  2018-02-17T15:02:31+08:00    #Times use ISO 8601 format, T connects date and time, + indicates timezone

Multi-line strings can use | to preserve line breaks, or > to fold them.

this: |
  Foo
  Bar
that: >
  Foo
  Bar

Converted to JS code:

{ this: 'Foo\nBar\n', that: 'Foo Bar\n' }

+ preserves trailing newlines in text blocks, - removes trailing newlines.

s1: |
  Foo

s2: |+
  Foo


s3: |-
  Foo

Converted to JSON:

{ s1: 'Foo\n', s2: 'Foo\n\n\n', s3: 'Foo' }

HTML markup can be inserted within strings.

message: |
  <p style="color: red">
    Paragraph
  </p>

Data Type Conversion

Two exclamation marks can be used to force data type conversion.

e: !!str 123
f: !!str true

Converted to JS:

{ e: '123', f: 'true' }

Anchors and Aliases

& anchors and * aliases can be used for referencing:

defaults: &defaults # Add an anchor
  adapter:  postgres
  host:     localhost

development:
  database: myapp_development
  <<: *defaults # << means merge, * references the anchor

test:
  database: myapp_test
  <<: *defaults # << means merge, * references the anchor

Equivalent to:

defaults:
  adapter:  postgres
  host:     localhost

development:
  database: myapp_development
  adapter:  postgres
  host:     localhost

test:
  database: myapp_test
  adapter:  postgres
  host:     localhost

& creates an anchor (defaults), << merges into the current data, and ***** references the anchor.

Here's another example:

- &showell Steve
- Clark
- Brian
- Oren
- *showell

Converted to JS:

[ 'Steve', 'Clark', 'Brian', 'Oren', 'Steve' ]

References:

• YAML official website: https://yaml.org/ (opens new window)
• YAML to JS conversion demo: http://nodeca.github.io/js-yaml/ (opens new window)
• Tutorial: https://www.ruanyifeng.com/blog/2016/07/yaml.html (opens new window)