ASB Notebook

Introduction to YAML: Basics and Advanced Concepts

YAML(YAML Ain’t Markup Language) is a human-readable data serialization standard. Many applications, tools and frameworks(Ex: Spring Boot, Docker, Kubernetes, GitHub, AWS, etc.) use YAML widely to write the configuration files. YAML is easy to read and write, which makes it a widely used language in the configuration management. In this article, we will get an introduction to YAML.

We will learn how to create simple YAML files. We will also understand the basic syntax of the YAML.

Let’s start.

A Simple YAML file

A YAML file can have the extension .yaml or .yml. YAML is also case sensitive.

A YAML file holds key and value pair as shown below. The “:” and space character separates the key and value.

We can use different types of values like number, Boolean, String, etc.

name: Arun
location: India
phone: 1234567890

Defining a List

To define a YAML key with multiple values, we can use the below format.

The values are defined by first adding the “–” character. Then add a space character. Finally, include the value of the item of the list.

Each item of the list can be defined in the separate line as shown below. Make sure to use the proper indentation also.

hobbies:
  - travelling
  - reading
  - hiking

Defining a little complex type

We can use YAML to define a hierarchy of data.

In the below example, we can see a complex data type. It has the key address along with other sub details, like pin, street, etc.

Notice that, each sub key-value pair should be in the same indentation level. We can also have multiple levels of sub key-value pairs.

address:
  street: 11 Main street
  zip_code: 123456
  city: Bangalore

Scalar Data types in YAML

Scalar data types contain a single value.

YAML supports different type of values like: String, Numbers, Boolean, Date & Time, Null, Binary, etc.

Below YAML data shows few of the supported YAML data types:

name: Arun
age: 32
weight: 65.2
is_student: true
flag: Yes
null_value1: null
null_value2: ~
null_value3:
  • In the above YAML data the name value is interpreted as a string.
  • YAML interprets the age value as an int.
  • YAML interprets the weight value as a float.
  • YAML interprets the is_student value as a boolean.
  • The flag value is interpreted as a String in YAML version 1.2 and above, and it is interpreted as a boolean in YAML version 1.1 and below.
  • The null value can be specified with the help of null, ~ or an empty value. The null_value1, null_value2 and null_value3 keys above are specifying null values.

String YAML values

We can use “”, ” or no quotes to represent a string.

If a string value holds any special character(Ex: hello!’), we can use ”(single quotes) to define them as YAML value.

We can use “”(double quotes) to define strings, if it holds escape sequences(Ex: “Line 1 \nLine 2”).

first_name: "Arun"
last_name: SB
gender: 'M'

Multi Line String values(Literal Block Style)

To define a string value with multiple lines, we can use the ‘|’ (pipe symbol).

Below example shows the usage of the same.

multi_line_string: |
  Line 1
  Line 2
  Line 3.

Folded Block Style:

We can use the ‘>’ symbol to fold new lines into spaces. This is helpful when we don’t want to introduce new lines while defining a big paragraph block.

folded_text_block: >
  This is sentense one.
  This sentense also appears in the same line as above sentence.

We can also use + and – symbols to retain or remove the line breaks in the string value along with the symbols | and >.

Below example shows how to keep the line breaks. YAML preserves the 2 new lines in the parsed output YAML value.

folded_text_block: >+
  This is sentense one.
  This sentense also appears in the same line as above sentence.

Comments inside YAML file

  • Single line comments: We can use ## symbols to define single line comments.
  • Multiple line comments are not supported by YAML, but we can use # symbol for each line of comment.
  • We can use comments along with the key-value pair, in a single line.
# Single line comment

# Two line
# comment

key: value # comment for value.

Date and time values

YAML interprets certain date and time values and considers them as date and timestamps.

The default pattern for date value is YYYY-MM-DD and default pattern for timestamp is YYYY-MM-DDTHH:MM:SSZ

We can also use the time zone while defining the timestamp values with the pattern: YYYY-MM-DDTHH:MM:SS+/-HH:MM

date: 2024-10-02
date_timestamp: 2024-10-02T11:11:11Z
date_timestamp_with_time_zone: 2024-10-02T11:11:11 +05:30

We can also define date timestamp values as shown below. Here, a space character separates the date and time and time zone.

date_timestamp_with_time_zone: 2024-10-02 11:11:11 +05:30
date_timestamp: 2024-10-02 11:11:11

Tags in YAML

We can explicitly define the data types while defining YAML values.

We can use !!<data-type> to explicitly define the data-type of the YAML values.

name: !!str Arun # string data type
age: !!int 32 # int data type

Advanced Data types in YAML

Let’s see some of the advanced data types used in YAML.

Collections/Sequences in YAML

In YAML sequences(or collections/lists) can be used to represent a list of values.

Block style: In this type of representation, each element of the sequence is defined in a new line. Each element uses a dash ‘–‘ symbol and a space.

Flow style: In this style of representation, each element of the sequence is defined in a single line. Elements are defined inside a []. This style is similar to JSON-like style.

# Block style
hobbies:
  - reading
  - writing

# Flow style
hobbies: [reading, writing]

Sequence of mapping in YAML

In YAML, sequence mappings combines sequences(list) and mapping(dictionaries) to create complex structures.

# Block style
students:
  - name: Arun
    age: 32
  - name: Raj
    age: 33

# Flow style
students: [
    {name: Arun, age: 32},
    {name: Raj, age: 33}
    ]

Mapping of sequences

Mapping of sequences in YAML holds a dictionary, where each key maps to a sequence or list of values.

# Block style
student:
  hobbies:
    - Reading
    - Writing
  subjects:
    - Computer science
    - Maths
# Flow style
student: {hobbies:[Reading, Writing], subjects: [Computer science, Maths]}

Sets in YAML

In YAML, set of values defines a values collection with no duplicates.

Sets are represented as a mapping where each key is linked with a null value.

Sets in YAML also uses explicit !!set tag. Each item in the set also uses the ? symbol.

hobbies: !!set
  ? Reading
  ? Writing
  ? Hiking

Ordered mapping

We define ordered mapping in YAML using the !!omap tag.

In YAML ordered mapping preserves the order of the key-value pair while parsing.

scores: !!omap
  - Maths: 85
  - Computer Science: 90
  - Physics: 90

Defining a complex key in YAML

A complex key can contain long string, sequences and mappings.

We can use ? symbol followed by a space at the beginning of the key to define a complex key in YAML.

? What is your name? 
: Arun

? | 
  Which is your 
  favorite sport? 
: Cricket

? - Reading
  - Writing
: Hobbies

Anchors and Aliases in YAML

  • Anchors: We can defining a piece of data, and re-use it later in the document with the help of Anchors in YAML. We define anchors using the symbol & followed by the name.
  • Aliases: To create references to the Anchors, we use aliases in YAML. We define aliases using the symbol * followed by the anchor name. Aliases allowed us to re-use the anchored data elsewhere in the YAML file.
  • Overriding Aliases: Sometimes we want to override the anchors and add extra information for a YAML value. For this we can use the <<: characters before the alias to add more values.
time_table:
  schedules:
    - week_day: &work_day # Anchor
        wake_up: 5.30 AM
        activities:
          - workout
          - office work
          - sleep
        go_to_bed: 11 PM 
    - week_end: &non_working_day # Anchor
        wake_up: 7.30 AM
        activities:
          - workout
          - go to movie
          - sleep
        go_to_bed: 12 AM
  week_planning:
    - monday: *work_day
    - tuesday: *work_day
    - wednesday: *work_day
    - thursday: *work_day
    - friday: *work_day
    - saturday: *non_working_day # Alias for non_working_day
    - sunday:
      <<: *non_working_day # Overidin the alias
      go_for_hiking: true
  • We have 2 anchors with the name: &work_day and &non_working_day.
  • These anchors are used with the help of aliases in the week_planning section.
  • We have also overridden the alias &non_working_day for the value sunday, and added an extra YAML field: go_for_hiking: true

In the example above, we have defined a schedule details using the YAML format.

Multi document support in YAML

YAML supports multiple documents in a single YAML file.

We can use ‘—‘ characters for the same.

We can also optionally specify the end of document with the help of ‘…’

# First document
key1: value2
key2: value2
---
# First document
key1: value2
key2: value2
...

Conclusion

In this article, we learned what is YAML, how it is used to define the application configurations.

We also learned basic and advanced syntax of the YAML and few simple examples for the same.

Introduction to YAML: Basics and Advanced Concepts

Discover more from ASB Notebook

Subscribe to get the latest posts sent to your email.

Leave a Reply

Scroll to top

Discover more from ASB Notebook

Subscribe now to keep reading and get access to the full archive.

Continue reading