Skip to content

Practical Introduction to YAML Format

Author: Pengxuan Zhu

This document provides a short, practical introduction to YAML for users who are not familiar with the format. This document assumes no prior knowledge of YAML. It is intended to help you read and write YAML files correctly before using them to configure Jarvis-HEP.

YAML is a human-readable data-serialization format commonly used for configuration files.

What Is YAML?

YAML stands for “YAML Ain’t Markup Language”. It is designed to be:

  • Easy to read and write
  • Indentation-based
  • Friendly to version control systems

YAML is often used as an alternative to JSON or XML for configuration purposes.

Core Syntax Rules

1. Indentation Matters

YAML uses indentation to represent structure. Spaces define hierarchy.

  • Use spaces, not tabs
  • Be consistent (commonly 2 or 4 spaces)

Correct

parent:
  child:
    key: value

Incorrect

parent:
 child:
    key: value

2. Key–Value Pairs

A basic YAML element is a key–value pair:

key: value

Keys are strings. Values can be strings, numbers, booleans, lists, or mappings.

3. Lists

Lists are written using hyphens (-), equivalent to the List object in Python: 

items:
  - apple
  - orange
  - banana

Lists of mappings are also common, equivalent to the Dict object in Python:

users:
  - name: Alice
    role: admin
  - name: Bob
    role: user

4. Strings and Quoting

Most strings do not require quotes.

name: example
path: /tmp/data

Use quotes when: - The string contains special characters - The value could be misinterpreted

expression: "a > b"
version: "1.0"

5. Numbers and Booleans

YAML automatically interprets numbers and booleans.

count: 10
ratio: 0.5
enabled: true
disabled: false

Avoid quoting numbers unless they must be treated as strings.

6. Comments

Comments start with #.

# This is a comment
key: value  # Inline comment

Comments are ignored by the parser.

Common Mistakes

❌ Using Tabs

key:
\tchild: value

Tabs are not allowed. Always use spaces.

❌ Inconsistent Indentation

key:
  child1: value
   child2: value

Even a single extra space changes the structure.

❌ Missing Spaces After Colon

key:value

Correct form:

key: value

❌ Ambiguous Values

yes: no
on: off

These may be interpreted as booleans in YAML 1.1. Use explicit values or quotes if unsure.

Useful Features (Optional)

Anchors and Aliases

YAML supports reusable blocks using anchors (&) and aliases (*).

defaults: &defaults
  timeout: 10
  retries: 3

task1:
  <<: *defaults
  name: task_one

This reduces duplication in large configuration files.

How to Validate YAML

Before using a YAML file, it is strongly recommended to validate it.

Options include: - Online validators (e.g. yamllint) - Command-line tools - Parsing the file in Python using yaml.safe_load

These resources provide deeper explanations and advanced usage examples.

Summary

  • YAML is indentation-based and human-readable
  • Consistent spacing is critical
  • Start simple and validate often
  • When in doubt, prefer clarity over brevity

Now, you can proceed to the Jarvis-HEP tutorial.