Nested YAML

Nested YAML means placing one data structure inside another. A mapping can contain another mapping. A list can contain mappings. A mapping can contain lists. This ability to combine structures is what makes YAML powerful enough to represent complex real-world configurations in a clean, readable way.

Nesting is controlled entirely by indentation. Each level of nesting adds more leading spaces.

Why Nesting Is Important

Real applications have complex settings. A web server does not just have one hostname — it might have a hostname, a port, SSL settings, timeouts, and logging levels. Nesting allows all these related settings to be grouped together under meaningful parent keys rather than scattered as independent flat entries.

Level 1 – Simple Flat Mapping (No Nesting)

name: Alice
age: 28
city: Delhi

All keys are at the same level. There is no hierarchy here. This is the simplest form of YAML.

Level 2 – One Level of Nesting

person:
  name: Alice
  age: 28
  city: Delhi

Now name, age, and city are all nested inside person. They are indented by 2 spaces, showing that they belong to person.

Level 3 – Two Levels of Nesting

person:
  name: Alice
  address:
    street: 12 Main Street
    city: Delhi
    country: India

Here, address is nested inside person. Then street, city, and country are nested inside address. This creates two levels of nesting.

Nesting Depth Diagram

Level 0 → person:
Level 1 →   name: Alice
Level 1 →   address:
Level 2 →     street: 12 Main Street
Level 2 →     city: Delhi
Level 2 →     country: India

Nested Mapping Inside a List

A list can contain mappings. Each list item becomes a full object with its own key-value pairs. This is one of the most common patterns in YAML configuration files.

servers:
  - host: web-01
    ip: 192.168.1.1
    role: web
  - host: db-01
    ip: 192.168.1.2
    role: database
  - host: cache-01
    ip: 192.168.1.3
    role: cache

The servers key holds a list. Each item in the list is a mapping with host, ip, and role keys.

List Inside a Mapping

A mapping can contain a list as a value.

developer:
  name: Bob
  skills:
    - Python
    - JavaScript
    - YAML
  certifications:
    - AWS Solutions Architect
    - Docker Certified Associate

The developer mapping has two keys whose values are lists: skills and certifications.

Deep Nesting Example – Application Config

application:
  name: ShopEasy
  version: 3.2.1
  environment: production
  server:
    host: 0.0.0.0
    port: 443
    tls:
      enabled: true
      cert: /etc/ssl/cert.pem
  database:
    host: db.shopEasy.com
    port: 5432
    name: shopdb
    credentials:
      username: admin
      password: secret123
  features:
    - name: dark_mode
      enabled: true
    - name: two_factor_auth
      enabled: false

Structure Diagram for This Example

application
  ├── name
  ├── version
  ├── environment
  ├── server
  │     ├── host
  │     ├── port
  │     └── tls
  │           ├── enabled
  │           └── cert
  ├── database
  │     ├── host
  │     ├── port
  │     ├── name
  │     └── credentials
  │           ├── username
  │           └── password
  └── features
        ├── [0] name: dark_mode, enabled: true
        └── [1] name: two_factor_auth, enabled: false

Inline (Flow) Nested Structures

Nested structures can also be written in flow style for compact representation.

# Nested mapping in flow style
address: {street: "12 Main St", city: Delhi, country: India}

# Nested list in flow style
skills: [Python, JavaScript, YAML]

# Combined
person: {name: Alice, skills: [Python, YAML], address: {city: Delhi}}

Flow style is compact but becomes hard to read when nesting goes deep. Use it only for shallow structures with few items.

Common Nesting Mistakes

Accessing Nested Values – How Tools Read YAML

Most programming languages and tools access nested YAML values using a dot notation or bracket notation.

# Given this YAML:
app:
  database:
    host: localhost

# Python reads it as:
# config['app']['database']['host']  →  "localhost"

# Some tools use dot notation:
# app.database.host  →  "localhost"

Summary

• Nesting places one data structure inside another using indentation
• Each level of nesting adds more leading spaces (use 2 spaces per level)
• Mappings can contain other mappings, lists, or both
• Lists can contain mappings, creating a list of objects
• Consistent indentation is critical — mixing tabs and spaces causes errors
• Deep nesting is powerful but keep it readable by limiting depth where possible