Quiz Entry - updated: 2026.11.05
When should data in YAML be a list, and when an object (mapping)? Why is a playbook a list of plays, but the arguments of a module an object?
Use a list for an open-ended sequence of similar items: order matters, duplicates are allowed, and you reach items by position. Use an object to describe one thing by its named properties: each key is unique, key order doesn't matter, and you reach values by key.
* Plays and tasks are lists because more can follow in order; module arguments are one object. *
| List (sequence) | Object (mapping) | |
|---|---|---|
| Models | A collection that can grow: users, servers, steps | One thing's properties: a user, a server, a service |
| Order | Defined and meaningful | Not meaningful |
| Duplicates | Allowed (- Bob twice is fine) |
Every key unique within the object |
| Access | By index (position) | By key name |
| Syntax | One - per item |
key: value lines, no dashes |
users: # list: more users can be appended, "Bob" may repeat
- Alice
- Bob
user: # object: the properties of one user
name: Alice
age: 30
active: true
A playbook follows the same reasoning at every level:
- The playbook is a list of plays, because you can always add another play ("now configure the database servers"), and plays run in the order written.
tasks:is a list of tasks for the same reason: an extendable sequence of steps that run one after another.- The arguments of a module are an object.
ansible.builtin.apt: {name: apache2, state: present}lists properties of a single desired state. Each argument appears once, and swappingnameandstatechanges nothing.
A quick test: ask "could there be another one, and does the order matter?" If yes, it's a list. If you are setting named attributes of a single thing, it's an object.
Go deeper:
YAML Syntax: YAML basics (official docs) — lists and dictionaries, and how playbooks nest them.
YAML 1.2.2 specification: sequences and mappings — the spec's own examples of sequences, mappings and their nesting.
YAML: syntax (Wikipedia) — sequences and mappings, block and inline style.