JSON to YAML: How to Convert JSON for Kubernetes, Docker & GitHub Actions

YAML and JSON represent the same data — key-value pairs, arrays, strings, numbers, booleans, and null. The difference is syntax: JSON uses braces, brackets, and quotes; YAML uses indentation and minimal punctuation. Because YAML supports comments and is easier to read in pull requests, it has become the standard format for infrastructure configuration — Kubernetes, Docker Compose, GitHub Actions, Ansible, and Helm all use YAML exclusively.

JSON to YAML type mapping

Every JSON type maps cleanly to a YAML equivalent:

// JSON
{
  "name": "api-server",
  "replicas": 3,
  "enabled": true,
  "tags": ["web", "prod"],
  "config": { "port": 8080 },
  "notes": null
}

# YAML equivalent
name: api-server
replicas: 3
enabled: true
tags:
  - web
  - prod
config:
  port: 8080
notes: null

JSON objects → YAML mappings (indented key: value pairs). JSON arrays → YAML sequences (list items prefixed with -). JSON strings → YAML scalars (usually unquoted unless the value would be misread). JSON null → YAML null or ~.

When to use YAML over JSON

Configuration files: YAML supports inline comments (#), so you can annotate each setting with its purpose, valid values, or warnings. JSON has no comment syntax.

Kubernetes & Helm: All Kubernetes resource definitions, Helm chart values, and kustomize overlays are YAML. If you have a tool that exports JSON, convert it to YAML before committing to your infrastructure repo.

GitHub Actions & GitLab CI: Workflow files are YAML. You cannot use JSON for pipeline definitions in these systems.

Readability in pull requests: YAML's reduced punctuation makes diffs cleaner and easier to review — fewer lines changed for the same logical edit.

YAML gotchas to watch for after conversion

String coercion: YAML parses unquoted true, false, yes, no, on, off, and numeric-looking values as their native types. If your JSON string value is "true" and you need it to remain a string in YAML, it must be quoted: 'true'.

Indentation sensitivity: YAML uses indentation (not braces) to define structure. A single wrong indent level breaks the document. The converter always outputs standard 2-space indentation for maximum compatibility.

Multi-line strings: Long strings in JSON become a single line in YAML unless you use block scalars (| for literal, > for folded). The converter wraps them in quotes to be safe; adjust manually if you prefer block style.