YAML vs JSON for Config Files

Q: Should I use YAML or JSON for config files?

Use YAML for human-edited config files that benefit from comments and readability (like Docker Compose, Kubernetes). Use JSON when the config is programmatically generated or when the ecosystem requires it (like package.json, tsconfig.json).

Q: Can I use comments in JSON config files?

Standard JSON doesn't support comments, which is a major limitation for config files. Some tools like VS Code's tsconfig.json use JSONC (JSON with Comments), but this isn't universally supported. YAML natively supports comments with #.

Q: Why does npm use JSON instead of YAML?

npm uses package.json because: JavaScript natively parses JSON, node_modules resolution is performance-critical, and the ecosystem was established before YAML became popular for configs. The strict syntax also prevents formatting ambiguity.

Last updated: • 7 min read

Use YAML for config files when you need comments, human readability, and manual editing (Docker, Kubernetes, CI/CD). Use JSON for config when the ecosystem requires it (package.json, tsconfig.json) or when configs are programmatically generated. This guide compares YAML vs JSON for config files with real-world examples. Need to convert? Try our free online converter.

Quick Comparison: YAML vs JSON for Config

Feature	YAML	JSON
Comments	✅ Supported (#)	❌ Not supported
Readability	✅ Excellent	Good
Manual editing	✅ Easy	More error-prone
Programmatic generation	Requires library	✅ Native in most languages
Strictness	Flexible (can cause bugs)	✅ Strict (catches errors)
Multi-line strings	✅ Native support	❌ Escape sequences only

When to Use YAML for Config Files

YAML is the better choice for configuration files when:

1. You Need Comments

Comments are essential for documenting config decisions:

# Database configuration
# Production values - DO NOT change without approval
database:
  host: db.example.com  # Primary host, failover is db2.example.com
  port: 5432
  pool_size: 20  # Increased from 10 for Black Friday traffic
  
# Feature flags
features:
  # Enable new checkout flow (A/B test: 50% of users)
  new_checkout: true
  dark_mode: false  # Planned for Q2 2025

2. Complex Nested Structures

YAML's indentation makes deep nesting readable:

# Kubernetes deployment (much cleaner than JSON equivalent)
apiVersion: apps/v1
kind: Deployment
metadata:
  name: web-app
spec:
  replicas: 3
  selector:
    matchLabels:
      app: web
  template:
    spec:
      containers:
        - name: web
          image: nginx:1.21
          ports:
            - containerPort: 80

3. Multi-line Content

# YAML handles multi-line strings elegantly
script: |
  #!/bin/bash
  echo "Starting deployment..."
  docker-compose up -d
  echo "Done!"
  
description: >
  This is a long description that spans
  multiple lines but will be folded into
  a single paragraph.

When to Use JSON for Config Files

1. Ecosystem Requirements

Some tools only accept JSON:

package.json - npm/Node.js
tsconfig.json - TypeScript
composer.json - PHP
.eslintrc.json - ESLint (also supports YAML)

2. Programmatic Generation

// JSON is native to JavaScript - no library needed
const config = {
  apiKey: process.env.API_KEY,
  endpoints: generateEndpoints(),
  timestamp: new Date().toISOString()
};

fs.writeFileSync('config.json', JSON.stringify(config, null, 2));

3. Strict Validation

JSON's strict syntax catches errors that YAML might miss:

# YAML ambiguity example - these can cause bugs:
country: NO           # Is this "NO" or boolean false?
version: 1.0          # Is this number 1 or string "1.0"?
port: 08080           # Octal number! Equals 4160 in decimal

// JSON is explicit - no ambiguity:
{
  "country": "NO",
  "version": "1.0",
  "port": 8080
}

Real-World Config File Examples

Tool	Format	Why
Docker Compose	YAML	Comments, readability
Kubernetes	YAML (or JSON)	Complex nested configs
GitHub Actions	YAML	Multi-line scripts, comments
npm/package.json	JSON	JavaScript ecosystem
TypeScript/tsconfig	JSON (with comments)	Tooling requirement
VS Code settings	JSON	Native to Electron/JS
Ansible	YAML	Playbook readability
Prettier	JSON or YAML	User preference

Config File Ecosystem Breakdown

YAML-First Tools

Infrastructure: Kubernetes, Docker Compose, Helm
CI/CD: GitHub Actions, GitLab CI, CircleCI, Travis CI
Automation: Ansible, Salt, Puppet (Hiera)
APIs: OpenAPI/Swagger specs

JSON-First Tools

JavaScript: package.json, tsconfig.json, babel.config.json
PHP: composer.json
Editors: VS Code settings, Sublime Text
Cloud: AWS CloudFormation (supports both)

Trend: New DevOps tools almost always choose YAML due to comment support and readability. JSON dominates in the JavaScript ecosystem.

Frequently Asked Questions

Should I use YAML or JSON for config files?

Use YAML for human-edited configs that benefit from comments and readability (Docker, Kubernetes, CI/CD). Use JSON when the ecosystem requires it (package.json) or configs are programmatically generated.

Why does Kubernetes use YAML instead of JSON?

Kubernetes uses YAML because it supports comments for documentation, is more readable for complex nested configurations, and is easier to edit manually. However, Kubernetes API actually accepts both YAML and JSON.

Can I use comments in JSON config files?

Standard JSON doesn't support comments. Some tools use JSONC (JSON with Comments) like VS Code's tsconfig.json, but this isn't universally supported. YAML natively supports comments with #.

Why does npm use JSON instead of YAML?

npm uses package.json because JavaScript natively parses JSON, node_modules resolution is performance-critical, and the ecosystem was established before YAML became popular. Strict syntax also prevents ambiguity.

Need to convert between YAML and JSON?

Use our free online converter for instant conversion.

Open Converter Tool →