Understanding Lists and Dictionaries in YAML¶

YAML is designed to be human-readable, but sometimes its structure can be confusing, especially when it comes to how lists and dictionaries work together. This guide clears up the concepts with examples, diagrams, and easy explanations.

1. Lists (Arrays) in YAML¶

Lists are ordered collections of items.
Each item in a list is always prefixed with a hyphen (-).

Example:¶

fruits:
  - apple
  - banana
  - orange

Explanation: - fruits: is a dictionary key. - Its value is a list. - Each fruit (apple, banana, orange) is a separate list item, indicated by -.

2. Dictionaries (Maps) in YAML¶

Dictionaries are unordered collections of key-value pairs.
No hyphen (-) is needed for dictionary keys.

Example:¶

person:
  name: Muhammad Ibtisam
  age: 25
  occupation: DevOps Engineer

Explanation: - person: is a dictionary key. - Its value is another dictionary (keys: name, age, occupation). - Each key-value pair is written normally without a hyphen.

3. Lists of Dictionaries¶

Now comes the part where people often get confused:

You can have a list where each item is a dictionary.

In that case: - Each dictionary starts with a hyphen (-). - Inside each dictionary, key-value pairs are written normally (no extra hyphens).

Example:¶

users:
  - name: admin
    role: superuser
  - name: guest
    role: read-only

Explanation: - users: is a dictionary key. - Its value is a list. - Each - indicates a new dictionary (a user object). - Inside each dictionary, you list keys (name, role) without hyphens.

4. Visual Representation¶

users
|— List
   |— Dictionary (User 1)
       |-- name: admin
       |-- role: superuser
   |— Dictionary (User 2)
       |-- name: guest
       |-- role: read-only

5. Quick Rules¶

Concept	Rule
List Item	Always use `-` before an item.
Dictionary Key	No `-` needed; just `key: value`.
List of Dictionaries	`-` at the start of each dictionary. Inside dictionaries, use normal `key: value` style.

6. Real-World Analogy¶

Imagine a shopping list:

The list itself has bullets (-).
Each item like "Apples" can have more details (color: red, weight: 1kg), but you don't put bullets for each detail, only for each item.

Similarly in YAML: - Use - for each list item. - Inside, describe the item with normal key-value pairs.

7. Common Mistake¶

Wrong: (Putting - before every dictionary key)

users:
  - name: admin
  - role: superuser  # Wrong!

Right: (Only use - once per dictionary)

users:
  - name: admin
    role: superuser

8. Validation Tip¶

To avoid mistakes in YAML structure, you can use online validators like yamllint.com. It helps catch errors like wrong indentation, extra/missing hyphens, and type mistakes.

Pro Tip: Always validate your YAML before applying it in production environments (especially Kubernetes!).

Final Takeaway¶

Hyphen - = "Hey YAML, this is a new list item!"

Inside a dictionary, just use key: value normally.