Managing Multi-line Strings in YAML: Literal vs. Folded Block Scalars

The Problem: Formatting Long Strings Without Escaping

When storing shell scripts, public keys, or long descriptions in YAML, using standard quoted strings (flow style) becomes unmanageable. Escaping double quotes and manually inserting \n characters increases the risk of syntax errors and makes the file difficult for humans to read.

The solution is using block scalars. These allow you to write multi-line strings exactly as they should appear, using indentation to define the block's boundaries. The primary decision is whether to use the Literal style (|) or the Folded style (>).

Choosing the Right Block Scalar

The choice depends on whether the newline characters in your source file are meant to be functional (part of the data) or purely for visual organization in the editor.

Feature	Literal Style (|)	Folded Style (>)
Newline Handling	Preserved as \n	Converted to spaces
Blank Lines	Preserved	Preserved
Primary Use Case	Scripts, Keys, Config files	Long descriptions, prose
Escaping Needed?	No	No

Controlling Trailing Newlines with Chomping

By default, YAML block scalars keep one newline at the end of the string. You can modify this behavior using chomping indicators immediately following the style character:

• Clip (Default): Keeps the final newline but removes any subsequent trailing blank lines.
• Strip (-): Removes all trailing newlines from the end of the string. Use |- or >-.
• Keep (+): Preserves all trailing newlines and blank lines exactly as written. Use |+ or >+.

Implementation Example

Consider a configuration file for a deployment tool that requires both a shell script (where line breaks matter) and a description (where line breaks are for readability).

# config.yaml
# Literal style: preserves newlines for the script
setup_script: |
  echo "Starting installation..."
  mkdir -p /opt/app
  chmod +x /opt/app/start.sh

# Folded style: converts newlines to spaces for the description
app_description: >
  This application provides a high-performance
  interface for data processing and
  real-time analytics across distributed nodes.

# Strip chomping: ensures no trailing newline for a secret key
api_key: |-
  MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCA
  QEA7vX1z... 

Validation and Verification

To verify how your parser interprets these blocks, load the YAML file and print the strings wrapped in delimiters (like brackets) to see hidden characters. Using a Python environment with PyYAML:

# Run this in a Python environment with pip install pyyaml
import yaml

with open('config.yaml', 'r') as f:
    data = yaml.safe_load(f)

# Verify Literal style (should contain \n)
print(f"Script: [{repr(data['setup_script'])}]")

# Verify Folded style (should be a single line)
print(f"Description: [{repr(data['app_description'])}]")

# Verify Strip chomping (should have no trailing \n)
print(f"Key: [{repr(data['api_key'])}]")

Expected Results

• The setup_script will show \n after every line.
• The app_description will appear as one continuous string with spaces replacing the line breaks.
• The api_key will end immediately after the last character, without a trailing \n.

Critical Constraints

• Indentation: All lines in a block scalar must be indented more than the key. If a line starts at the same indentation level as the key, the block ends prematurely, often causing a parsing error.
• Folded Blank Lines: In folded style (>), a double newline (a blank line) is not folded; it is preserved as a newline in the resulting string.

Rollback and Correction

If a parser is incorrectly interpreting a string (e.g., a script is being loaded as one long line), change the indicator from > to |. If your application fails because of an unexpected trailing newline in a secret or token, change the indicator from | to |-.