YAML (YAML Ain't Markup Language)

YAML (a recursive acronym for YAML Ain't Markup Language) is a human-readable, data-oriented serialization format designed for configuration management, data persistence, and cross-language object serialization. Emphasizing readability through whitespace indentation over curly braces and brackets, YAML is the dominant standard for DevOps tooling, including Docker Compose, Kubernetes manifests, and GitHub Actions workflows.

Convert, validate, and convert YAML to JSON or TOML seamlessly with our client-side YAML Converter tool and validate CI pipelines with our GitHub Actions YAML Validator.

---

Technical Specifications at a Glance

Specification	Details
Current Specification	YAML 1.2.2 (Standardized by yaml.org)
MIME Media Type	application/yaml, text/yaml
Standard File Extensions	.yaml, .yml
Character Encoding	UTF-8 or UTF-16
Structural Model	Strict indentation (spaces only; tabs are prohibited)
JSON Compatibility	YAML 1.2 is a superset of JSON

---

Core Structural Syntax & Data Types

YAML natively models three foundational data structures: scalars (strings, numbers, booleans), sequences (ordered lists), and mappings (key-value dictionaries).

1. Key-Value Mappings

server:
  host: "127.0.0.1"
  port: 8080
  debug: true

2. Sequences (Lists)

Sequences are denoted by a leading dash followed by a space:

environments:
  - production
  - staging
  - development

3. Multi-Line Strings: Literal (|) vs Folded (>)

• Literal Block Scalar (|): Preserves all newlines and line breaks verbatim.
• Folded Block Scalar (>): Replaces single line breaks with spaces, preserving blank lines as paragraph breaks.

literal_text: |
  Line one will remain
  Line two will stay on its own line
folded_text: >
  This long paragraph will be folded
  into a single continuous line when parsed.

4. Anchors (&) and Aliases (*) for DRY Configs

YAML supports referencing and reusing nodes without repetition:

default_settings: &defaults
  timeout: 30
  retry: 3

production_api:
  <<: *defaults
  endpoint: "https://api.wtool.dev"

---

YAML vs JSON: Key Architectural Differences

Feature	YAML	JSON
Syntax Style	Indentation-based (clean, minimal punctuation)	Delimiter-based ({}, [], quotes, commas)
Comments	Fully supported (# comment)	Not supported in strict RFC 8259
Data Types	Rich (dates, binary, complex keys, sets)	6 primitives (string, number, bool, null, obj, arr)
Parsing Complexity	High (complex grammar, multiple specs)	Low (ultra-fast native C++ parsers)
Primary Domain	DevOps, Kubernetes, Helm, Ansible	Web APIs, REST payloads, browser storage

---

Security Pitfalls & The "Norway Problem"

1. The Norway Problem (Type Coercion)

In YAML 1.1, the string NO (the ISO country code for Norway) was automatically parsed as the boolean false. Similarly, yes, no, on, and off were coerced to booleans unless explicitly wrapped in quotation marks ("NO"). YAML 1.2 aligned boolean rules with JSON (true/false), but developers should always quote country codes and string flags.

2. Arbitrary Code Execution via Unsafe Deserialization

Certain YAML parsers (notably Python's PyYAML via yaml.load()) historically allowed object instantiation tags like !!python/object/apply. Attackers could inject serialized payloads causing remote code execution (RCE).

• Mitigation: Always use safe loaders (e.g., yaml.safe_load() in Python) when parsing untrusted input.

---

Code Examples: Parsing YAML

Modern JavaScript (using yaml library)

import YAML from 'yaml';

const rawYaml = `
app: DevFlow
version: 2.5
services:
  - web
  - worker
`;

// Parse YAML string to JavaScript object
const parsed = YAML.parse(rawYaml);
console.log(parsed.app); // "DevFlow"

// Serialize JS object back to clean YAML
const serialized = YAML.stringify(parsed);

Python 3 (using Safe Loader)

import yaml

config_yaml = """
database:
  host: localhost
  port: 5432
  ssl: true
"""

# Always use safe_load to prevent arbitrary code execution
data = yaml.safe_load(config_yaml)
print(f"Connecting to {data['database']['host']}:{data['database']['port']}")

---

Frequently Asked Questions

What is the difference between .yaml and .yml?

There is no technical difference. Both file extensions represent identical YAML documents. The .yml extension emerged due to historical 8.3 filename constraints in legacy DOS and Windows operating systems. Modern tools recognize both interchangeably, though .yaml is officially recommended.

Can YAML contain comments?

Yes. Comments begin with a hash character (#) and can appear anywhere on a line. Everything following the # is ignored by the parser. This makes YAML widely preferred over JSON for configuration files like Docker Compose and Kubernetes specs.

Why does YAML forbid tab indentation?

YAML strictly mandates space indentation because different text editors, terminals, and operating systems render horizontal tabs (\t) with varying column widths (e.g., 2, 4, or 8 spaces). Using spaces guarantees consistent hierarchical nesting across all developer environments.

Is JSON valid YAML?

Yes. As of the YAML 1.2 specification, JSON is an official subset of YAML. Any syntactically valid JSON payload can be parsed directly by a compliant YAML 1.2 parser without errors.