🧑‍🏫️ Interactive YAML tutorial

🤔 What is YAML?

YAML (short for YAML Ain't Markup Language) is a language for storing data, designed to be human-readable. One of the common uses for YAML is configuration files. Several cloud computing tools use YAML to configure settings and parameters, including products such as:

• Kubernetes
• Ansible
• CircleCI
• GitLab CI/CD
• GitHub Actions
• Azure DevOps

🧑 Who is this tutorial for?

This tutorial is suited for those with an awareness of JSON. Each example and exercise demonstrates how JSON can be converted to the equivalent YAML format.

📃 Example: simple, flat data

Take a look at the JSON object below, which has three key-value pairs.

The equivalent YAML is below. Each key-value pair is represented as a simple line, with the key followed by a colon and the value. Notice that string values (e.g. Alice) don't need to be written in quotes.

As you can see, the YAML code has less noise and complexity, with the aim of being as readable as possible.

💪 Exercise 1

Welcome to the first exercise! Take a look at the JSON data below representing a character in a video game. Your task is to write the equivalent YAML code in the empty box. Once you're done, hit the "Check answer" button.

📃 Example: arrays

In JSON, arrays are expressed in a similar way as in JavaScript:

In YAML, the syntax looks quite different.

Each item in the array is represented with a hyphen followed by a space, and each item is placed on a new line.

💡 Keep in mind:

• The space after each hyphen is necessary.
• It's not strictly necessary to indent each element, but it is recommended.

💪 Exercise 2

This time, our witch has certain strengths and weaknesses, stored in arrays. Make sure to include all of the data in your answer.

📃 Example: nested data

In JSON, to create nested data, we place an object inside an object. Take a look at the address in the following example:

YAML uses indentation instead. Notice how the "street-name" property belongs to "house", which in turn belongs to "address":

💪 Exercise 3

Our Hexandra now has various spells. You'll need to create a couple levels of nested YAML for this one.

💡 Tip: don't forget the level property.

💪 Exercise 4

It's possible for an array to be nested inside an object. Give this exercise a shot.

📃 Example: arrays of objects

A common but slightly more complex data structure is an array where each element of the array is an object:

Notice how the equivalent YAML syntax logically develops what we've looked at already. Each element of the array (each family member) is indicated separately by a hyphen, but instead of a single value, each array element is a set of key-value pairs.

The example above might feel a little cramped. It's a matter of preference, but adding an extra line between each array element can aid readability.

💪 Exercise 5

Hexandra also has a variety of skills, which can individually be levelled up as the game progresses. You know what to do. 😎

👏 You've got the fundamentals down

If you've completed all the exercises up to this point, then you have the skills to read and write 80-90% of the YAML out there.

Below are a couple of bonus features that are useful to know!

📃 Example: comments

One limitation of JSON is that it can only store data. There's no way to store comments in JSON to help humans understand and contextualise the data.

Thankfully, YAML does support comments, which is super handy. To create one, just place a hash (#) symbol followed by your comment.

Here's an example of using comments to make a (fictional) configuration file easier to scan and decipher:

Feel free to add comments to any of the previous exercises, and notice that it has no effect on your correct answers.

📃 Example: multi-line strings

You can use the > symbol to wrap a long string across multiple lines for convenience.

If you actually want to preserve the line breaks in the resulting string, you can use a pipe |:

Note, in both of the examples above, YAML will add a single line break to end of the string.

You can control how YAML handles multi-line strings - see here.