The YAML format (YML) is a language made especially for data, mainly used for configuration files. It has caught on in recent years together with languages such as XML or JSON. One of its major peculiarities is the possibility of writing the format by indenting the nesting of the various contents and objects inside it with spaces. This makes reading cleaner and more human-friendly.
We can however write it using more syntax, json style.
Another great quality of its is the inclusion of comments, which we will explain later.
Nest contents in YAML format: >
It is possible to nest contents inside others through the use of two spaces for the nested object.
Personally I don’t appreciate this possibility very much. The choice is very subjective and depends more on the source languages, based more on indentation.
wizard:
name: Harry
favoriteSpell: Expelliarmus
age: 42
The object type in the YAML format: >
Let’s start from the object type (or map). The reason is that it will be the most common type together with the basic types. For example, in configuration files we will find lists of objects in key-value format. There are two variants of this typology, depending on the syntax you want to use. We can also enter keys with spaces, although not recommended, with " or ' wrapping.
The most concise and the one that is used the most is a simple list with colons dividing the keys from the values.
label: "User"
name: "Harry"
job: "wizard"
"favorite spell": "Expelliarmus"
It is important to keep the same spacing before the key, in this language and with this syntax variant.
{ label: "User", name: "Harry", job: "wizard" }
The string type in YAML format: >
The classic basic type of any language based on a text format. We can enter a string surrounded by single ', double " or even no quotes. It is always advisable to include quotes because some particular keywords can be cast to other formats. For example, if you enter the value true or false which are boolean types or even more unexpected strings such as the characters Y and N, which are also translated into boolean anyway.
label: "User"
name: 'Harry'
job: wizard
The numeric string variant: >
The numeric types in this language depend a lot on who is going to read the yaml file. Usually, if a correct numeric format is found, without quotes, integer or decimal with point, a normalization of the data can be performed. For instance a trim of the excess zeros.
old: 42
yearsOfMagicSchool: 005.600 # Print 5.6
The block string variant: >
We can also enter this type in block mode. This by prefixing the string with either the > character or the pipe | character. On the contrary, the compilation of the language will go into error, not inserting any of the two characters. For instance if we go with a new line in a string, even if using quotes. In addition to this block format, you can trim the string externally. We get it by appending the hyphen character - immediately following the string block characters.
An example for both.
wizardDescription: >
A magician is a person capable of accomplishing
spells and enchantments.
wizardDescription: >-
A magician is a person capable of accomplishing
spells and enchantments,
as the trim of this text.
The boolean type: >
The binary type to identify if a property is true or false. As explained in the previous paragraph, some strings or characters can become boolean if you do not perform precise typing using single or double quotes.
isWizard: true
isHuman:N# Gets false
The list type: >
The list type is also heavily used within YAML configurations. As well as maps, we can use it both in its peculiar formatting through indentation and more in JSON style. To create a list in YAML we put a dash in front of each element of our list. Obviously this type of syntax can be mixed with all other types, both objects and block strings.
In this format it is not necessary that all elements of the list have the same properties, despite the typing in other languages.
Two examples of lists of strings or objects.
- Bananas.
- Apples.
# ...
- name: Harry
job: wizard
- name: Hermione
job: witch
The JSON-like format exists for lists too, with square brackets [] and commas to express the elements of a list.
["Harry", "Hermione"]
The comment: >
One of the strengths of YAML (compared to the more used JSON), is the possibility of inserting comments. The possibilities of this syntax are evident when, for example, we have to insert a well-defined range of configurations. We’ll have to indicate which ones are possible.
Examples of this syntax are in all this article.
# A comment.
name: Harry # Another comment.
# name: Hermione but is a comment.
Less used syntax in the YAML format
Now let’s look at lesser-used but still possibly useful syntax within this format.
Anchors (or tags)
We can establish a value in a different portion of the file that we can recall several times, through the use of a special anchor. By placing the ampersand & character before it, the tag can be created and it can be recalled with the asterisk * character. Personally little used due to the rigidity of the syntax. For example I can’t call a tag created inside a larger string.
variables:
&name Harry
# ... other contents ...
wizards:
wizardName: *name # Prints Harry
Multiple documents
We can have this possibility by inserting 3 dashes appended within our file, to define both the beginning and the end of our document. This approach could be useful, for example, for inserting meta information into our document in md format. This is done by placing all the necessary properties between dashes.
---
name: Harry
# The yaml part ends and the md part begins.
---
Harry was a wizard.
Content typing
You can force data typing. The only example I can think of of this usage is for example keeping the character Y as a string instead of allowing it to be cast to boolean.
For typing, we use the double exclamation point !!, followed by the type and the value.
- isWizard: !!str Y # Prints "Y"
- isWizard: !!bool Y # Prints "true"
That’s all for today.
Try it at home!
