JSON zu YAML

Converting JSON to YAML: From Data Interchange to Human-Readable Configuration

JSON (JavaScript Object Notation) is the dominant data interchange format on the web — practically every REST API speaks JSON, every npm package uses package.json, and most NoSQL databases store documents as JSON. However, when it comes to configuration files for infrastructure tools like Kubernetes, Docker Compose, Ansible, and GitHub Actions, YAML has become the standard. This tool converts valid JSON into clean, idiomatic YAML 1.2 output, preserving data types, nested structures, and array ordering while producing human-readable configuration ready for deployment workflows.

Why Migrate from JSON to YAML for Configuration

JSON was designed as a lightweight data interchange format optimized for machine parsing. Its strict syntax — mandatory double quotes around keys, no trailing commas, no comments — makes it predictable for APIs but cumbersome for humans editing configuration files by hand. YAML addresses these limitations directly:

• Comments: JSON has no comment syntax whatsoever. YAML supports inline comments with #, enabling teams to document configuration decisions directly in the file.
• Multi-line strings: JSON requires \n escape sequences for line breaks. YAML provides block scalars (| for literal, > for folded) that preserve formatting naturally.
• Readability: JSON's brace-heavy syntax creates visual noise in deeply nested configs. YAML's indentation-based structure reduces clutter and makes hierarchy immediately visible.
• No quoting requirement: YAML does not require quotes around most string keys and values, reducing character count and improving scannability.
• Anchors and aliases: YAML supports &anchor and *alias syntax for reusing repeated configuration blocks — impossible in plain JSON.

These differences explain why Kubernetes manifests, Docker Compose files, CI/CD pipelines, and Helm charts all adopted YAML over JSON despite JSON being technically valid YAML (every JSON document is a valid YAML 1.2 document). The conversion from JSON to YAML is about optimizing for the human reader and the DevOps workflow.

JSON Conventions and Limitations in the Configuration Context

JSON's design, governed by ECMA-404 and RFC 8259, enforces strict syntactic rules that become pain points in configuration scenarios:

• All keys must be double-quoted strings: Writing "replicas" instead of just replicas adds visual noise across hundreds of configuration lines.
• No trailing commas: Adding or removing the last item in an array or object requires editing the preceding line — a common source of merge conflicts in version control.
• Single number type: JSON has only one numeric type (IEEE 754 double). YAML 1.2 distinguishes integers from floats and supports octal, hexadecimal, and infinity/NaN values.
• No date/time type: Dates in JSON are just strings. YAML 1.2 natively recognizes ISO 8601 timestamps as a distinct type.
• No null distinction: JSON uses null exclusively. YAML accepts null, ~, and empty values as equivalent representations.

When converting JSON to YAML, these limitations become opportunities. A JSON value like "2024-01-15T10:30:00Z" can remain as a YAML timestamp without quotes. A numeric port value 8080 maps directly to a YAML integer. The converter preserves semantic meaning while removing syntactic overhead.

Data Type Mapping: JSON to YAML 1.2

YAML 1.2 (defined by the YAML 1.2.2 specification) uses a tag system to represent data types. When converting from JSON, the mapping is straightforward because JSON is a subset of YAML 1.2's JSON Schema:

• string → YAML scalar (unquoted when safe, quoted when containing special characters)
• number (integer) → YAML !!int (e.g., 42)
• number (float) → YAML !!float (e.g., 3.14)
• boolean → YAML !!bool (true / false)
• null → YAML !!null (rendered as null or ~)
• array → YAML sequence (block style with - prefix per item)
• object → YAML mapping (block style with key: value pairs)

The conversion is lossless — converting YAML back to JSON produces the identical data structure. However, YAML's additional expressiveness (comments, anchors, multi-line strings) means that YAML→JSON conversion may lose metadata that JSON cannot represent.

Real-World Use Case: Kubernetes and Docker Compose

The most common reason developers convert JSON to YAML is generating Kubernetes manifests or Docker Compose files from JSON-based tooling. Many infrastructure generators, Terraform outputs, and API responses produce JSON, but deployment targets expect YAML:

• Kubernetes: kubectl accepts both formats, but the community convention is YAML. Helm charts, Kustomize overlays, and ArgoCD manifests are all YAML-first.
• Docker Compose: The docker-compose.yml format requires YAML. Programmatic generation often starts as JSON objects that need conversion.
• GitHub Actions: Workflow files (.github/workflows/*.yml) must be YAML. Automated workflow generators typically produce JSON internally.
• Ansible: Playbooks and inventory files are YAML. Dynamic inventory scripts output JSON that Ansible consumes — but static inventory is YAML.

This tool handles nested structures common in these formats: deeply nested pod specs, environment variable arrays, volume mount configurations, and multi-container deployments all convert cleanly from their JSON representation to readable YAML output.

Code Examples

Converting a Kubernetes Deployment from JSON to YAML

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

Output:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web-app
  labels:
    app: web
    tier: frontend
spec:
  replicas: 3
  selector:
    matchLabels:
      app: web
  template:
    spec:
      containers:
        - name: nginx
          image: "nginx:1.25"
          ports:
            - containerPort: 80

Standards & Specifications

• YAML 1.2.2 Specification — The current YAML specification defining syntax, data types, and the JSON Schema that ensures JSON↔YAML compatibility
• RFC 8259 (JSON) — The JSON data interchange format specification — defines the input format this tool accepts
• ECMA-404 — The ECMA standard for JSON syntax — the formal grammar governing valid JSON input