# YAML for JSON Developers: A Practical Introduction

2026-04-15

https://toolblip.com/blog/yaml-for-json-developers

# YAML for JSON Developers: A Practical Introduction

If you work with APIs or configuration files, you've likely encountered YAML. Docker Compose, Kubernetes, GitHub Actions, Ansible - all use YAML. This guide gets you productive fast.

## YAML vs JSON at a Glance

| Feature | JSON | YAML |
|---------|------|------|
| Comments | ❌ | ✅ |
| Trailing commas | ❌ | ✅ |
| Quotes for strings | Required for special chars | Usually optional |
| Indentation | Any whitespace | **Spaces only** (no tabs!) |
| Type inference | Limited | Automatic |

## Basic Syntax

### Objects
```yaml
# JSON equivalent: { "name": "Toolblip", "version": "1.0" }
name: Toolblip
version: "1.0"
```

### Arrays / Lists
```yaml
# JSON: { "tools": ["JSON Formatter", "Base64", "Cron"] }
tools:
  - JSON Formatter
  - Base64
  - Cron
```

### Nested Structures
```yaml
server:
  host: api.toolblip.com
  port: 443
  ssl: true
  tags:
    - production
    - api
```

## The Pitfalls

### 1. Tabs Are Forbidden

YAML parsers expect spaces only. If your editor uses tabs, you're going to have a bad time.

```yaml
# ❌ Tab indentation will fail
name: Toolblip
	version: 1.0

# ✅ Spaces only
name: Toolblip
version: 1.0
```

### 2. Type Coercion Can Bite You

YAML auto-converts values to types - sometimes unexpectedly.

```yaml
# ⚠️ "yes" becomes boolean true
answer: yes         # → true (boolean!)

# ✅ Use quotes for strings
answer: "yes"       # → "yes" (string)
```

### 3. The `?` Question Mark

Used when you need to specify both day-of-month and day-of-week without conflict (like cron expressions).

## Multi-Document Files

One YAML file can contain multiple documents separated by `---`:

```yaml
---
app: frontend
env: production
---
app: backend
env: staging
```

## When to Use YAML vs JSON

**Use YAML for:**
- Configuration files (Docker, Kubernetes, GitHub Actions)
- Human-edited files where comments add value
- Files that benefit from cleaner, more readable syntax

**Use JSON for:**
- API request/response bodies
- Data exchange between systems
- Machine-readable files where every byte matters

## Convert Between YAML and JSON

👉 **[YAML ↔ JSON Converter →](/tools/json-yaml-converter)**

Paste YAML → get JSON, or paste JSON → get YAML. Also validates syntax before converting.

## Python and JavaScript

```python
# Python
import yaml

with open('config.yaml') as f:
    config = yaml.safe_load(f)  # safe_load prevents code execution

# Always use safe_load with untrusted input
yaml.safe_load(user_input)
```

```javascript
// JavaScript
import yaml from 'js-yaml';

const config = yaml.load(fs.readFileSync('config.yaml', 'utf8'));
```

## Key Takeaways

1. **Spaces only** - no tabs, ever
2. **Quotes protect strings** from accidental type conversion
3. **Comments are free** - use them in configuration files
4. **Automatic types** - `yes`/`no` become booleans, `42` becomes a number
5. **`---` separates documents** in multi-document files

YAML is a superpower for configuration. Once you know the gotchas, it's much more readable than JSON for human-edited files.