dashes and indentations in yaml

I'm going through the "getting started" tutorial for Prometheus. I'm getting very hung up on the YAML config file:

scrape_configs:
  - job_name:       'node'

    # Override the global default and scrape targets from this job every 5 seconds.
    scrape_interval: 5s

    static_configs:
      - targets: ['localhost:8080', 'localhost:8081']
        labels:
          group: 'production'

      - targets: ['localhost:8082']
        labels:
          group: 'canary'

So apparently hyphens are supposed to indicate one of two things: The first item in a new list, or a key value pair.

So it looks like job_name: 'node' is a key value pair. Why then is everything after it indented?
targets also looks like a key value pair. But so does labels and it doesn't have a hyphen. Further, group is indented by one space from labels.

It's very, very difficult for me to tell what is going on here. I need to know if I am ever going to customize this file (which I already tried to do and received errors when starting up Prometheus).

What is the logical structure of this file?

Solution

YAML documents consist of three types of nodes: Scalars, sequences and mappings. When using block syntax, each node exists at a specific indentation level, where its content is defined.

Here's a simple example to make it more clear:

-
  a
- 
  b:
    c
-
  -
    d

At indentation level 0, there are hyphens defining sequence items. Therefore, the top level node is a sequence. In the first sequence item, there is an a. It is part of the sequence item since it has more indentation. This is parsed as scalar.

In the second sequence item, there is a mapping that maps the scalar b to the scalar c. We see that because b: is an implicit key (a single-line node succeeded by a colon), and the occurrence of an implicit key indicates the existence of a mapping (just like the existence of a sequence item indicates the existence of a sequence). c is the value of b because again, it is more indented.

Now YAML defines a compact notation where you can treat sequence indicators as part of the indentation. Also you can place certain nodes directly after an implicit key. This condenses the example to:

- a
- b: c
- - d

Still, the key b: is completely independent of the sequence item indicator -. Now let's apply this to your file:

scrape_configs:
  - job_name:       'node'

    # Override the global default and scrape targets from this job every 5 seconds.
    scrape_interval: 5s
    # …

The top level is a mapping since there is an implicit key scrape_configs. It contains a sequence with one item. This one item is a mapping and starts at job_name:. Other keys are scrape_interval and static_configs. static_configs maps to a sequence of mappings, where each mapping contains the keys targets and labels.

The [] syntax is an alterative syntax for defining sequences, usually for short ones that fit on a single line. Scalars can be quoted, which is usually done when values contain YAML special symbols. For example, within [] a comma starts the next item, so if you want to have a comma in your scalar, you need to quote the scalar.

So, bottom line: Hyphens and implicit keys are independent structures. Don't read the hyphen as part of the key.