How to write YAML lists and objects at the correct level

Short answer

A YAML list is a sequence whose items begin with -. An object is a mapping of keys and values separated by :. To create a list of objects, align every list marker and place the additional properties of each item at the same level as the first key after its marker.

A list of simple values

ports:
  - 80
  - 443
  - 8080

The ports key contains a sequence of three numbers. The markers occupy the same column because all three items are siblings. Its JSON equivalent is:

{
  "ports": [80, 443, 8080]
}

A list of objects

servers:
  - name: api-1
    ip: 192.0.2.10
    active: true
  - name: api-2
    ip: 192.0.2.11
    active: false

Each marker starts one sequence item. name, ip, and active belong to the same server mapping. The second marker returns to the column of the first and starts the next item.

The YAML to JSON converter shows two objects inside the servers array. Always inspect the resolved result: valid YAML can still represent a different tree from the one you intended.

The most common level error

This fragment moves active outside the expected structure:

servers:
  - name: api-1
    ip: 192.0.2.10
  active: true

This is invalid YAML, not a valid object with a misplaced field: a mapping entry cannot appear beside the sequence markers at that level. If active belongs to this server, add two spaces before the key:

servers:
  - name: api-1
    ip: 192.0.2.10
    active: true

The corrected JSON contains one server with three properties:

{
  "servers": [{ "name": "api-1", "ip": "192.0.2.10", "active": true }]
}

If active belongs to the whole document instead, move it fully left to align with servers. That version is valid too, but produces a root-level active property outside the array. Choose the correction from the application’s schema, not just whichever indentation makes the error disappear.

Mappings containing lists and lists containing mappings

Structures can alternate as deeply as the format and application allow:

service:
  name: api
  targets:
    - host: db-1
      roles:
        - read
        - write
    - host: db-2
      roles:
        - read

Read from the outside inward: service is a mapping, targets is a list, each target is a mapping, and roles is another list.

Checklist

1. Identify each expected node type: mapping, sequence, or scalar.
2. Align all markers that belong to the same list.
3. Align sibling properties inside every mapping.
4. Never use tabs to define YAML indentation.
5. Convert the sample to JSON and count objects, arrays, and levels.
6. Compare the resulting tree with the application’s schema.

Section 8.2 of YAML 1.2.2 defines block sequences with - indicators and mappings with key/value pairs. Indentation determines which collection owns each node, so changing a column changes the data structure.