Migrate to RunxBuild and earn up to $50 in hosting credit on your first deposit.

Calculate your savings
unxBuild
Log in Get Started
Back to Blog Tutorial

JSON to YAML: Tools, When to Convert, and the Gotchas

Sean

Platform Writer

Jul 05, 2026
5 min read

JSON to YAML conversion: tools include yq (the YAML/JSON processor), Python’s pyyaml, online converters. YAML is preferred for config files (Kubernetes manifests, GitHub Actions, Docker Compose) because it’s more human-readable. The team that converts for config has cleaner diffs and easier review.

JSON to YAML: Tools, When to Convert, and the Gotchas

Table of contents

Why convert

  • Kubernetes manifests: YAML is standard.
  • GitHub Actions: YAML workflow files.
  • Docker Compose: YAML compose.yaml.
  • Ansible: YAML playbooks.
  • GitLab CI: YAML .gitlab-ci.yml.

The team that uses YAML has config in the human-readable format.

yq - the standard tool

# Install
sudo apt install yq    # or brew install yq on macOS

# Convert JSON to YAML
yq -P input.json > output.yaml
# Or read from stdin
echo '{"key": "value"}' | yq -P .

The team that uses yq (the modern version, written in Go) has the right tool. The Python-based yq (mikefarah’s) is also good.

Python conversion

import yaml, json

with open('input.json') as f:
    data = json.load(f)

with open('output.yaml', 'w') as f:
    yaml.dump(data, f, default_flow_style=False)

The team that uses Python has scripting for batch conversion.

Online tools

The team that uses online tools for one-off conversions has quick results. The team that uses yq for automation has scriptable.

Common YAML gotchas

  1. Indentation matters - spaces only, no tabs.
  2. Strings vs numbers: port: 80 is int, port: "80" is string. YAML 1.1 vs 1.2 differ on this.
  3. Multi-line strings: use | (literal) or > (folded) for multi-line.
  4. No comments in JSON but YAML supports # comments.
  5. Anchors and aliases: &anchor and *alias for DRY YAML.

YAML for K8s manifests

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  replicas: 3
  selector:
    matchLabels:
      app: myapp
  template:
    metadata:
      labels:
        app: myapp
    spec:
      containers:
        - name: myapp
          image: myapp:1.0
          ports:
            - containerPort: 8080

The team that uses YAML for K8s has the standard format.

JSON vs YAML tradeoffs

  • YAML: more readable, supports comments, but indentation matters.
  • JSON: less readable, but unambiguous (no indentation issues).

The team that uses YAML for human-edited config and JSON for machine-to-machine has the right split.

FAQ

Is YAML a superset of JSON?

Yes - all valid JSON is valid YAML. The team that uses YAML can embed JSON syntax for complex values.

Which yq should I install?

Two projects: mikefarah/yq (Go-based, yq from snap or GitHub releases) and kislyuk/yq (Python wrapper around jq). Mikefarah’s is the modern standard.

Can I convert YAML back to JSON?

Yes - yq -o=json input.yaml > output.json. The team that needs round-trip conversion uses yq.

What’s the difference between > and | in YAML?

> folds newlines to spaces (paragraph mode). | preserves newlines (literal block). The team that uses | for code blocks and > for prose has the right text.

Is YAML slower to parse than JSON?

Yes - YAML parsing is more complex. The team that uses YAML for config (parsed once at startup) has no performance issue. The team that uses YAML in tight loops has wrong tool.

If you are sizing the infrastructure for the kind of project this post covers, the RunxBuild hosting calculator is the right place to model the line items. The compute, the memory, the storage, the bandwidth, the database - each one is a separate number, and the team’s mental model for the platform is the sum of those numbers. The RunxBuild dashboard is where the team sees the actual usage in one place.

Useful related references:

#json#yaml#conversion#tools#dev-infra