JSON to YAML for Kubernetes: Conversion Guide + Gotchas

Kubernetes accepts both JSON and YAML, but the ecosystem expects YAML — kubectl examples, Helm charts, and every GitOps workflow are written in it. Converting a JSON manifest is straightforward, but three specific YAML quirks can silently corrupt a manifest in ways that are hard to debug. This guide covers the conversion process and exactly what to watch for.

Key takeaways

• kubectl accepts both formats. kubectl apply -f manifest.json works. You don't have to convert — but YAML is the convention.
• The Kubernetes YAML string-boolean trap is real. Many parsers treat unquoted no, yes, on, off as booleans — always quote these strings in ConfigMaps and env vars.
• Tabs kill manifests. The YAML spec forbids tabs. One tab character will crash kubectl apply.
• Multiline strings need explicit style. JSON's \n escapes become literal block scalars (|) in YAML for scripts and SQL.
• Secrets in manifests need a client-side converter — one that doesn't upload your manifest to a server.

kubectl JSON vs YAML — do you actually need to convert?

Before converting, worth knowing: kubectl speaks JSON natively. The Kubernetes API is a REST API that uses JSON internally — YAML manifests are parsed to JSON by kubectl before being sent to the API server. So kubectl apply -f deployment.json is completely valid.

When to stay with JSON: your manifest is generated programmatically, you're working in a pipeline that produces JSON, or your team is comfortable with it.

When to convert to YAML: you want comments (YAML supports them, JSON doesn't), you're contributing to a project that uses YAML conventions, or you're working with Helm/Kustomize/ArgoCD which all expect YAML.

A real example: Deployment JSON → YAML

Here is a minimal Deployment manifest in JSON:

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

Pasted into the converter, it becomes:

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

This is valid, ready-to-apply YAML. Now for the gotchas that make this go wrong.

Gotcha 1 — the Kubernetes YAML string-boolean trap

Many YAML parsers historically treated a set of bare words as booleans rather than strings: true, false, yes, no, on, off (and their capitalised variants). Parser behavior varies by implementation and version, but the risk is real enough that the safe rule is simple: always quote string values that look like booleans in Kubernetes YAML.

In practice: if a ConfigMap value is the string "no" in your JSON, the converted YAML must quote it. Without quotes:

# JSON
{ "FEATURE_FLAG": "no" }

# Converted YAML — WRONG (no is parsed as boolean false)
FEATURE_FLAG: no

# Correct YAML — string is preserved
FEATURE_FLAG: "no"

Kubernetes validates the type it receives. A field expecting a string that gets a boolean will fail with a type mismatch error — often a confusing one since the YAML "looks" right. Always check converted YAML for unquoted boolean-looking string values, especially in ConfigMaps and environment variable lists.

Gotcha 2 — Kubernetes YAML multiline strings (scripts, SQL, config)

JSON encodes newlines as \n escape sequences. When a JSON-to-YAML converter sees a string with \n, it has to choose a YAML block scalar style. There are two:

For a shell script in a ConfigMap, you want literal (|):

data:
  startup.sh: |
    #!/bin/bash
    echo "Starting service"
    exec "$@"

If a converter outputs the folded style (>) for a shell script, the newlines collapse into spaces and the script breaks. Check multiline values after conversion.

Gotcha 3 — numeric strings

Like booleans, YAML infers types from unquoted values. A version string like "1.10" in JSON may become 1.1 (a float, with the trailing zero dropped) in YAML if left unquoted. Port numbers, version tags, and anything that looks numeric but should be treated as a string must be quoted:

# Wrong — YAML infers float
version: 1.10

# Correct — explicitly a string
version: "1.10"

Kubernetes YAML tabs vs spaces — indentation rules

The YAML spec forbids tab characters — any tab in a manifest causes a hard parse error when you run kubectl apply. The error message (found character that cannot start any token) is not always obvious. Always use spaces.

Two spaces per indent level is the Kubernetes community standard and what tooling like yamllint, Helm, and most IDE plugins enforce. The JSON-to-YAML converter outputs 2-space indentation automatically.

Converting safely when the manifest contains secrets

Kubernetes Secret manifests contain base64-encoded credentials. Even encoded, pasting a Secret manifest into a server-based converter sends those credentials to a third party. The JSON Dev Tools converter is client-side — your manifest is converted in your browser and never uploaded. For the full explanation of how to verify any online tool is genuinely client-side, see is it safe to paste JSON into an online tool?

Browser-only converter vs alternatives