YAML 101

4 min readSep 27, 2019

---name: YAML
purpose: encoding of data for storage or transmission (data serialization)
types_supported: [strings, floats, ints, dictionaries, lists]

Almost every developer working on a simple web server written to run on Node.js or pretty much any other language runtime must have come across files named: x.yml or x.yaml.

Most of these files are used to hold configurations for Continuous Integration/Deployment (CI/CD) systems or API documentation.

For example .travis.yml` holds configuration for TravisCI and .config.yml` stores configuration information for CircleCI.

The first time I wrote a .yml` file was when I was building an API and needed to deploy this app to the Heroku platform, so I quickly went to the TravisCI website and followed the instructions to create a .travis.yml` file without knowing exactly what .yml files are, but it worked anyway 😆, and TravisCI recognized my .travis.yml file.

And then when I made few mistakes, mostly with indentation putting together my .config.yml file for CircleCI, then it dawned on me that I do not know YAML (YDK_YAML) in Kyle Simpson’s voice 😃.

So, Welcome to the club if you belong to the class of backend developers who don’t know YAML (just yet).

What are `.yml` or `.yaml` files?

.yml or .yaml files are files that store and transmit data written in a language called YAML.

YAML is an acronym for YAML Ain’t Markup Language. It was initially named “Yet Another Markup Language”.

It performs the same purpose like the popular data serialization language: JSON, but it was designed to be a little more human-friendly to read.

Here are a few tips about YAML:

It’s a human-friendly language
It borrows from python style of denoting blocks — through indentation (awesome right?)
YAML supports primitive types like ints, strings, floats, and other types such as lists and maps
YAML is not a markup language (as if that is not obvious from the name 😃)

It’s imperative to know YAML to better understand your configuration files and other types of files written in YAML to get rid of the frustration of your build failing due to syntax error or your build doing something it was not intended to do.

Here’s a simple .yml file:

# the_sun.yml
# line numbers were added to the left, they are not part of the file content1. star: "sun" # sun is a string
2. code_name: yellow dwarf # "yellow dwarf" is also a string
3. planets: [mercury, venus, earth, mars, jupiter] # this is a list
4. mass: 2.0e+31
5. facts: |
  the sun is mostly composed of hydrogen,
  which constitute about 73% of the sun's total matter
  and fellas, this was only used to demonstrate
  how to write multiline strings, that reserve their newlines in YAML

The above file demonstrated the common types that can be represented in YAML for storing and transmitting data.

Let’s start with:

Strings: Most of the contents written in .yml files are simply strings, usually as values to map keys. Strings can be written in a single line or multi-lines

msg: "Hello YAML"
msg: 'Hello YAML'
msg: Hello YAML# All representations of "Hello YAML" are valid. Strings can be double-quoted, single-quoted or zero-quoted.# Here's a multiline string (newlines are preserved):
msg: |
  YAML is not a markup language,
  it is also not a programming language,
  it is a language for storing and transmitting data
  over a network# Here's another multiline string (where newlines are stripped off):
msg: >
  Roses are red,
  Violets are blue,
  and indentation is important
  in YAML.

Integers: Integers are useful for example to specify tag names for say: Docker images, and can be written in YAML files

2 // a valid integer
-4 // another valid integer

Floats: Just like ints, floats can also be represented in YAML as you would express in popular programming language:

DOCKER_IMAGE_TAGS: [8.07, 9.99, 7.900000]

Lists: A list is a collection of values, say you want to store a list of plugins that ESLint rules extends, then you can do this:

extends: [airbnb, prettier]# or we can do this:extends:
  - airbnb
  - prettier
# The second syntax is more common.
# 2 spaces are used for the indentation
# the an hyphen (dash) is used to start the list the item
# and then a space and after that we have the list item value# the indentation here is important

Maps: Maps is another commonly used data type used in most .yml files to associate some value with some key. One thing to take note of when writing maps or hashes are that the key values are spaced from the key and colon by a single space:

person_map:
  name: 'Tyrion Lannister' # key and colon are separated from the value by a space, this is important
  house: 'lannister'
  real_name: 'Peter Dinklage'# NOTICE the space between the colon and the value

I hope these few illustrations have given you more understanding of the YAML syntax and semantics. You can explore more about YAML on the site: https://yaml.org/

I intend to follow this article with another to illustrate some advanced YAML. Happy hacking Devs.

As you write .yml files, you may need a linter for validation or tools that can convert from YAML to JSON. There are great tools for these purposes:

Linting/Validation: http://www.yamllint.com/
Conversion/Validation: https://codebeautify.org/yaml-to-json-xml-csv

YAML 101

What are .yml or .yaml files?

Here are a few tips about YAML:

Written by Micah Akpan

What are `.yml` or `.yaml` files?