336

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?

Michael
  • 41,989
  • 11
  • 82
  • 128
Andy
  • 5,433
  • 6
  • 31
  • 38
  • 62
    @lexicore I checked the docs before I tried an example. But I did not get a clear understanding and I thought I would understand better if someone explained. I am sorry if it appeared very basic, FYI I am only a beginner. – Andy Jun 11 '18 at 17:51

2 Answers2

263

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.

Yi Ou
  • 3,242
  • 1
  • 11
  • 12
  • I read production rule 211 in the YAML 1.2 spec in such a way that you don't need a document-end-indicator even if you have directives in the following document, the only thing required in that case is that you have an end-of-directives indicator (at the beginning of the `l-explicit-document`). – Anthon Dec 09 '18 at 10:31
  • 1
    My understanding on the three dots usage is based on this sentence of [the spec](https://yaml.org/spec/1.2/spec.html#id2801681): **"If a document is not terminated by a document end marker line, then the following document must begin with a directives end marker line. "** Requiring a document to begin with the directives end marker `---` would mean no directives are allowed for that document. So if doc 2 has directives, doc 1 must be terminated with the document end marker `...`. – Yi Ou Dec 09 '18 at 13:32
  • In fact, the [definition of l-explicit-document](https://yaml.org/spec/1.2/spec.html#id2801301) forbids directives for it: **"An explicit document begins with an explicit directives end marker line but no directives."** – Yi Ou Dec 09 '18 at 13:46
  • Rule 211 explicitly has the directives outside of the l-explicit-document, and I am not sure if your quoting of the text even contradicts that. In any case the Python YAML parsers do implement it that way (i.e. you don't need an explicit end-of-document indicator before the next documents directives). – Anthon Dec 09 '18 at 15:15
  • I don't see Rule 211 allowing directives preceding `l-explicit-document`. The expression `l-document-prefix*` does not contain directives. I am not familiar with the Python Yaml parser, but an interesting question would be whether it just silently skips the directives, if they are not preceded by the dots. – Yi Ou Dec 09 '18 at 20:23
  • This is also good as a brief intro: https://gettaurus.org/docs/YAMLTutorial/ – flow2k Oct 23 '19 at 00:12
  • 1
    Did the people designing YAML ever stop to think whether or not they should implement this? – Dragas Sep 02 '20 at 10:54
  • When I read it using devops pipeline, it is one object with both sections merged – JRichardsz Sep 16 '21 at 22:51
87

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"
Yassin Hajaj
  • 21,337
  • 9
  • 51
  • 89