Master YAML: A Beginner’s Guide to Readable Data Serialization

YAML is a data‑serialization standard that works with any programming language and is prized for its readability.

What is YAML?

YAML is commonly used for writing configuration files, and many systems and frameworks adopt it for that purpose.

Simple YAML Example

title: yaml test
date: 2016/08/06
content: hello yaml

This is a minimal YAML file that is easy to understand.

YAML vs XML/JSON

YAML is more concise than XML, which relies on many tags and supports DTD validation, while YAML lacks a DTD concept. Compared with JSON, YAML offers better readability, especially for nested structures.

# YAML supporting JSON style
Button: {name: button2, text: Button 2}

YAML can also represent the same data as JSON but with clearer formatting:

arr:
  - a:
      a1: 1
      a2:
        - 2
        - 3
  - b

{
  "arr": [
    {
      "a": {
        "a1": 1,
        "a2": [2, 3]
      }
    },
    "b"
  ]
}

Heavy use of braces and brackets in JSON can make it hard to read.

How to Use YAML

JavaScript (browser)

<script src="esprima.js"></script>
<script src="js-yaml.min.js"></script>
<script type="text/javascript">
  var doc = jsyaml.load('greeting: hello');
</script>

Node.js

yaml = require('js-yaml');
fs = require('fs');
try {
  var doc = yaml.safeLoad(fs.readFileSync('/home/example.yml', 'utf8'));
  console.log(doc);
} catch (e) {
  console.log(e);
}

Java (JYaml library)

date: 11/29/2005
receipts:
  - store: ken stanton music
    category: entertainment
    description: saxophone repair
    total: 382.00
  - store: walmart
    category: groceries
    total: 14.26

YAML Basic Syntax

YAML uses spaces for indentation; spaces are part of the syntax, not just formatting.

Objects

name: YAML

Parsed as:

{ name: 'YAML' }

User:
  name: Bill
  age: 30

Parsed as:

{ User: { name: 'Bill', age: 30 } }

Arrays

- a
- b
- c

Parsed as:

[ 'a', 'b', 'c' ]

items:
  - id: 1
    price: 1.1
  - id: 2
    price: 2.2

Parsed as:

{ items: [ { id: 1, price: 1.1 }, { id: 2, price: 2.2 } ] }

Strings

Strings can be unquoted:

str: hello world

Special characters require quotes:

str: 'contains: abc'

Multi‑line strings join lines with spaces unless the pipe symbol | is used to preserve line breaks:

str: |
  line1
  line2
  line3

Parsed as:

{ str: 'line1
line2
line3
' }

Using |+ keeps trailing newlines, while |- discards them.

References (Anchors & Aliases)

sign: &sign
  name: Gates
  email: [email protected]
A:
  content: aaa
  <<: *sign
B:
  content: bbb
  <<: *sign

Parsed as:

{ sign: { name: 'Gates', email: '[email protected]' },
  A: { content: 'aaa', name: 'Gates', email: '[email protected]' },
  B: { content: 'bbb', name: 'Gates', email: '[email protected]' } }

The & creates an anchor, * references it, and << merges the anchored content.

Explicit Type Conversion

num: !!str 123

Parsed as:

{ num: '123' }

The !! prefix forces a type conversion.

Comments

# key: value

Lines starting with # are comments.

Resources

YAML official website: http://www.yaml.org/

Online YAML parser (js-yaml): http://nodeca.github.io/js-yaml/