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

yaml

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?

@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.

Yi Ou

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

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

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).

My understanding on the three dots usage is based on this sentence of the spec: "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 ....

In fact, the definition of l-explicit-document forbids directives for it: "An explicit document begins with an explicit directives end marker line but no directives."

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).

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.

Yassin Hajaj

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"

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

Follow WeChat

Want to stay one step ahead of the latest teleworks?

相似问题

Platform

Support

Contact US