YAML (YAML Ain't Markup Language) supports multiple documents within a single file. This feature allows you to store related but separate data structures in one YAML file, enhancing organization and flexibility in data representation.

Understanding YAML Multiple Documents

In YAML, you can define multiple documents in a single file using document separators. Each document is treated as an independent unit, making it easier to manage complex configurations or datasets.

Document Separators

YAML uses three dashes (---) to indicate the start of a new document. The end of a document can be marked with three dots (...), though this is optional for the last document in the file.

Syntax and Usage

Here's a basic example of how multiple documents look in a YAML file:

---
# First document
name: Document 1
value: 42
---
# Second document
name: Document 2
items:
  - apple
  - banana
---
# Third document
name: Document 3
nested:
  key: value
...

Each document can have its own structure and content, independent of the others. This flexibility is particularly useful when working with YAML Complex Structures.

Common Use Cases

YAML multiple documents are often used in scenarios such as:

Configuration files for different environments (development, staging, production)
Storing multiple related but separate data sets
Defining multiple resources in infrastructure-as-code tools

For instance, in YAML in Kubernetes, multiple documents are frequently used to define different resources in a single file.

Practical Example

Let's look at a more practical example using multiple documents for different environment configurations:

---
# Development environment
environment: development
database:
  host: localhost
  port: 5432
debug: true
---
# Production environment
environment: production
database:
  host: db.example.com
  port: 5432
debug: false
...

This structure allows you to keep related configurations together while maintaining clear separation between different environments.

Parsing Multiple Documents

When working with multiple YAML documents, it's important to use a parser that supports this feature. Most YAML libraries in various programming languages provide methods to iterate through multiple documents in a file.

For example, in YAML in Python, you can use the yaml.safe_load_all() function to parse multiple documents:

import yaml

with open('multiple_docs.yaml', 'r') as file:
    documents = yaml.safe_load_all(file)
    for doc in documents:
        print(doc)

Best Practices

Use clear and consistent document separators
Consider adding comments before each document to describe its purpose
Ensure each document is self-contained and doesn't rely on data from other documents in the file
Be mindful of file size when using multiple documents; very large files can become difficult to manage

Conclusion

YAML multiple documents provide a powerful way to organize related but separate data structures within a single file. By understanding and utilizing this feature, you can create more flexible and maintainable YAML configurations for various applications and systems.

Remember to always validate your YAML files, especially when working with multiple documents, to ensure correct syntax and structure. You can use YAML Online Validators for quick checks during development.