YAML Documents

A single YAML file can hold more than one document. A document is a complete block of data with its own structure. Think of a binder with several sheets of paper: the binder is the file, and each sheet is a document. This feature lets related settings live together in one place.

The Document Start Marker

Three dashes on a line begin a document. The marker is optional for the first document and required to separate later ones.

---
name: Report
pages: 12

Many tools add the marker automatically. Writing it yourself makes the boundary obvious to human readers.

The Document End Marker

Three dots on a line close a document. Most files skip this marker because the next three-dash line or the end of the file closes the document anyway. Streaming systems use the dots to signal that no more data follows in the current document.

---
name: Report
pages: 12
...

Multiple Documents in One File

Place three dashes between documents to split them:

---
kind: Fruit
name: Mango
---
kind: Fruit
name: Guava
---
kind: Vegetable
name: Carrot

The file contains three separate documents. Each one starts fresh, so keys in one document never collide with keys in another.

Picturing the Layout

+------------------ fruits.yaml ------------------+
|  ---                                             |
|  [ Document 1 ]  name: Mango                     |
|  ---                                             |
|  [ Document 2 ]  name: Guava                     |
|  ---                                             |
|  [ Document 3 ]  name: Carrot                    |
+--------------------------------------------------+

A dashed line acts like a divider tab in the binder. A parser that supports multiple documents returns a list with one entry per sheet.

Directives

Directives sit above the start marker and begin with a percent sign. The most common one declares the YAML version:

%YAML 1.2
---
name: Report

Few files use directives. Tools that read YAML often ignore them, and the default version suits nearly every project.

Reading Many Documents with Python

The normal loading function expects one document and raises an error when it meets several. Use the multi-document function instead:

import yaml

with open("fruits.yaml") as f:
    for doc in yaml.safe_load_all(f):
        print(doc)

The loop prints one dictionary per document. The same pattern works for any file that stacks documents.

Where Multiple Documents Appear

Area	Reason for several documents
Kubernetes	One file describes a deployment, a service, and a storage claim
Log streams	Each log record forms its own document
Test data	Every case sits in a separate document
Configuration bundles	One file ships settings for several components

Comments and Documents

A comment placed before the first marker belongs to the file header. Comments after a marker belong to the document that follows. Use header comments to describe the purpose of the whole file.

# Sample produce list
---
name: Mango
---
name: Guava

Common Mistakes

• Writing four dashes instead of three. The parser reads the line as plain text.
• Indenting the marker. Place the three dashes at the very start of the line.
• Calling the single-document loader on a multi-document file.
• Adding text on the marker line without a space, such as ---name.

Why Splitting Helps

Related data stays together when it travels as one file. A team can send a single attachment, store one file in version control, and apply it with one command. Reviewers scan the whole bundle in one scroll and notice missing pieces quickly.

Documents also keep responsibilities clear. A deployment document describes how an application runs, while a service document describes how traffic reaches it. Readers jump to the relevant sheet without wading through unrelated settings.

Keep each document small and focused. A file with a dozen unrelated documents becomes hard to read, and splitting it into separate files often serves the project better.