why --- (3 dashes/hyphen) in yaml file?

As you already found out, the three dashes --- are used to signal the start of a document, i.e.:

  1. To signal the document start after directives, i.e., %YAML or %TAG lines according to the current spec. For example:

    %YAML 1.2
    %TAG !foo! !foo-types/
    ---
    myKey: myValue
    
  2. To signal the document start when you have multiple yaml documents in the same stream, e.g., a yaml file:

    doc 1
    ---
    doc 2
    

    If doc 2 has some preceding directives, then we have to use three dots ... to indicate the end of doc 1 (and the start of potential directives preceding doc 2) to the parser. For example:

    doc 1
    ...
    %TAG !bar! !bar-types/
    ---
    doc 2
    

The spec is good for yaml parser implementers. However, I find this article easier to read from a user perspective.


It's not mandatory to have them if you do not begin your YAML with a directive. If it's the case, you should use them.

Let's take a look at the documentation

3.2.3.4. Directives

Each document may be associated with a set of directives. A directive has a name and an optional sequence of parameters. Directives are instructions to the YAML processor, and like all other presentation details are not reflected in the YAML serialization tree or representation graph. This version of YAML defines a two directives, “YAML” and “TAG”. All other directives are reserved for future versions of YAML.

One example of this can also be found in the documentation for directive YAML

%YAML 1.2 # Attempt parsing
           # with a warning
---
"foo"