YAML vs JSON vs TOML: Configuration File Formats Compared

Configuration files are the backbone of modern software. Docker uses YAML, Node.js uses JSON, Rust uses TOML. Choosing the right format affects developer experience, tooling compatibility, and even security. This guide compares the three dominant configuration formats with identical data examples.

The Same Data in Three Formats

JSON:

{
  "name": "my-app",
  "version": "1.0.0",
  "database": {
    "host": "localhost",
    "port": 5432,
    "ssl": true
  },
  "features": ["auth", "logging", "cache"]
}

YAML:

name: my-app
version: "1.0.0"
database:
  host: localhost
  port: 5432
  ssl: true
features:
  - auth
  - logging
  - cache

TOML:

name = "my-app"
version = "1.0.0"
features = ["auth", "logging", "cache"]

[database]
host = "localhost"
port = 5432
ssl = true

Feature Comparison

Ecosystem Usage

• JSON: package.json, tsconfig.json, .eslintrc.json, AWS CloudFormation, Terraform (also HCL)
• YAML: Docker Compose, Kubernetes manifests, GitHub Actions, Ansible, Helm charts, OpenAPI specs
• TOML: Cargo.toml (Rust), pyproject.toml (Python), Hugo config, Deno config, Netlify config

Security Considerations

YAML has the most security pitfalls:

• Billion laughs attack: YAML anchors/aliases can create exponentially expanding data (similar to XML entity expansion). Always set recursion limits.
• Arbitrary code execution: Some YAML parsers (notably Python's yaml.load()) can execute arbitrary code through special tags. Always use yaml.safe_load().
• Type coercion surprises: YAML auto-interprets yes/no as booleans and 12:30 as sexagesimal numbers. Quote strings when in doubt.

JSON and TOML are inherently safer because they lack features that enable these attacks.

Recommendations

• Use JSON for programmatic configuration that is generated or consumed by code, and for web/JavaScript ecosystems.
• Use YAML for human-authored configuration in DevOps and infrastructure (Docker, K8s, CI/CD). Be mindful of security.
• Use TOML for simple, flat-ish configuration where comments matter and you want strict, unambiguous parsing.

Convert between formats with the YAML to JSON and JSON to YAML converters on WizlyTools.