YAML explained: mappings, lists, and indentation

A YAML file is easier to read when you see the structure behind the text. A colon connects a key to a value. A dash can start a list item. Indentation helps show which values belong inside which collections.

Read YAML as structured data. When a program loads the file, it reads values and collections; it does not execute each line like a shell command.

This guide follows the examples in the attached structure diagram, then applies the same reading method to a Kubernetes manifest.

What is YAML?

YAML stands for YAML Ain’t Markup Language. It is a data serialization language often used for configuration. Its main building blocks are scalars, mappings, and sequences, described in the YAML 1.2.2 specification.

Building block	Plain-English meaning	Example
Scalar	One value	Ram, 30, or true
Mapping	Key/value pairs, often called a dictionary	name: Ram
Sequence	An ordered list of items	- Docker followed by - Kubernetes

Collections can contain other collections. That is how a short configuration becomes a nested structure.

Watch the structure build, step by step

The motion diagram pairs each YAML example with its structure tree. The code stays unchanged during playback. Highlights guide attention to the current concept rather than suggesting the data is changing.

Open the interactive YAML diagram in a full browser tab.

Use Play to follow all six stages, or Next and Previous to pause on an idea. On narrow screens, scroll horizontally inside the diagram to compare its code and tree. A complete static view remains available without JavaScript or when reduced motion is enabled.

1. Start with a key and a value

name: Ram

Read this as “the key name has the value Ram.” In this block-style example, the colon and following space separate them.

Use clear spacing:

name: Ram
age: 30

Do not assume name:Ram means the same thing. Without the separating space, it can be interpreted as a single scalar rather than the mapping entry you intended.

2. Recognize a mapping inside another mapping

person:
  name: Ram
  age: 30

The value of person is a mapping containing name and age. Those two keys are siblings: both belong to the same parent mapping.

The paths are:

person.name → Ram
person.age  → 30

A colon with no inline value does not automatically create a dictionary. Here, the indented entries supply a mapping value. A key with no supplied value can instead resolve to null:

person:

The distinction matters when a program expects a collection and receives an empty value.

3. Recognize a list

tools:
  - Docker
  - Kubernetes

tools holds a sequence with two items. Each - starts a separate item in this block-style list.

Order matters for the sequence: Docker is the first item and Kubernetes is the second. An application’s schema determines what each item is allowed to contain.

4. Read a list of mappings

students:
  - name: Ram
    age: 20
  - name: Sita
    age: 22

There are two students, not four. The first dash begins one mapping containing Ram’s name and age. The second dash begins another mapping for Sita.

students[0].name → Ram
students[0].age  → 20
students[1].name → Sita
students[1].age  → 22

These paths use zero-based indexing to explain the structure. They are not additional YAML syntax.

When reading nested lists, find the item marker first, then identify the fields inside that item. This same pattern appears in Kubernetes containers, ports, and volumeMounts.

5. Use indentation to identify the parent

The diagram’s student example uses zero spaces for students, two before the list marker, and four before age. That alignment makes the nesting visible.

Use spaces for indentation, never tabs. Two spaces per level is a useful convention, not a universal YAML requirement. Keep the structure consistent, and follow the style of the project you are editing.

Compare these two valid but different documents:

# age belongs to the person mapping
person:
  name: Ram
  age: 30

# age belongs to the outer mapping
person:
  name: Ram
age: 30

The second version can parse successfully while expressing the wrong data for your application. Valid YAML can still describe the wrong structure.

Values, quotes, comments, and multiline text

Quote values that must remain strings when they resemble other types:

replicas: 3
enabled: true
version: "1.0"
accountCode: "00123"
message: "Ready: waiting for approval"

Parser versions and schemas can differ in implicit typing. Quoting identifiers avoids ambiguity. A # can introduce a comment; quote it when it belongs in the value.

For multiline strings, | preserves line breaks, while > usually folds ordinary line breaks into spaces; blank lines and indentation affect the result. These rules are covered by the YAML scalar specification.

startupScript: |
  echo "Starting"
  echo "Ready"

description: >
  A short description
  written across two lines.

Apply the same method to Kubernetes YAML

A Kubernetes manifest combines the same mappings, sequences, and scalars:

apiVersion: v1
kind: Pod
metadata:
  name: yaml-demo
  labels:
    app: demo
spec:
  containers:
    - name: app
      image: busybox:1.37
      command: ["sh", "-c", "sleep 3600"]

Read it from the outside in:

1. apiVersion and kind identify the API resource.
2. metadata is a mapping; name and labels belong inside it.
3. metadata.labels is another mapping.
4. spec.containers is a sequence with one container mapping.
5. name, image, and command belong to that container.
6. The square-bracket form of command is a sequence written inline.

YAML defines the data structure. The Kubernetes API defines the fields and their meaning. The official Kubernetes object documentation explains how manifests describe objects.

For example, an indented image under metadata might be syntactically valid YAML, but it would not configure a Pod container. Check both syntax and the application’s schema.

Check a file before using it

Start with your editor’s YAML validation, then validate against the intended application’s schema. For a Kubernetes manifest, a server dry run checks the request against a reachable cluster without persisting the object:

kubectl apply --dry-run=server -f pod.yaml

This requires cluster access and appropriate permissions. It does not prove the image can be pulled or the application will run successfully; those are runtime concerns. See Kubernetes dry-run behavior.

Problem	What to check
An expected field is missing	Its indentation may place it under a different parent.
A list has too many items	An extra dash may have started another item.
A number was expected but a string arrived	Check quoting and the application’s type requirements.
YAML parses, but the application rejects it	Validate field names and types against the schema.
A key appears twice in one mapping	Remove the duplicate; parsers may reject it or handle it inconsistently.

Download the examples and diagram

• Download the YAML structure examples.
• Open the original supplied diagram.
• Open the motion diagram with the website’s handwritten fonts.

To practice with larger manifests, continue with Kubernetes Gateway API or StorageClass, PV, and PVC.

Look for the collection first, identify each key or item, then follow its nesting. That reading habit scales from a small example to a full Kubernetes configuration.