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

Question

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?

Answer 1

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.