Updated on 2024-05-28 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 to represent hierarchical relationships.
  • Only spaces can be used for indentation.
  • The number of spaces used for indentation does not matter. Elements of the same level must be aligned on the left side.
  • Lines that start with a number sign (#) are comments.

YAML supports three types of data structures.

  • Object: A set of key-value pairs, which is also called mapping, hashes, or dictionary.
  • Array: A group of values arranged in sequence, which is also called a 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 use single quotation marks (' '), as shown in the following:

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:
- 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

Scalar data types include string, Boolean value, integer, floating-point number, null, time, and date.

  • 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 single quotation marks are used consecutively 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
  • Floating-point number:
    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

  • ---: indicates the start of a YAML file. ...: indicates the end of a YAML file.
---
# A list of delicious fruits
- Apple
- Strawberry
- Mango
...
  • You can use two exclamation marks (!) to forcibly convert an integer, a floating-point number, or a Boolean value.
strbool: !!str true
strint: !!str 10
  • For a string in multiple lines, you can use a literal block scalar (|) to start new lines or folded block scalar (>) to fold new lines. The two symbols are often used in the character strings of 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 "|" be used to meet the requirements of most scenarios.

Comment

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

The comment of YAML starts with a number sign (#), as shown in the following:

languages:
 - Ruby                # Indicates the Ruby language.
 - Go                  # Indicates the Go language.
   --  PythonPy               # Indicates the Python language.