How to Break YAML Strings Across Multiple Lines

In YAML, you can break long strings across multiple lines using several different syntax approaches while preserving quotes and maintaining literal content. The most common methods include using block scalar styles (| and >), explicit line concatenation with the + operator, or leveraging double-quoted strings with escape sequences.

Contents

• Basic Line Concatenation Method
• Block Scalar Styles
• Double-Quoted Multi-Line Strings
• Best Practices and Examples
• Handling Special Characters
• Performance Considerations

Basic Line Concatenation Method

The approach you mentioned in your question using the + operator is indeed valid in many YAML parsers, though it’s not part of the official YAML specification. Here’s how it works:

Key: 'this is my very very very ' +
     'very very very long string'

Important note: While this syntax works in many YAML implementations (especially in programming contexts), it’s not guaranteed to work across all YAML parsers. The most reliable methods are the block scalar styles.

Block Scalar Styles

YAML provides two main block scalar styles for handling multi-line strings:

1. Literal Block Scalar (|)

The | style preserves line breaks exactly as they appear in the source:

Key: |
  this is my very very very
  very very very long string

This will produce the string:

this is my very very very
very very very long string

2. Folded Block Scalar (>)

The > style joins lines with spaces for better readability:

Key: >
  this is my very very very
  very very very long string

This will produce the string:

this is my very very very very very very long string

For your specific case of maintaining quotes, you can combine these styles with quoted strings:

Key: |
  'this is my very very very
   very very very long string'

Double-Quoted Multi-Line Strings

Double-quoted strings in YAML support escape sequences and can span multiple lines using the backslash (\) continuation character:

Key: "this is my very very very \
      very very very long string"

Alternatively, you can use explicit line breaks within double quotes:

Key: "this is my very very very
      very very very long string"

Best Practices and Examples

Recommended Approach for Your Use Case

For maintaining quotes while breaking strings, here are the most reliable methods:

Method 1: Folded Scalar with Quotes

Key: >
  'this is my very very very
   very very very long string'

Method 2: Literal Scalar with Quotes

Key: |
  'this is my very very very
   very very very long string'

Method 3: Double-quoted with Continuation

Key: "this is my very very very \
      very very very long string"

Practical Examples

Configuration File Example:

database:
  connection_string: >
    "mysql://user:password@host:3306/
     database_name?charset=utf8mb4"
  
  query: |
    SELECT * FROM users 
    WHERE created_at > '2024-01-01'
    AND status = 'active'

API Configuration Example:

api:
  endpoint: "https://api.example.com/v1/
             users/123/profile"
  
  headers: >
    Authorization: Bearer your_token_here
    Content-Type: application/json
    Accept: application/json

Handling Special Characters

When breaking strings that contain special characters, the block scalar styles are particularly useful:

command: |
  "find /path/to/files -name '*.log' -mtime +7
   -exec rm {} \;"

This preserves the special characters and maintains readability without requiring extensive escaping.

Performance Considerations

• Block scalars (| and >) are generally more performant as they’re natively supported by YAML parsers
• String concatenation (+ operator) may require additional processing by the YAML parser
• Double-quoted strings with escape sequences can be slower due to the need to process escape sequences
• For very large strings (thousands of lines), block scalar styles are recommended for both performance and readability

Conclusion

To break YAML strings across multiple lines while preserving quotes and content, you have several reliable options:

1. Use block scalar styles (| for literal, > for folded) - most reliable and standards-compliant
2. Combine block scalars with quotes - preserves both formatting and quotes
3. Use double-quoted strings with backslash continuation - good for simple cases
4. Avoid relying solely on + operator - not guaranteed across all YAML parsers

The block scalar approach (| or >) is generally recommended as it’s part of the YAML specification and works consistently across different parsers and programming languages. When you need to maintain quotes specifically, simply place the quoted string content within the block scalar.

For complex strings requiring special character preservation, literal scalars (|) work best, while for regular text that benefits from automatic word joining, folded scalars (>) are more appropriate.

Sources

1. YAML 1.2 Specification - Block Styles
2. YAML Tutorial - Multi-line Strings
3. PyYAML Documentation - String Handling