YAML vs JSON vs TOML: The Complete Guide to Configuration Format Conversion

If you work in DevOps, you've encountered this scenario: You have a perfect Kubernetes YAML manifest, but the CI/CD tool only accepts JSON. Or you're migrating from Docker Compose (YAML) to Rust-based deployment configs (TOML). Or you need to debug an API response that's nested 12 levels deep and JSON's bracket soup is making your eyes bleed.

Welcome to the world of configuration format conversion—a surprisingly critical skill that can save hours of manual translation and prevent deployment failures from syntax errors.

In this comprehensive guide, I'll explain the differences between YAML, JSON, and TOML, show you real-world conversion scenarios, and reveal the tools and techniques that make format migration painless.

The Three Configuration Formats: What Makes Them Different?

Before we dive into conversion, let's understand what makes each format unique and why they exist.

YAML (YAML Ain't Markup Language)

Born: 2001
Philosophy: Human-readability first
Used By: Kubernetes, Docker Compose, Ansible, GitHub Actions, CircleCI

Strengths:

• Most human-readable—looks like structured text
• Supports comments (crucial for documentation)
• Multi-line strings without escaping
• Less visual noise (no braces, fewer quotes)

Weaknesses:

• Whitespace-sensitive (tabs vs spaces can break everything)
• Complex indentation rules
• Implicit type coercion can cause surprises (Norway problem: NO becomes false)
• Harder to generate programmatically

Perfect For: Configuration files read/edited by humans (Kubernetes manifests, CI/CD pipelines)

JSON (JavaScript Object Notation)

Born: 2001
Philosophy: Universal data interchange
Used By: REST APIs, Web APIs, npm package.json, VS Code settings

Strengths:

• Universal support (every language has a JSON parser)
• Strict syntax (fewer parsing ambiguities)
• Native JavaScript support
• Fast parsing

Weaknesses:

• No comments (huge problem for configuration)
• Verbose syntax (quotes, braces, commas)
• Hard to read when deeply nested
• Trailing commas cause errors

Perfect For: API payloads, programmatic data exchange, configuration consumed by code

TOML (Tom's Obvious, Minimal Language)

Born: 2013
Philosophy: Minimal, unambiguous configuration
Used By: Rust (Cargo.toml), Python (pyproject.toml), Hugo, Netlify

Strengths:

• Explicit typing (no implicit conversions)
• Supports comments
• Easier to parse than YAML
• Minimal syntax

Weaknesses:

• Less common (smaller ecosystem)
• Verbose for deeply nested data
• Limited nesting compared to JSON/YAML

Perfect For: Package manager configs, build tool settings, static site generators

Real-World Conversion Scenarios

Let's look at actual situations where format conversion saves the day.

Scenario 1: Kubernetes YAML to JSON for kubectl

While kubectl accepts YAML, some custom operators or CI/CD tools require JSON. Here's a Kubernetes Deployment manifest in both formats:

YAML (Original):

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  labels:
    app: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.21
        ports:
        - containerPort: 80

JSON (Converted):

{
  "apiVersion": "apps/v1",
  "kind": "Deployment",
  "metadata": {
    "name": "nginx-deployment",
    "labels": {
      "app": "nginx"
    }
  },
  "spec": {
    "replicas": 3,
    "selector": {
      "matchLabels": {
        "app": "nginx"
      }
    },
    "template": {
      "metadata": {
        "labels": {
          "app": "nginx"
        }
      },
      "spec": {
        "containers": [
          {
            "name": "nginx",
            "image": "nginx:1.21",
            "ports": [
              {
                "containerPort": 80
              }
            ]
          }
        ]
      }
    }
  }
}

Notice how JSON requires explicit type preservation—the replicas: 3 integer must remain "replicas": 3 (no quotes around the number) or Kubernetes will reject it.

Scenario 2: Docker Compose to AWS ECS Task Definition

Docker Compose uses YAML, but AWS ECS task definitions use JSON. You need to convert and adapt:

Docker Compose YAML:

version: '3.8'
services:
  web:
    image: nginx:alpine
    ports:
      - "80:80"
    environment:
      - ENV=production
    volumes:
      - ./html:/usr/share/nginx/html

ECS Task Definition JSON (after conversion + adaptation):

{
  "family": "web-service",
  "containerDefinitions": [
    {
      "name": "web",
      "image": "nginx:alpine",
      "portMappings": [
        {
          "containerPort": 80,
          "protocol": "tcp"
        }
      ],
      "environment": [
        {
          "name": "ENV",
          "value": "production"
        }
      ]
    }
  ]
}

Scenario 3: GitHub Actions YAML to GitLab CI JSON

Migrating CI/CD platforms? You'll need to convert workflow syntax:

GitHub Actions (YAML):

name: CI
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run tests
        run: npm test

GitLab CI (YAML, but different structure):

build:
  stage: build
  script:
    - npm test
  only:
    - main

This requires not just format conversion but structure translation—understanding the semantic differences between platforms.

Conversion Pitfalls and How to Avoid Them

Pitfall #1: Type Coercion Mismatches

YAML's implicit typing can cause issues. The famous "Norway problem":

# YAML
countries:
  - NO   # Interpreted as boolean false!
  - SE   # Interpreted as string "SE"
  - DK   # Interpreted as string "DK"

When converted to JSON, NO becomes false instead of "NO".

Solution: Quote all string values in YAML: countries: ["NO", "SE", "DK"]

Pitfall #2: Lost Comments

JSON doesn't support comments. When converting YAML → JSON, all documentation comments disappear.

Solution: Document your JSON configs in separate files or use description fields within the JSON structure itself.

Pitfall #3: Whitespace Sensitivity

YAML breaks if you mix tabs and spaces. When generating YAML programmatically, always use spaces.

Solution: Use linters like yamllint to catch indentation errors before deployment.

Pitfall #4: Anchor References Don't Convert

YAML supports anchors and aliases for DRY configs:

defaults: &defaults
  timeout: 30
  retries: 3

service1:
  <<: *defaults
  name: auth

JSON has no equivalent. Conversion tools will inline the values or fail.

Solution: Resolve anchors before conversion or use a preprocessor.

Automated Conversion Tools and Best Practices

Command-Line Tools

For YAML ↔ JSON:

# Using yq (YAML processor)
yq eval -o=json input.yaml > output.json
yq eval -P input.json > output.yaml

# Using jq (JSON processor)
cat input.json | jq . > pretty.json

For TOML ↔ JSON:

# Using remarshal (Python)
remarshal -if toml -of json Cargo.toml > package.json
remarshal -if json -of toml package.json > Cargo.toml

Programming Language Libraries

Python:

import yaml
import json

# YAML to JSON
with open('config.yaml') as f:
    data = yaml.safe_load(f)
with open('config.json', 'w') as f:
    json.dump(data, f, indent=2)

JavaScript/Node.js:

const yaml = require('js-yaml');
const fs = require('fs');

// JSON to YAML
const jsonData = require('./config.json');
const yamlStr = yaml.dump(jsonData);
fs.writeFileSync('config.yaml', yamlStr);

Online Tools

• GetDevUtils YAML Lab: Convert YAML/JSON/TOML with AI validation and error detection
• JSON to YAML: Simple web-based converters (but your data goes to their servers!)
• YAML Lint: Validate YAML syntax before conversion

Advanced: Semantic Structure Preservation

Not all conversions are simple syntax translation. You need semantic preservation—maintaining the meaning and structure of your data.

For example, Kubernetes expects certain fields to be integers (like replicas), not strings. A naive converter might turn:

replicas: 3   # YAML (integer)

Into:

"replicas": "3"   # JSON (string) - WRONG!

Good converters understand data types and preserve them correctly:

"replicas": 3   # JSON (integer) - CORRECT!

CI/CD Integration: Automated Format Conversion

For platform migrations, automate conversion in your CI/CD pipeline:

GitHub Actions Example:

name: Convert Configs
on: [push]
jobs:
  convert:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install yq
        run: |
          sudo wget -O /usr/local/bin/yq https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64
          sudo chmod +x /usr/local/bin/yq
      - name: Convert YAML to JSON
        run: |
          for file in configs/*.yaml; do
            yq eval -o=json "$file" > "${file%.yaml}.json"
          done
      - name: Commit converted files
        run: |
          git add configs/*.json
          git commit -m "Auto-convert YAML to JSON"
          git push

Conclusion: Pick the Right Format for the Job

There's no "best" configuration format—only the best format for your specific use case:

• Use YAML when: Humans need to read/edit configs (Kubernetes, Docker Compose, CI/CD pipelines)
• Use JSON when: Machines need to parse data (API payloads, programmatic configs, web APIs)
• Use TOML when: You need explicit typing and minimal syntax (package managers, build tools)

And when you need to convert between them? Use tools that preserve semantic structure, validate syntax, and keep your data secure with local processing.

← Back to Blog | GetDevUtils Home