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

So I just started using YAML file instead of application.properties as it is more readable. I see in YAML files they start with ---. I googled and found the below explanation.

> YAML uses three dashes (“---”) to separate directives from document > content. This also serves to signal the start of a document if no > directives are present.

Also, I tried a sample without --- and understood that it is not mandatory to have them.

I think I don't have a clear understanding of directive and document. Can anyone please explain with a simple example?

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"