Overcoming YAML Hatred

I was editing the Serverless Framework configuration YAML, looking at the following sample from the official site.

Overcoming YAML Hatred

When I finished editing and ran the file, it didn't work, and when I looked closely, I found that "arn: arn:xx" was actually indented one space more than "sns:", and when I fixed it, it worked....

I am ashamed to admit that I am actually not very good at YAML, and I had been using it without understanding it.

There were many things that could not be understood without actually writing them, so we proceeded by entering YAML at the following site.

https://www.json2yaml.com/

What is YAML?

YAML is a text format for representing array and map data. It is characterized by the fact that it is designed to be sensibly readable by humans.

array (programming, programing)

Elements begin with "-" andOpen space.Write the value
Parallel elements should be aligned with the head position.write vertically

YAML

- A
- B
- C

JSON

[
    "A",
    "B",
    "C"
]

map

element, followed by a ":".Open space.Write the value
Parallel elements should be aligned with the head position.write vertically

YAML

a: A
b: B
c: C

JSON

{
    a: "A",
    b: "B",
    c: "C"
}

Comments and delimiters

After the "#" is the comment. You can write anywhere.
Separated by "---"

YAML

- A # comment
# comment
- B
- C

---
- D
- E
- F

JSON

[
    "A",
    "B",
    "C"
]

[
    "D",
    "E",
    "F"
]

Shift the value to the next line.

The value of an element can be written on the following line
The value must be indented and below the position of the element.
- Exception (see below): If a map element contains an array, it does not need to be indented.

YAML

-
    A
- B
- C

JSON

[
    "A",
    "B",
    "C"
]

YAML

a:
    A
b: B
c: C

JSON

{
    a: "A",
    b: "B",
    c: "C"
}

nesting

Arrays and maps can be nested by indentation.
It can be said to be an application of "shift the value to the next line" above.

YAML

# 配列 -> 配列
-
    - A
    - B
- C

# 配列 -> マップ
-
    a: A
    b: B
- C

# マップ -> 配列
a:
    - A
    - B
c: C

# マップ -> マップ
a:
    b: B
    c: C
d: D

JSON

[
    ["A", "B"],
    "C"
]

[
    {a: "A", b: "B"},
    "C"
]

{
    a: ["A", "B"],
    c: "C"
}

{
    a: {b: "B", c: "C"},
    d: "D"
}

Indentation is super important.

Parallel elements should be indented head-to-head.
The absolute position of the indentation is irrelevant, and where you belong is determined by whether each element is indented above, below, or equal to you in comparison to its surroundings.

The following "A, B" and "C, D" will be in the same position, unchanged in depth.

YAML

-
        - A
        - B
-
    - C
    - D

JSON

[
    [
        "A",
        "B"
    ],
    [
        "C",
        "D"
    ],
]

A single character shift can make a difference in meaning. The following is a syntax error

YAML

-
   - a
    - b
-
    - c
   - d

in-line representation

As indicated at the beginning, a value can be written immediately after the element. This is called inline notation
A line break after an element and writing after the next line is called next-line notation.

YAML

- A    # インライン表記
-
    B    # ネクストライン表記

---
a: A    # インライン表記
b:
    B    # ネクストライン表記

JSON

[
    "A",
    "B"
]

{
    a: "A",
    b: "B"
}

The inline representation of the map isOnly when the element value is a direct value (scalar)Possible

YAML

# これはOK
a: A

# これはNG
a: b: B

# これもNG
a: - A

Inline notation for arrays can also be used to value arrays/maps (although I've never seen it used...) (When writing parallel elements, align the heads)

YAML

# これはOK
- A

# これもOK
- a: A

# これもOK
- - A

# 応用
- - A
  - B
  - - - c: C
        d: D
    - E

JSON

[
    "A"
]

[
    { a: "A" }
]

[
    [ "A" ]
]

[
    [
        "A",
        "B",
        [
            [
                { c: "C", d: "D" }
            ],
            "E"
        ]
    ]
]

Writing both inline and nextline notations makes things strange.

The following is a syntax error

YAML

a: A
    b: B

The following are unintended values

YAML

- A
    - B

JSON

["A - B"]

When the value is nothing in inline notation, it is null. (null is omitted).

YAML

-     # nullが隠れている
- B

---
a:     # nullが隠れている
b: B

JSON

[
    null,
    "B"
]

{
    a: null,
    b: "B"
}

null can be written explicitly.

YAML

- null
- B

---
a: null
b: B

Next Line Notation Indentation Exception

The basic next line must be indented, but only if the map elements are arrays.

YAML

a:
- A  # OK
- B  # OK
b:
  - C
  - D

JSON

{
    a:
        [
            "A",
            "B"
        ],
    b:
        [
            "C",
            "D"
        ]
}

The opposite is true, i.e., if the array value is a map, it must be indented or else NG. The following is a syntax error.

YAML

# [ {a: "A", b:"B"} ] を作りたかったとする
-
a: "A"  # インデントしないといけない
b: "B"  # インデントしないといけない

flow style

Only that mode can be embedded in JSON format.
Arrays are enclosed in "[]", maps are enclosed in "{}", and elements are separated by ",".
Since it is JSON, you don't have to worry about line breaks and indentation. You can write with the same feeling as when you normally write JSON.

YAML

- [A, B, C]
- a:
    {
        b: "B",
        c: "C"
    }

JSON

[
    ["A", "B", "C"], 
    {
        a: {b: "B", c: "C"}
    }
]

Review of points that are easy to get caught

Orientation is not good either vertically or horizontally. Always line up vertically.
Parallel elements must have their heads aligned
Indent position is important. Absolute position (depth of indentation) is not important, relative position is important.
Maps cannot be represented inline except for direct values.
Inline and nextline notation should not be used at the same time.
- When you use inline notation, the value of the element is determined there, so it is not acceptable to include a next-line notation that attempts to set the value of the element in a subsequent line.
null is omitted
- In many cases, unintentional nulls are inserted due to mistakes

impressions

I had been using inline and nextline notations without understanding them well, and that was one of the reasons for my confusion.

JSON is indented appropriately to make it easier to read, but in YAML, the indentation itself is important, not just for appearance. Particular attention should be paid to the height of theAlign.Is that what you mean?

I thought I could summarize the use of YAML in a concise way, but it's hard to put the rules in writing and it's kind of a blur...

It is interesting to note that the YAML rule was created to make it easier for people to read, but it turned out to be a rule that is difficult for people to understand, just like a natural language.

However, it has made the configuration files and other files more readable.

Incidentally, regarding the first mistake in the Serverless Framework configuration file, what should be "YAML_OK" is wrong, like "YAML_NG". It is totally different with just one space. This is a problem because syntactically, neither of them is wrong. (You wouldn't expect "null" to be in there on its own, would you? .......)

I would like to think that I have overcome my YAML allergy a little, because now I can see some differences.

YAML_OK

- sns:
    arn: arn:xxx

# JSON
# [
#     {
#         sns: { arn: "arn:xxx" }
#     }
# ]

YAML_NG

- sns:
  arn: arn:xxx

# JSON
# [
#     {
#         sns: null
#         arn: "arn:xxx"
#     }
# ]

Welcome to new things

[Technical] [Electronic work] [Gadget] [Game] memo writing

What is YAML?

array (programming, programing)

map

Comments and delimiters

Shift the value to the next line.

nesting

Indentation is super important.

in-line representation

Writing both inline and nextline notations makes things strange.

When the value is nothing in inline notation, it is null. (null is omitted).

Next Line Notation Indentation Exception

flow style

Review of points that are easy to get caught

impressions

reference information

What is YAML?

array (programming, programing)

map

Comments and delimiters

Shift the value to the next line.

nesting

Indentation is super important.

in-line representation

Writing both inline and nextline notations makes things strange.

When the value is nothing in inline notation, it is null. (null is omitted).

Next Line Notation Indentation Exception

flow style

Review of points that are easy to get caught

impressions

reference information

Related Category Articles