YAML Syntax and Structure

Every language has rules. YAML has a set of simple rules called syntax. The syntax of YAML controls how data is written so that computers and humans can read it correctly. Understanding YAML syntax is the first real step toward writing correct YAML files.

YAML syntax is minimal. It avoids symbols like curly braces, angle brackets, and semicolons. Instead, it uses indentation, colons, and dashes to organize data.

The Basic Building Block – Key-Value Pair

The most basic unit in YAML is the key-value pair. A key is a label. A value is the information attached to that label. They are separated by a colon followed by a space.

key: value

The space after the colon is required. Without that space, YAML will not parse the line correctly.

Example

language: YAML
version: 1.2
author: Clark Evans

Each line here is one key-value pair. The key is on the left. The value is on the right. This pattern repeats throughout every YAML file.

Indentation Rules

Indentation in YAML defines hierarchy. Items indented under a key belong to that key. YAML uses spaces only — never tabs. Using tab characters causes a parsing error.

Correct Indentation (Using Spaces)

person:
  name: Alice
  age: 25

Here, name and age are indented under person. This tells YAML that name and age are properties of person.

Wrong Indentation (Using Tabs)

person:
	name: Alice   ← This uses a TAB — this will cause an error

Always use 2 spaces per indentation level. Some developers use 4 spaces. Both work, but consistency within one file is required.

Indentation Diagram

Level 0  →  person:
Level 1  →    name: Alice
Level 1  →    address:
Level 2  →      city: London
Level 2  →      zip: E1 6AN

Each level goes deeper by adding more spaces. All items at the same level must have the same number of leading spaces.

Case Sensitivity

YAML is case-sensitive. The key Name and the key name are treated as two completely different keys. This is important when writing configuration files that other tools will read.

Name: Alice
name: Bob

Both lines exist as separate entries in YAML. No error is thrown, but the values are stored separately.

Document Start and End Markers

A YAML file can contain multiple documents. Each document starts with three dashes --- and optionally ends with three dots ....

---
name: Alice
age: 25
...
---
name: Bob
age: 30
...

The --- marker signals the start of a new YAML document within the same file. This feature is used frequently in Kubernetes, where one file may define multiple resources.

Whitespace Rules

Whitespace is meaningful in YAML. Extra blank lines between items are allowed and ignored by parsers. However, extra spaces within a key or value can change the meaning.

city: New York     ← Value is "New York" (correct)
city:  New York    ← Value may be " New York" with a leading space (be careful)

Always place exactly one space after the colon. Do not add extra spaces before the value unless using multiline blocks intentionally.

Strings Without Quotes

In YAML, plain strings do not need quotation marks.

country: India
greeting: Hello World

Quotes become necessary only when the value contains special characters like colons, quotes, or leading/trailing spaces.

message: "Error: File not found"
note: 'It''s working'

The Colon Rule

A colon followed by a space (: ) always signals a key-value separator. If a string value contains a colon, wrap it in quotes to avoid confusion.

url: "https://estudy247.com"

Without quotes here, YAML would misread the line because the // and later content after the colon could confuse some parsers.

Full Structure Overview Diagram

+------------------------------------------+
|              YAML File Structure          |
+------------------------------------------+
|                                          |
|  --- (Document Start)                    |
|                                          |
|  key: value          ← Simple pair       |
|                                          |
|  parent:                                 |
|    child: value      ← Nested pair       |
|                                          |
|  list:                                   |
|    - item1           ← List items        |
|    - item2                               |
|                                          |
|  ... (Document End)                      |
|                                          |
+------------------------------------------+

Common Syntax Rules at a Glance

Summary

• YAML uses key-value pairs as its basic unit
• A colon followed by a space separates keys and values
• Indentation uses spaces — never tabs
• YAML is case-sensitive
• Use --- to separate multiple documents in one file
• Wrap values in quotes when they contain special characters