Updated on 2023-09-26 GMT+08:00

YAML Syntax

YAML is a simple and powerful language. It is designed to make the language easy to read.

Basic Syntax Rules

  • Characters are case-sensitive.
  • Indentation is used for denoting structure.
  • Only spaces can be used for indentation, but tab characters are not allowed.
  • The specific number of spaces in the indentation is unimportant as long as parallel elements have the same left justification.
  • Comments begin with the number sign (#).

Data Types Supported by YAML

  • Object: A set of key-value pairs, which is also known as maps, hashes, or dictionaries.
  • Array: A group of values arranged in sequence, which is also known as sequence or list.
  • Scalar: A single and irreducible value, which is the minimum data unit.

Object

An object is a group of key-value pairs. For key: value, the colon (:) must be followed by a space or newline character. The valid expression is as follows:

animal: pets
plant:
  tree

You can also write multiple key-value pairs into an inline object.

hash: {name: Steve, foo: bar}

However, an error occurs in the following scenario:

foo: somebody said I should put a colon here: so I did
windows_drive: c:

To resolve the issue, you can enclose values in single quotation marks (' ') as follows:

foo: 'somebody said I should put a colon here: so I did'
windows_drive: 'c:'

Array

An array is represented by a hyphen (-) and space. The valid expression is as follows:

animal:
- Cat
- Dog
- Goldfish

You can also use the inline representation.

animal: [Cat, Dog, Goldfish]

Objects and arrays can be used in combination to form a composite structure.

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

Scalar

Scalars include strings, Boolean values, integers, floats, null, time, and dates.

  • String:

    By default, a string is not enclosed in quotation marks.

    str:This_is_a_line

    If a string contains spaces or special characters, the string needs to be enclosed in quotation marks.

    str: 'content: a string'

    Both single and double quotation marks can be used. The difference between them is that the former can identify escape characters while the latter cannot convert special characters.

    s1: 'content:\n a string'
    s2: "content:\n a string"

    If there is a single quotation mark between two single quotation marks, ensure that two consecutive single quotation marks are used to achieve conversion.

    str: 'labor''s day'

    Strings can be written into multiple lines. The lines except the first line must be indented with one space. The newline character will be converted to a space.

    str: This_is
     a_multi_line
  • Integer:
    int_value: 314
  • Float:
    float_value: 3.14
  • Null:
    parent: ~
  • Time

    The time is in the ISO8601 format.

    iso8601: 2018-12-14t21:59:43.10-05:00
  • Date:

    The date is in the compound ISO8601 format: year-month-day.

    date: 1976-07-31

Special Symbols

  • Three hyphens (---) indicate the start of a YAML file. Three periods (...) indicate the end of a YAML file.
---
# A list of delicious fruits
- Apple
- Orange
- Strawberry
- Mango
...
  • You can use two exclamation marks (!!) to forcibly convert an integer, a float, or a Boolean value.
strbool: !!str true
strint: !!str 10
  • For a string occupying multiple lines, you can use a literal block scalar (|) to preserve newlines or folded block scalar (>) to fold newlines. The two symbols are often used in the character strings in YAML files.
this: |
 Foo
 Bar
that: >
 Foo
 Bar

The corresponding objects are as follows:

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

It is recommended that you use "|" to meet the requirements of most scenarios.

Comment

YAML supports comments. This is an advantage of YAML compared with JSON.

Comments in YAML files begin with the number sign (#), as shown in the following:

languages:
 - Ruby                # Ruby programming language
 - Go                  # Go programming language
 - Python              # Python programming language