Aadarsh Verma

Posted on May 16

YAML Tutorial: A Beginner's Guide to Writing YAML Files

#devops #programming #yaml #cicd

Hey Guys! This blog will make you understand what YAML is all about.
I'm keeping it simple and easy, so you can grasp it without breaking a sweat.

Let's Begin! What is YAML?

Initially it was called Yet Another Markup Language, but later renamed to YAML Ain't Markup Language (a recursive acronym).

YAML is the cleanest way to write configuration files. I'm guessing you already know we need config files for certain tasks while developing apps or working that DevOps magic. There are multiple ways to write configuration files such as XML, JSON, and TOML (plus several others), but YAML has some distinct advantages.

Why do we need YAML or any other file formats?

These file formats make developers happy and help our data dance from server to server or client to server. They're primarily used for transmitting data between servers and clients, particularly in web applications. These are basic data formats for writing important stuff like secret files, destinations, project configurations, and all those hidden gems that make our coding life easier.

If we dive into the technical side, these files serialize complex data structures into a human-readable format that machines can easily parse. Using these formats allows different tools and systems to play nicely together.

Serialize: The process of converting an object or data structure into a format that can be easily stored or transmitted.

Let's dive into YAML

YAML is like JSON's bigger, cooler sibling (another serializing language)

YAML can do everything JSON does and then some! It's actually a superset of JSON. Unlike JSON, YAML uses indentation (similar to Python) which creates cleaner, more readable code. No brackets, no braces – just clean, clear lines of code.

How to write YAML

The basic structure of YAML is a map (object in JavaScript, dictionary in Python) - just key-value pairs, nothing more.

key: value

Now that you know the secret sauce, let's build some examples:

Object type:

# Key-value pairs
name: Elon Musk
age: 56

# or in flow style (JSON-like)
{name: Elon Musk, age: 56}

YAML offers the braces format for the old-school folks who are stuck in 1972. Hehe...

List type

# List in YAML (block style)
countries:
  - India
  - China
  - Russia

# or in flow style
countries: [India, China, Russia]

Now you know what a list looks like in YAML. Let's keep going...

Multi-line strings

# Literal block scalar (preserves newlines)
description: |
  This is a multi-line string.
  Each line will be preserved.
  Including the line breaks.

Output:

This is a multi-line string.\nEach line will be preserved.\nIncluding the line breaks.\n

The pipe character (|) preserves all newlines in the text.

A way to write in multiple lines but get output in one line:

# Folded block scalar (folds newlines to spaces)
description: >
  This is also a multi-line string,
  but newlines will be replaced with spaces,
  creating one continuous line.

Output:

This is also a multi-line string, but newlines will be replaced with spaces, creating one continuous line.\n

The greater-than symbol (>) replaces newlines with spaces, except for empty lines and more-indented lines.

How a real YAML file looks like

services:
  backend:
    build: backend
    depends_on:
      - db
  db:
    # We use a mariadb image which supports both amd64 & arm64 architecture
    image: mariadb:10.6.4-focal
    # If you really want to use MySQL, uncomment the following line
    #image: mysql:8.0.27
    volumes:
      - db_data:/var/lib/mysql
  frontend:
    build: frontend
    ports:
      - 3000:3000
    depends_on:
      - backend

This is an example of a docker-compose.yaml file. Don't worry if you're not familiar with Docker yet - just focus on understanding the file structure.

We have a top-level services key that contains nested keys for backend, db, and frontend. Each of these has its own nested properties. Notice how the ports key holds a list of values.

Blocks in YAML (Document Separators)

YAML allows multiple documents in a single file using document separators (---):

---
"apple": "Snow white should eat me!!"
22: "this is Aadarsh age"
---
# lists
- apple
- mango
- banana
- Apple
---
cities:
- new delhi
- mumbai
- gujrat

Here we've written 3 separate YAML documents in one file. Save it as config.yaml, and when you run it, it will be treated as three separate YAML documents.

How to end a file?

You can explicitly mark the end of a YAML document using ... (three dots):

services:
  backend:
    build: backend
...

Comments

You can add comments using the # symbol:

- Apple # This is a delicious fruit
- Orange # It's both a fruit and a color

Specify Data types in YAML

YAML can infer data types, but you can also be explicit:

# Explicitly specify types
zero: !!int 0
positiveNum: !!int 45
negativeNum: !!int -45

binaryNum: !!int 0b11001
octalNum: !!int 06574

hexa: !!int 0x45
float: !!float 45.55

commaValue: !!int +540_000 # 540,000
is_active: !!bool true

Common YAML tags include !!str (string), !!int (integer), !!float (float), and !!bool (boolean). You might not need these often, but it's good to know they exist.

Anchors and Aliases in YAML

One of YAML's most powerful features is the ability to reuse content with anchors (&) and aliases (*):

# Define an anchor
base: &base_config
  version: 1.0
  environment: production
  logging: true

# Reuse it with an alias
service1:
  <<: *base_config  # Merge the base_config here
  name: authentication
  port: 8080

service2:
  <<: *base_config  # Same base config reused
  name: payments
  port: 9090

This helps avoid repetition in your YAML files.

Advanced YAML Features

Nested Maps and Complex Structures

YAML excels at representing complex, deeply nested structures:

person:
  name: 
    first: John
    last: Doe
  contact:
    email:
      personal: john.doe@personal.com
      work: john.doe@company.com
    phone:
      - type: home
        number: 555-1234
      - type: mobile
        number: 555-5678
  hobbies:
    - reading:
        genres: [sci-fi, history]
        favorite_book: Foundation
    - gaming
    - hiking

Environment Variables in YAML

Many YAML processors support environment variable interpolation:

database:
  username: ${DB_USERNAME}  # Uses environment variable
  password: ${DB_PASSWORD}
  host: ${DB_HOST:-localhost}  # With default value

YAML Validation

Always validate your YAML files before using them in production! Several online and offline tools can help:

YAML Lint
YAML Validator
yamllint CLI tool

Invalid YAML can cause mysterious errors in your applications - a misplaced space or tab can break everything!

Common YAML Errors and How to Fix Them

Indentation errors: YAML is sensitive to spaces and tabs. Always use consistent indentation (preferably spaces).
Mixing tabs and spaces: Don't mix them! Pick one and stick with it.
Missing quotes around special characters: If your string contains characters like :, {, }, [, ], etc., wrap it in quotes:

   message: "This string contains: special characters"

Incorrect line breaks in multi-line strings: Make sure you understand the difference between | and >.

Real-world Use Cases Beyond Docker

YAML is widely used in:

Kubernetes - for defining containers, pods, services, and entire deployments
GitHub Actions - for defining CI/CD pipelines
Ansible - for configuration management and automation
CircleCI/TravisCI - for continuous integration
Static site generators (Jekyll, Hugo) - for frontmatter in content files
OpenAPI/Swagger - for API documentation

Tools for Working with YAML

yq - Like jq but for YAML, allows command-line manipulation of YAML
VSCode plugins - YAML extension provides syntax highlighting and validation
PyYAML - Python library for YAML processing
js-yaml - JavaScript library for YAML

Conclusion

YAML provides a clean, human-readable way to configure applications and services. Its simplicity and flexibility make it increasingly popular in modern development workflows, especially in cloud-native and DevOps environments.

Key advantages of YAML:

More readable than JSON or XML
Support for comments (unlike JSON)
Rich data structures with less syntax noise
Built-in anchors and aliases for DRY (Don't Repeat Yourself) configurations
Wide adoption in tools like Kubernetes, Docker, and CI/CD pipelines

Whether you're configuring a complex Kubernetes cluster or setting up a simple GitHub Actions workflow, understanding YAML will save you time and headaches. Start with simple configurations and gradually explore its more advanced features as needed.