YAML performs the same task as JSON and XML, only that it offers a more human-readable format. With YAML, its focus is on key-value pairs, with the main emphasis on indentation and line separation. Besides, YAML has plenty of uses in internet messaging, data persistence, and cross-language data sharing.
Furthermore, YAML is finding its place in existing technologies, and technologies like Docker are adopting it as the modern way of writing configuration files. Even for languages like Python, we have the pyYAML, which supports using YAML with Python.
In this guide, we will learn everything about YAML, from the syntax to the examples, ensuring you come out as a YAML pro at the end. Let’s get started.
Why Use YAML
JSON and XML are popular ways of writing configuration files. However, YAML is gaining more popularity, and here are the following reasons:
- YAML offers a more human-readable code.
- You can use strings with YAML without enclosing them with quotation marks.
- YAML is designed to handle data. It is solely a data serialization language.
- It has advanced features, such as relational anchors and extensible data types.
- You can add comments to your YAML file.
- YAML offers simple syntax, and its inline style is a superset of JSON.
- It can be used with all modern programming languages.
YAML file can take the .yml or .yaml extension.
YAML Syntax
The key difference between YAML and XML or JSON is how the data structure gets defined. For YAML, the definition is based on the line indentation and the line separation. A wrong spacing for YAML will raise an error, but that makes YAML a human-readable option among the three options.
When working with YAML, the syntax is mainly centered on key-value pairs, objects, lists, comments, multi-line strings, etc. Let’s cover each in detail and provide examples.
Key-Value Pairs
When using YAML, most items take the key-value pair format. The key stands for the pair’s name, and the data attached to the key is the value. A single stored value becomes a scalar. It’s from the key-value pairs that other constructions for YAML are founded.
The key-value pair gets represented as a mapping, where the mapping associates unordered key-value nodes. Ideally, a mapping is created by defining its name, followed by the colon, a space, and its value.
Here’s a simple key-value pair for a configuration file.
Previously, you note that the mapping follows the key-value syntax. In the first line, the key is the course, and its value is the YAML introduction.
Note that the indentation has to be the same. Otherwise, it will raise an error like in the following image:
Working With Strings
Unlike JSON and XML, YAML doesn’t require enclosing strings with single or double quotation marks. Whether you enclose them in quotation marks or not, XML will still capture the value as a string.
The following example demonstrates the different ways of representing a string in YAML:
When working with special characters, such as the newline character \n, you should enclose the string to avoid YAML treating it as a standard string instead of a special character.
Doing so makes YAML recognize the special character and handle it as expected.
For strings, you can make YAML recognize a single and multi-line string, depending on how you represent it.
If you have a long sentence that you want to break into multiple sentences but want it to get treated as a single line by the parser, represent it as shown below:
Here, the trick is to add the greater than sign (>) so that the parser can treat the value as a single line. Also, you must ensure each line has the same indentation. Otherwise, you will get an error in your key-value pair.
To add to the greater than sign, we need to specify whether we want the last character to get preserved when processing. In the previous case, we wanted each last character of every line to be preserved. Therefore, we need to use the >+ symbol.
If you want to trail each of the previous lines with a \n to add a new line, use the pipe (|) symbol instead.
Here’s how the new code would look. You can choose to retain the last character by adding a plus (+) or not retain it by adding a minus (-).
With this method, you enjoy a cleaner way of creating a new line for the paragraph instead of adding the \n at the end.
Numbers
You can use numbers as part of the scalars in your YAML file. YAML allows using exponential, octal, decimal, integers, floating values, and hexadecimal. With YAML, you don’t need to emphasize the number type.
Simply add it, and provided it has no quotes, YAML will recognize it as a number, as follows:
Boolean
YAML supports using Boolean values similar to how you can apply them with various programming languages. With YAML, you can create a key-value pair where the value can be yes/no, on/off, and true/false. If you don’t want the scalar to be treated as a Boolean, enclose it within quotes.
Here’s the following example of using Boolean with YAML:
The three are the common Boolean values that YAML recognizes.
Comments
YAML allows adding comments. To use a comment, use the # before the comment line, and YAML will skip the comment line.
Note that the indentation or line spacing of the comment doesn’t affect anything.
Null
In a case where you have a null, YAML allows you to represent it using the tilde (~) or null keyword.
Take a look at the following example:
Either of the previous options will work for your case.
Objects
When creating objects, you must place all their attributes on the same indentation level. The indentation separates the object name and the attributes. That way, the parser will recognize that you’ve created an object.
Let’s provide the following example:
In the previous image, note how each attribute is indented one width from the margin, and all attributes have the same indentation. You can have any datatype in your object.
That’s how you represent an object in YAML.
List
To represent a list, add a hyphen. A list can be created from an object, where you have an object having various a sub-category of attributes. Ensure you add the correct indentation and line separation to make a valid YAML file.
In the previous example, we have a list of members containing each member’s name, age, and career.
It’s possible to create a nested list from an attribute of an object. It could be one of the attributes that have plenty of value. In that case, you can create a nested list in YAML, as shown below:
For the nested list, use a hyphen to represent the primitive data under the attribute and ensure you add the required indentation and line spacing.
Alternatively, you can represent the primitive data on one line to create a cleaner code. Here’s how the same nested list can be expressed.
It will still get parsed as a YAML list/array.
Working With Multiple YAML Files
The good news with YAML is that it allows working with multiple YAML files on one document. This feature is handy for someone writing a configuration file for things like Docker tools. It improves as you can have the same key name in the document but under a different YAML file.
To work with multiple YAML files, and the triple hyphens (—) to signal the start of the first YAML file and repeat the same for the other file.
Here’s an example of a document with three YAML files.
You must add the three hyphens for the last file to signal the end.
Implementing Anchors and Alias
When dealing with a large configuration file, a given configuration will likely be repeated elsewhere in the YAML file. In that case, it will lead to duplication, and unnecessary lines will be used.
Luckily, YAML allows using anchors (&) and alias (*) to avoid this duplication. Let’s have the following example of a configuration file:
In the previous example, note how we have duplicated configuration details for all the kicks. We can avoid this by using the anchors to define a configuration chunk, then using the aliases to refer to the defined chunk elsewhere in the code.
That said, here’s how we can rewrite the earlier configuration file, eliminating duplication.
We now have a cleaner and simplified code with no duplication. Using alias and anchor comes in handy when the configuration details are the same for all items. However, we could have a kick with different trial times or versions for our example.
In such a case, we invoke the overrides (<<:) to change the anchor’s details without having to rewrite it again.
Here’s an example of implementing an override scenario of kick2 and kick3.
We still end up with a simplified code.
Note that you can always verify that your YAML file is correct using an online parser of your choice. If you have an indentation or line spacing error, it will display an error output to help you debug your file, as in the following example:
Working With Environmental Variables
When creating a YAML file, you can utilize an environmental variable by invoking it using the dollar sign. For instance, you could use the $USER environmental variable when writing a configuration file that requires the Linux login details.
To do so, use the environmental variable as $USER, and the parser will fetch the value of the specified environment variable.
Conclusion
YAML is an advanced way of creating configuration files, and it offers a better syntax to use with Docker, Ansible, and Kubernetes than XML or JSON. With YAML, you get a human-readable cleaner code, meaning anyone can follow along. This guide has presented the main concepts of using YAML. We’ve seen the syntax to follow for YAML and given various examples to help you get comfortable using YAML for your activities. Keep practicing to understand the syntax, and you will love the simplicity that comes with YAML.
