Mastering YML (YAML): A guide for Developers, Admins, and Self-Hosters

When you are doing a lot of tool configuration, but also while coding, you likely need to read and/or write YML code.

What is YML (YAML) and why is it important? #

YML (also called YAML) stands for Yet another Markup language: It is a file format in which you can describe data.

Basically you can think of key value pairs, e.g. “My name is Oliver” (key would be name, value would be Oliver).

Step-by-Step guide: How to write YML (YAML) #

YML data does not have any start or end sequence. So the easiest YML file you could write, would be empty.

Let’s say you want to describe a user as an YML object, given the “My name is Oliver” example from above, your JSON could look like this:

1

name: Oliver

Data Types Explained: From Strings to Objects #

As you can see in the example above, key and value are seperated by :, they have no special formatting. Like in JSON, value can have multiple types:

1

key: Oliver

1

key: 123

1

key: 123.23

1

key: true

1
2
3
4

key:
  - 1
  - 2
  - 3

1

key: null

1

name: Oliver

1
2

key: 
  name: Oliver

YML data can have multiple values, in this case they are seperated by newline:

1
2

name: Oliver
year_born: 1990

Whitespaces matter #

In the example YML above, I used spaces and linebreaks. In fact, YML cares about them a lot. If you skip line breaks or indentation, the represented information will not be the same or it will not work at all.

One exception are arrays: You don’t need to indent the array items.

1
2
3
4

key:
  - 1
  - 2
  - 3

Is similar to:

1
2
3
4

key:
- 1
- 2
- 3

I personally like to indent array items for better readability.

Multiline text #

YML supports multiline text in two ways. You can decide to respect line breaks or have line breaks replaced with spaces.

Hint: In the YML file, linebreaks always will show up. This is just an information for whoever works with the file.

With line breaks #

1
2
3

text: |
  This is a multiline text
  where linebreaks will be represented.  

With line breaks replaced as space #

1
2
3

text: >
  This is a multiline text
  where linebreaks will be replaced with spaces.  

Reusable / Templates / Defaults #

YML support the definition of default values that you can re-use in your code at any place.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

default_car: &default_car
  distance_km: 800
  tires: 4
  doors: 5

private_car: *default_car

company_car:
  <<: *default_car
  doors: 2

In this example, private_car has the same key and values as default_car (named alias), while company_car would have basically the same information but overwrites the amount of doors (named merge keys). The following code would represent the same information:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

default_car:
  distance_km: 800
  tires: 4
  doors: 5

private_car:
  distance_km: 800
  tires: 4
  doors: 5

company_car:
  distance_km: 600
  tires: 4
  doors: 2

How to create and work with YML files in any editor #

After knowing how YML is structured, it is quiet easy to read and write. YML files are normal text files that you can open and edit with every editor you like. But instead of txt you use yml or yaml as a file extension:

1. Create my-first-config.yml
2. Open it in your text editor, or your favorit IDE
3. Add your JSON code as shown above, modify it to your needs
4. Save the file

Validate YML files #

While you can work on YML files with any text editor, using an IDE has benefits.

IDEs do understand the syntax of YML files and can help you with syntax highlighting in case you do something wrong.

Common mistakes #

Here’s some examples I face every now and then when working with YML files.

Wrong indentation #

YML is highly sensitive to indentation. Using inconsistent spaces or mixing tabs and spaces can lead to parsing errors.

Always use spaces for indentation (e.g., 2 spaces per level). Many text editors and IDEs allow you to configure this setting to avoid mixing tabs and spaces.

Improper use of special characters #

Characters like :, #, {, } , [, ], and - have specific meanings in YML. If you want to use them in a string value, you need to wrap the whole string in quotes:

1

title: "Mastering YML (YAML): A guide for Developers, Admins, and Self-Hosters"

Unintended data type interpretation #

YML tries to infer data types, which can lead to unexpected results. For example, writing “yes” or “no” without quotes may be interpreted as booleans instead of strings.

If you want to be sure that your value is interpret as a string, use quotes for the value, e.g.:

1
2

boolean_string_example: "yes"
integer_string_example: "123"