In DevOps, you’ll often find yourself creating configuration files that define the behavior of an application, deployment, or system. When working with Kubernetes or Ansible, those configuration files will mostly be in YAML format. If the configurations you are defining in YAML are complex, you might be required to work with strings spanning multiple lines, such as SQL queries or bash scripts.

In this article, we’ll discuss the different methods that we can use to break a single string over multiple lines in YAML.

What is YAML

YAML is a human-readable data-serialization language mainly used to write configuration files. Unlike JSON or XML format, YAML is designed for readability, allowing even non-technical people to understand what the code is trying to do. YAML also supports many data types, from strings, numbers, boolean, dates, timestamps, and arrays to maps. For these reasons, platforms like Kubernetes, Ansible, and GitLab CI use YAML as their scripting language.

How to Write Multi-Line Strings on YAML

There are three approaches you can use to write multi-line strings in YAML:

• Use block-scalar styles
• Use block-chomping indicators
• Use Flow scalar styles

Let’s see how each of the three approaches works.

Break a String Using Block-Scalar Styles

In YAML, scalars generally refer to a data type representing a single data value. Strings, booleans, integers, and floats are scalar types. Other data types, such as arrays, lists, or objects, are not scalar types.

There are two ways to break a string using block-scalar:

• Literal style
• Folded style

Literal Style

Literal style, denoted by the pipe "|" character, is the most readable scalar style.

To break a string using the literal style, you add the "|" character at the beginning of the string. Below is an example of breaking an SQL query string using the literal style.

---
apiVersion: v1
kind: ConfigMap
metadata:
name: postgresql-initdb-config
data:
init.sql: |
CREATE TABLE IF NOT EXISTS blog (
ID         SERIAL NOT NULL PRIMARY KEY,
BODY       TEXT   NOT NULL,
CREATED_AT TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
UPDATED_AT TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
INSERT INTO blog(ID,BODY,CREATED_AT,UPDATED_AT)
VALUES(1,'sample_blog',now(),now());

This Kubernetes Configmap deployment file creates a config map for initializing SQL queries. Using the "|" syntax, the SQL queries can be spanned into multiple lines, making them more readable.

Folded Style

Folded style is denoted using the greater than ">" character. The folded style works similarly to the literal style. The only difference is that, in folded style, the line breaks are only taken if there are multiple consecutive line breaks in the string. If there is only one line break in the string, it is considered space. Below is an example of a string broken using the folded style:

name: MySQL database
description: >
The MySQL database is used for storing relational data.
User profile info is stored in it.
All other non-relational data is stored in MongoDB instead.
type: relational

In the above example, the value of the "description" string will be treated as below:

The MySQL database is used for storing relational data. 
User profile info is stored in it.
All other non-relational data is stored in MongoDB instead. 

Break a String Using a Block-Chomping Indicator

You can mix the block scalar styles with a block-chomping indicator, using a "+" or "-" to handle the line breaks at the end of the string.

• With the plus "+" syntax, you keep all the line breaks at the end of the string.
• With the minus "-" syntax, you remove all the line breaks at the end of the string.
• If you do not provide the block chomping indicator, one line break will be automatically added to the end of the string.

Below is an example of a string definition using the "+" indicator:

name: Redis database
description: >+
The Redis database is used for storing caching data.
Caching data helps to boost service performance.
Remember that you need to invalidate the cache to match the business logic.


type: nosql

The representation of the "description" value in the above example will look like:

The Redis database is used for storing caching data. 
Caching data helps to boost service performance.
Remember that you need to invalidate the cache to match the business logic.

Considering the below example for demonstrating a string definition using the "-" indicator:

name: Mongo database
description: >-
The Mongo database is used for storing non-relational data.
It helps improve the service performance compared to traditional SQL databases.
Consider using an SQL database if you need relational features support.


type: nosql

The representation of the "description" value for the example above will look like this:

The Mongo database is used for storing non-relational data. 
It helps improve the service performance compared to traditional SQL databases.
Consider using an SQL database if you need relational features support.

Break a String Using Flow Scalar Styles

Flow style syntax in YAML looks similar to JSON. In flow style, you use commas to separate the data and curly braces to construct the object. There are three styles of breaking a string using Flow scalar, plain style, double-quoted style, and single-quoted style.

Below is an example of using Flow style in YAML:

id: 1
description: "This is a description for breaking string using flow scalar types."
fullname: "I am anonymous"

Suppose the description key is a very long string. Let’s look at how we would use each of the three Flow styles to handle a long description string.

Plain style

With plain style, you simply write the string in multiple lines as it is.

description: demonstrating how to break
a string using plain style in Flow scalar styles

The problem with plain style is that you don’t have support for special characters like "#" or '"'.

Double-quoted style

With double-quoted style “””, you need to escape special characters like double-quote “”” using “\” character. To insert a new line in the string, you use the "\n" syntax. Below is an example of breaking a string using double-quoted style:

description: "Vietnam is a very peaceful country in South East Asia.\n
Here is a favorite quote in Vietnam: \"Adversity is the mother of wisdom.\""

Single-quoted style

With the single-quoted style "'", you can have almost any character in your string. You will often find the single-quoted style convenient when you want to have the double-quoted character in your string.

description: 'Vietnam is a very peaceful country in South East Asia.
Here is a favorite quote in Vietnam: "Adversity is the mother of wisdom".'

The problem with a single-quoted style is you can't break the string into multi-line.

Format the Multi-Line String Using Indentation Indicators

To make your multi-line string more readable, you can use indentation indicators. For example, you can indent every line of your string to 2 spaces by adding the “>2” chomping indicator as the one below:

blogId: 1
content: >2
  This blog is about natural resources.
    We must protect our natural resources to be able to survive.
      This allows our generation to live and enjoy their lives.

The resulting multi-line string looks like the below:

This blog is about natural resources.
We must protect our natural resources to be able to survive.
This allows our generation to live and enjoy their lives.

Conclusion

In this article, you’ve learned the different approaches you can use to make multi-line comments more readable. We’ve covered how to break multi-line comments using block scalars style, block-chomping indicator, and flow scalar style.

To learn more about YAML and its role in DevOps, enroll in our DevOps Pre-Requisite Course.