YAML Mappings

A mapping in YAML is a collection of key-value pairs. It is the most fundamental structure in YAML. Every configuration file built with YAML uses mappings. Other names for this concept in different programming languages include dictionary (Python), object (JSON/JavaScript), and hash (Ruby).

In a mapping, each key is unique and maps to exactly one value. The key and value are separated by a colon followed by a space.

Basic Mapping Syntax

key: value

Example

name: Alice
age: 28
city: Mumbai
is_active: true

This is a flat mapping with four key-value pairs. Each line is one entry. Keys are on the left and values are on the right.

Mapping Structure Diagram

+---------------------------+
|       YAML Mapping        |
+---------------------------+
|  name:      Alice         |
|  age:       28            |
|  city:      Mumbai        |
|  is_active: true          |
+---------------------------+
         ↑           ↑
        Key         Value

Block Style vs Flow Style

Like lists, mappings also support two writing styles.

Block Style (Recommended)

person:
  name: Alice
  age: 28
  city: Mumbai

Flow Style (Compact)

person: {name: Alice, age: 28, city: Mumbai}

Both styles produce identical data. Block style is easier to read and is preferred for large configuration files. Flow style works well for short inline mappings.

Keys in Mappings

Keys in YAML are usually plain strings. However, YAML allows more complex key types using a special syntax called complex mapping keys, marked with a question mark.

Simple String Keys (Most Common)

host: localhost
port: 8080
debug: false

Quoted Keys (When Key Has Special Characters)

"server.host": localhost
"content-type": application/json

Complex Keys (Advanced, Rarely Used)

? - item1
  - item2
: list_value

The question mark syntax is almost never needed in everyday YAML writing. It appears in very specialized use cases.

Mapping Values Can Be Any Type

A value in a mapping can be a string, number, boolean, null, another mapping, or a list.

app:
  name: MyApp
  version: 2.1
  debug: false
  owner: null
  tags:
    - web
    - api
  database:
    host: localhost
    port: 5432

Here, tags holds a list and database holds a nested mapping. This is a real-world style configuration for a software application.

Nested Mappings

A mapping can contain another mapping as a value. This creates a hierarchy of data.

server:
  host: 0.0.0.0
  port: 443
  tls:
    enabled: true
    cert_file: /etc/ssl/cert.pem
    key_file: /etc/ssl/key.pem

The key tls contains its own mapping with three keys. Indentation shows that enabled, cert_file, and key_file all belong to tls, which itself belongs to server.

Nested Mapping Hierarchy Diagram

server
  ├── host: 0.0.0.0
  ├── port: 443
  └── tls
        ├── enabled: true
        ├── cert_file: /etc/ssl/cert.pem
        └── key_file: /etc/ssl/key.pem

Key Uniqueness Rule

Within the same mapping level, all keys must be unique. Duplicate keys are not officially allowed in YAML. Some parsers accept them and use the last value, but this behavior is unreliable and should be avoided.

# Wrong – Duplicate keys
name: Alice
name: Bob   ← This overwrites the first 'name' in some parsers

# Correct – Unique keys
first_name: Alice
last_name: Bob

Mapping vs List – When to Use Which

Real-World Example – Kubernetes ConfigMap

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
  namespace: default
data:
  APP_ENV: production
  LOG_LEVEL: info
  MAX_CONNECTIONS: "100"

The metadata key holds a mapping with name and namespace. The data key holds a mapping of environment variable names and their values.

Real-World Example – Ansible Playbook Task

- name: Install nginx
  apt:
    name: nginx
    state: present
    update_cache: true

The apt key maps to a nested mapping with three settings. This pattern is extremely common in Ansible playbooks.

Summary

• A YAML mapping is a collection of key-value pairs
• Keys and values are separated by a colon followed by a space
• Block style is preferred over flow style for readability
• Values can be strings, numbers, booleans, lists, or other mappings
• Keys within the same mapping must be unique
• Nested mappings create a hierarchy of data using indentation