Lesson 5: Block and flow scalars
Write a string across more than one line using literal blocks, folded blocks, or flows.
This is also the course's first introduction to indentation within YAML files. YAML is commonly indented with two-space increments. It's important to use spaces and not "tab" characters for indentation. It's okay to use tabs if your editor converts them to spaces (most do have that as a setting).
Literal blocks
A literal style block starts with a | followed by a line break and indentation. Then, the string starts on the next line. Indent all the lines for the same string the same way.
summary: regular scalar description: | This is my sentence with the literal scalar. And another sentence. operationId: jasmint
The literal style block has a line break after the first sentence in the example. Line breaks are taken literally (as actual line breaks within the string).
Folded blocks
A folded style block starts with a > followed by a line break. But the line breaks are treated as a line break if there are multiple consecutive line breaks. Otherwise, they're treated as spaces.
summary: regular scalar description: > This is my sentence with the folded scalar. And another sentence starts without a preceding line break. And a sentence starts with a preceding line break, because there are two consecutive line breaks preceding this line. operationId: jasmint
Line breaks to end blocks
The block type can be followed with nothing (as shown in the examples above) which is the default clip.
| Line break style | Description |
|---|---|
| Clip (default) | Adds single line break at the end of the string |
| Strip (-) | Removes line breaks from the end of the string |
| Keep (+) | Keeps (more than one) line breaks at the end of the string |
Examples with literal style
description: | This has the default Clip behavior.
description: |- This has the strip behavior.
description: |+ This has the keep behavior.
Examples with folded style
description: > This has the default Clip behavior.
description: >- This has the strip behavior.
description: >+ This has the keep behavior.
Flow scalars
You should be aware of flow scalars (but probably not use them because you have less explicit control of the behavior).
Summary: regular scalar Description: This is my sentence with a flow scalar. And this is my next sentence. operationId: scaly
Summary: regular scalar Description: 'This is my sentence with a flow scalar. And this is my next sentence.' operationId: scaly
Summary: regular scalar Description: "This is my sentence with a flow scalar. And this is my next sentence." operationId: scaly
The single quote removes the ending line break.
Exercise 5.1: Find the problematic scalars (multiple choice)
A)
# Example A Description: | This is my description of a wonderful exercise.
B)
# Example B Description: { This is my description of a wonderful exercise.
C)
# Example C Description: < This is my description of a wonderful exercise.
D)
# Example D Description: This is my first sentence. This is my description of a wonderful exercise.
Which scalar is problematic?
- Example A
- Example B
- Example C
- Example D
- All of the above
See answer
All of the above.
Example A is missing indentation.
# Example A Description: | - This is my description of a wonderful exercise. + This is my description of a wonderful exercise.
Example B used a wrong token { instead of | or >.
# Example B - Description: { + Description: | This is my description of a wonderful exercise.
Example C had the mirror of the correct symbol >.
# Example C - Description: < + Description: > This is my description of a wonderful exercise.
Example D uses a flow scalar but lacks the indentation.
# Example D Description: This is my first sentence. - This is my description of a wonderful exercise. + This is my description of a wonderful exercise.