Choosing Between Literal (|) and Folded (>) YAML Multiline Scalars

The Problem: Unintended Text Transformation

Embedding multiline text in YAML often leads to formatting errors when the parser interprets line breaks differently than the author intended. Choosing the wrong scalar style can turn a functional shell script into a single line of space-separated commands or strip necessary paragraph breaks from a long description.

The practical takeaway: Use the literal style (|) when whitespace is functional (code, keys, logs) and the folded style (>) when whitespace is presentational (natural language prose).

Decision Constraints

The choice depends on three primary constraints:

• Parser Fidelity: While YAML 1.2 is standard, older or non-compliant parsers (such as certain legacy libyaml versions) may mishandle blank lines within folded scalars, potentially removing intended paragraph breaks.
• File Size and Memory: Folded scalars can reduce file size by up to 30% for long paragraphs by allowing the author to wrap text without adding literal newline characters to the resulting string. Conversely, very large literal scalars can increase memory overhead during parsing.
• Editing Ergonomics: Literal blocks maintain visible line breaks in most IDEs, aiding manual editing. Folded blocks may be rendered as a single long line by some tools, making the source file harder to read.

Comparison of Scalar Styles

Feature	Literal (|)	Folded (>)
Newline Handling	Preserves all line breaks	Collapses single newlines to spaces
Paragraph Breaks	Blank lines remain blank lines	Blank lines create a newline in output
Primary Use Case	Scripts, SSH keys, preformatted logs	Descriptions, documentation, notes
Source Formatting	Exact representation	Flexible wrapping for readability

Trade-offs and Chomping

Literal style is the safest choice for any content where the exact position of a character matters. It is the only viable option for multi-line scripts or diff outputs. The trade-off is a larger file footprint and a strict requirement for correct indentation.

Folded style improves the readability of the YAML source file. It allows a writer to wrap a long sentence across five lines in the editor, but the parser treats it as one continuous string. The risk is the potential loss of formatting if the downstream application expects specific line breaks.

Both styles support chomping indicators to control trailing newlines at the end of the block:

• | or > (Clip): Keeps one trailing newline.
• |- or >- (Strip): Removes all trailing newlines.
• |+ or >+ (Keep): Preserves all trailing newlines.

Implementation and Validation

To verify behavior, create a file named config.yaml with the following content:

script: |
  echo Starting backup
  tar -czf backup.tar.gz /data
  echo Done

description: >
  This is a long description written over
  several lines in the editor for readability
  but parsed as a single sentence.

  A blank line above creates a paragraph break.

First, validate the syntax using a linter from the project root (requires read permissions):

yamllint config.yaml

Next, load the file using SnakeYAML (Java 17+) to inspect the resulting strings. Ensure the application has read permissions for config.yaml:

import org.yaml.snakeyaml.Yaml;
import java.util.Map;
import java.io.FileInputStream;

public class YamlTest {
    public static void main(String[] args) throws Exception {
        Yaml yaml = new Yaml();
        Map<String, Object> data = yaml.load(new FileInputStream("config.yaml"));
        System.out.println("Script: " + data.get("script"));
        System.out.println("Description: " + data.get("description"));
    }
}

Expected Result: The script value should contain \n characters after every command. The description value should contain spaces where the single line breaks were, but a \n where the blank line occurred.

Limitations

Be aware that some automated YAML formatters may convert literal scalars to folded scalars (or vice versa) based on line length settings, which can silently change the semantics of your data. If memory is severely constrained, avoid loading massive literal blocks into memory; use a streaming API instead.

To verify the final result, assert that the script key contains the expected number of newlines and the description key contains the expected space-collapsed sentence.