Imagine you are a DevOps engineer preparing to deploy a Node.js application. Your application needs a database, a backend server, and a few environment settings. You create a configuration file, run the deployment command, and suddenly everything fails because of two extra spaces.

You check the error logs and discover that the problem is not your application code. It is your YAML file. This happens more often than you might think. YAML is easy to read, but its indentation rules can confuse beginners. Once you understand how YAML organizes data, writing configuration files becomes much easier. In this guide, we will learn YAML syntax using simple examples and practical situations from everyday software development.

What Is YAML?

YAML stands for YAML Ain't Markup Language. It is a human-readable format used to store structured data, especially configuration settings. Developers commonly use YAML with Docker Compose, Kubernetes, GitHub Actions, and other DevOps tools. For example, imagine you want to store your application's name, port, and environment:

app:
  name: my-api
  port: 5000
  environment: development

Even without knowing YAML, you can probably understand what this configuration means. The app key contains three settings: name, port, and environment. YAML stores this information. Your application or the tool reading the file decides what to do with it.

1. YAML Uses Key-Value Pairs

The first thing you need to understand is the key-value pair. A key is the name of a setting, and its value is the information assigned to it.

name: Sumit
role: Developer
city: Nagpur

Here, name, role, and city are keys. Their corresponding values are Sumit, Developer, and Nagpur. Notice that a colon separates each key from its value.

Incorrect YAML:

name Sumit

Correct YAML:

name: Sumit

A missing colon can cause a parsing error. When writing YAML configuration files, check that every mapping entry uses the correct key: value structure.

2. Indentation Defines the Structure

This is one of the most important YAML rules. In JSON, you use curly braces to group related properties. In YAML, indentation shows which properties belong together. For example:

server:
  host: localhost
  port: 5000

The host and port settings belong to the server object because they are indented beneath it. Now look at this example:

app:
  name: my-api
  database:
    host: localhost
    port: 27017

Here, database is nested inside app, and host and port belong to database. As a full stack developer, you can think of this structure as a nested JavaScript object:

const app = {
  name: "my-api",
  database: {
    host: "localhost",
    port: 27017
  }
};

Both represent the same basic data structure. A practical tip: Use spaces instead of tabs for YAML indentation. Two spaces per level is a common convention, although YAML permits other consistent indentation widths.

3. How to Write Lists in YAML

Sometimes a configuration needs multiple values instead of a single value. For example, your application might support several programming languages or run several services. YAML represents a list using a hyphen followed by a space.

languages:
  - JavaScript
  - Python
  - Java
  - Go

The languages key contains four list items. You can also create a list of objects:

services:
  - name: frontend
    port: 3000
  - name: backend
    port: 5000

Each item represents a service with its own name and port. This structure is useful when describing services, deployment targets, test environments, or other collections of settings.

4. Working with Strings, Numbers, and Boolean Values

YAML supports different types of values, including strings, numbers, Boolean values, and null.

app:
  name: my-api
  port: 5000
  enabled: true
  debug: false
  description: My application

In this example:

• name is a string.

• port is a number.

• enabled is a Boolean with the value true.

• debug is a Boolean with the value false.

• description is a string.

You can also use quotes around strings:

version: "1.0"
employee_code: "00123"

Why does this matter? Because a version number or employee code might need to remain text rather than be interpreted as a number. YAML parsers can also differ in how they interpret some values, depending on the YAML version. For predictable results, use true and false for Boolean values and quote strings that must remain strings.

5. How to Add Comments in YAML

When working on a team, you will often need to explain why a configuration setting exists. YAML supports comments using the # character.

server:
  host: localhost
  port: 5000  # Port used by the backend

Everything after the comment marker on that line is treated as a comment, provided the marker is not inside a quoted string. Comments are useful when another developer needs to understand your configuration without searching through the source code. Remember that comments are for humans. They are not included as data when the YAML file is parsed.

6. Using YAML in Docker Compose

Let's move from basic syntax to a real development task. Suppose you are building a MERN application. You have a Node.js backend and a MongoDB database. You want your teammates to start both services without configuring every container manually. Docker Compose uses YAML files to describe these services.

services:
  backend:
    image: node:22
    ports:
      - "5000:5000"
  database:
    image: mongo:8
    volumes:
      - mongo_data:/data/db
volumes:
  mongo_data:

This configuration defines a backend container and a MongoDB container, along with a named volume for database storage. The ports list maps port 5000 on the host to port 5000 in the container. The volumes section helps keep database files outside the container's temporary writable layer.

A real application may also need a startup command, application code, environment settings, and a database connection string. The example focuses on the YAML structure rather than providing a complete production setup.

7. Using YAML in Kubernetes

Kubernetes uses YAML manifests to describe resources such as Deployments and Services. Imagine you want Kubernetes to run two instances of your backend application.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: backend
spec:
  replicas: 2
  selector:
    matchLabels:
      app: backend
  template:
    metadata:
      labels:
        app: backend
    spec:
      containers:
        - name: backend
          image: my-backend:1.0
          ports:
            - containerPort: 5000

Let's understand the important parts:

• kind: Deployment tells Kubernetes what type of resource you are defining.

• metadata.name gives the resource its name.

• replicas: 2 specifies the desired number of application instances.

• containers defines the container configuration.

As a DevOps engineer, you can update the desired replica count in the manifest and apply the configuration to the cluster.

However, valid YAML does not guarantee a successful deployment. The image must exist, the cluster must be able to access it, and the resource configuration must meet Kubernetes requirements.

8. Common YAML Mistakes to Avoid

Even experienced developers can make YAML mistakes, especially when editing large configuration files.

Here are the problems worth checking first:

Incorrect indentation

app:
  name: my-api
    port: 5000

The port property is indented differently from name. If both properties should belong to app, align them correctly.

Using tabs for indentation

YAML does not allow tab characters for indentation. Configure your editor to insert spaces.

Forgetting the space after a list hyphen

Write - JavaScript, not -JavaScript, when defining a list item.

Repeating the same key

Avoid duplicate keys in a mapping. Different parsers may reject them or handle them differently.

Assuming valid YAML means valid configuration

A YAML file can pass syntax validation but still contain an invalid port, a missing environment variable, or an unsupported setting.

9. How to Validate YAML Before Deployment

When your YAML file fails, do not keep changing spaces randomly. Follow a simple process:

• Read the error message and note the reported line.

• Check the indentation around that line.

• Verify colons, list items, and nested structures.

• Validate the file using a YAML parser or the target tool.

• Test the configuration in a development environment before deploying it to production.

If your data starts in JSON, you can use a JSON to YAML converter to convert valid JSON into YAML. Review the output afterward, especially if the file will be used by Docker, Kubernetes, or a CI/CD pipeline.

Conclusion

YAML becomes much easier once you understand its core rules: key-value pairs use colons, indentation defines nesting, lists use hyphens, and comments start with #.

For full stack developers, YAML can simplify service configuration and local development. For DevOps engineers, it is an important part of managing Docker Compose services, Kubernetes resources, and automated deployment workflows.

Start with small examples, learn to recognize nested structures, and validate your files before deploying them. You do not need to memorize every YAML feature at once. Understanding these basics will give you a solid foundation for working with real-world configuration files.