What is YAML?

YAML stands for “YAML Ain’t Markup Language” and it is extensively used in configuration files. YAML is popular because it is a human-readable structured data.

Usually, all kind of configuration settings such as server config, application config, docker-compose configs, and etc. are stored in this format. YAML standard has been created to make it simple to use and read. It is supported in all major programming languages.

Technically, it is a human-friendly data serialization standard for all programming languages. A YAML file has .yaml or .yml file extension e.g. application.yaml, docker-compose.yml etc.

Below is a sample yml or yaml file (application.yml – used in a spring-boot application). For simplicity, you can consider this as a better alternative of .properties or .json config files.


Basic rules to follow

As I said above, YAML is a data serialization standard which focuses on easy to use. It is well supported in all major programming languages via frameworks or libraries. There are few rules you need to follow, and these are described below.

  1. YAML is case sensitive. Take care of the property names and values accordingly.
  2. A yaml file has .yml or .yaml file extension. Certain platform limitations may only support .yaml.
  3. It only supports space, don’t use tab for indentations.
  4. - and --- are special characters in this standard.
  5. If a string contains - or ---, use double quotes “my-string”.

YAML Specifications

Apart from readability and ease to use, YAML excels at working with scalars (strings / numbers), collections (hashes / dictionaries) and structures (arrays / lists). You can relate it with JSON. Continue reading below to understand how each of these datatypes are specified in this standard.

1. Specifying comments

Use # to specify comments, YAML only supports single line comments, no block comments supported yet.


2. Scalars – numbers, strings, booleans.

Scalars are like variables in programming languages, use : to specify the key:value.  Check the example in yaml and json for better understanding.





3. Collections – List, dictionary

List/Array is a collection of data. Dictionary is a collection of key:value data.

List in yml


List/Array in json


Dictionary in yaml


Dictionary – Objects in json.


4. Multi documents

YAML allows multiple documents to be embedded in a single file, unlike json. Every document has to start with ---, optionally end with ... .


5. A complete YAML file example



YAML specification is simple to read as long the content is less. In my opinion, a huge yaml file will be difficult to read and understand especially if it is nested. YAML is not 100% platform independent, there are certain features which is platform specific (read the official spec for details). Also, yaml-parsers are complex, heavy and slow as compared to JSON parsers.

I advice to use it only for configuration purposes, where the application only reads the file during bootstrap or occasionally to reload. Also, make sure you use a yaml-linter in your IDE to avoid errors.