YAML to JSON: A Practical Guide

Convert YAML to JSON without losing meaning: understand scalar types, comments, anchors, merge keys, multi-document files, and Kubernetes validation.

YAML is a convenient authoring format; JSON is a predictable interchange format. The conversion between them is not a visual re-wrap. A parser decides whether no is a string, whether 1.10 is a number, and whether an anchor is expanded before a serializer emits JSON. That distinction matters when a converted file becomes a Kubernetes manifest, an API request, or a generated configuration artifact.

The YAML ↔ JSON converter on Control Plane Labs runs in the browser. It uses js-yaml’s YAML 1.2 core schema, accepts multi-document YAML, expands anchors and merge keys, and uses the browser’s JSON parser and serializer for the JSON direction. Your input stays in the page; use the JSON formatter and validator afterward when you need a second syntax check.

What actually changes during conversion

YAML and JSON overlap, but they are not identical document formats. YAML 1.2 was designed to be a strict superset of JSON, according to the YAML 1.2.2 specification. Both formats can express mappings, sequences, strings, numbers, booleans, and null values. YAML adds indentation-based structure, comments, tags, anchors, aliases, and document streams; JSON keeps a smaller grammar built around braces, brackets, quoted names, and six structural characters.

The JSON data-interchange standard defines four primitive types—strings, numbers, booleans, and null—and two structured types: objects and arrays. JSON object names are strings and SHOULD be unique. JSON has no comment syntax, no anchor syntax, and no standard separator for a stream of independent JSON documents.

That leads to a useful rule:

Convert YAML to JSON when you need the data in a JSON-shaped interface. Do not convert it when the YAML file itself—its comments, aliases, formatting, or document boundaries—is the thing you need to preserve.

Scalar types are the first source of surprises

YAML’s plain scalars are resolved according to a schema. The YAML 1.2 core schema recognizes true and false as booleans, decimal values as numbers, and null, Null, NULL, or ~ as null. Words that older YAML 1.1 tooling treated as booleans—yes, no, on, and off—are plain strings under the 1.2 core rules. The core-schema section of the specification is the authority when a parser’s behavior is in doubt.

The same-looking source can therefore produce different JSON depending on the parser and schema:

enabled: no
replicas: 3
release: 1.10
quoted_release: "1.10"
empty_value: null

With a YAML 1.2 core parser, the meaningful JSON shape is:

{
  "enabled": "no",
  "replicas": 3,
  "release": 1.1,
  "quoted_release": "1.10",
  "empty_value": null
}

The value 1.10 is a number, so its trailing zero does not survive numeric serialization. Quote identifiers that look numeric: versions, postal codes, account IDs, image tags, and dates used as labels. This is not only a YAML concern. RFC 8259 notes that implementations commonly use IEEE 754 binary64 numbers and that exact agreement is safest for integers from (-(2^53)+1) through (2^53-1). If a value is an identifier rather than a quantity, make that intent explicit with quotes.

Kubernetes gives these choices real consequences. A manifest may be authored in YAML, but Kubernetes object documentation explains that kubectl converts manifest information to JSON when sending an API request. A value that parses as a number but belongs in a string field can fail validation. A value that silently changes type can also produce a valid-looking object with the wrong meaning.

A quick type-checking table

The table is a data-model check, not a Kubernetes schema check. A generic converter can tell you what the parser saw; it cannot tell you whether a Deployment accepts that value in a particular field. For manifest-specific feedback, run the Kubernetes YAML linter after conversion.

Comments, anchors, and merge keys do not have JSON equivalents

Comments are part of a YAML source file but not part of its data model. A line such as timeout: 45 # chosen for the upstream proxy becomes only "timeout": 45. The YAML specification’s comment rules describe comments as presentation content; RFC 8259 defines JSON whitespace but no comment production. If the rationale matters, move it into documentation or a dedicated field before converting.

Anchors and aliases let YAML represent repeated nodes. An anchor labels a node with &name; an alias refers back to it with *name:

defaults: &defaults
  image: nginx:1.27
  replicas: 2

worker:
  <<: *defaults
  replicas: 5

This is compact for a human-maintained file, but JSON has no pointer or alias syntax. A converter must either reject the construct, invent a convention, or materialize the referenced values. The live tool materializes them, so the JSON result is equivalent to:

{
  "defaults": {
    "image": "nginx:1.27",
    "replicas": 2
  },
  "worker": {
    "image": "nginx:1.27",
    "replicas": 5
  }
}

The defaults mapping is still present because it is a normal YAML key. The alias relationship is gone; worker now owns ordinary JSON members. If you convert the JSON back to YAML, you get valid YAML data, but not the original &defaults shorthand. The YAML specification’s structures section describes anchors and aliases as references to repeated nodes, while the js-yaml project provides the parser and serializer used by the converter.

Do not confuse a merge key with a deep merge. << brings keys from one or more mappings into the current mapping. A child mapping can override a value, as replicas: 5 overrides the inherited replicas: 2. Nested objects are not automatically merged according to a universal JSON rule. Inspect the emitted object at the depth where your configuration depends on inheritance.

Multi-document YAML needs an explicit JSON shape

YAML can contain a stream of documents separated by ---:

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-settings
---
apiVersion: v1
kind: Service
metadata:
  name: app

That is two documents, not one object with two top-level apiVersion keys. JSON’s grammar describes one serialized value at a time; it does not define a standard multi-document stream. A converter therefore needs a policy. The Control Plane Labs tool returns one JSON value for a single YAML document and a JSON array for two or more documents, preserving their order.

This shape is useful for Kubernetes. The Kubernetes workload-management documentation shows related resources in one YAML file separated by ---, and says they are created in the order they appear. If you flatten that file into one object, you lose the resource boundaries. If you emit an array, you preserve the boundaries for a later loop or tool that understands a manifest list.

Do not paste a multi-document YAML stream into a strict JSON parser and expect it to work. Convert it to an array, process each document separately, or keep it as YAML until the consumer that accepts the stream receives it.

Kubernetes validation happens after syntax conversion

Successful parsing answers only: “Can this text be read as YAML or JSON?” It does not answer: “Will this object be accepted by my cluster?”

Kubernetes API concepts describe JSON as the default API encoding and note that Kubernetes also supports YAML media types. The API server knows resource schemas, field types, and version-specific rules. A generic YAML-to-JSON converter knows none of those resource-specific constraints.

The distinction is easiest to see in three layers:

1. Syntax: Is the YAML indentation valid? Is the JSON comma and quote structure valid?
2. Data shape: Did conversion produce an object, array, number, string, boolean, or null where you expected one?
3. Kubernetes schema: Are apiVersion, kind, metadata, and spec valid for this resource? Are fields known and typed correctly?

Kubernetes has server-side field validation for unrecognized and duplicate fields. Its documented modes are strict, warn, and ignore; strict is the default for kubectl and fails on validation errors, while warn reports problems without blocking when server-side validation is available. The kubectl create reference documents the same --validate choices and confirms that both JSON and YAML input are accepted.

Use a generic converter to inspect the representation, then validate against the cluster or resource schema:

# Convert or review the file first, then ask the API server for strict validation.
kubectl apply --dry-run=server --validate=strict -f converted.yaml

# If the consumer really requires JSON, render the validated object as JSON.
kubectl create --dry-run=client -f converted.yaml -o json

The dry-run mode is a safety check, not a substitute for testing admission policies, defaults, or references in a staging cluster. It also cannot repair a semantic mistake that was already encoded in the source. A converter can show that replicas became 5; only the Kubernetes schema and your operational intent can establish whether 5 is correct.

A five-minute conversion review

Use this sequence whenever YAML crosses a JSON boundary:

1. Identify the consumer. Write down whether the next hop is a browser API, CI job, Kubernetes API, or a vendor endpoint. Its schema matters more than the file extension.
2. Mark type-sensitive scalars. Quote versions, IDs, leading-zero values, and strings that resemble booleans or null. Do not rely on every runtime using the same YAML schema.
3. Search for YAML-only features. Look for # comments, & anchors, * aliases, << merge keys, tags, and --- document separators. Decide what each one becomes before conversion.
4. Convert and inspect structure. Check the top-level type, object keys, array lengths, and the values that came from merges. For a multi-document file, confirm that the output is an array with the expected document count.
5. Validate the target. Run a JSON syntax check, then the target tool’s schema validation. For Kubernetes, use server-side dry run with strict field validation where the cluster supports it.
6. Keep the source of truth. Commit the authored YAML if humans need its comments or anchors. Treat generated JSON as an artifact and record the parser, schema, and conversion command used to produce it.

The YAML cheatsheet covers indentation and scalar notation. For Kubernetes-specific serialization choices, Kubernetes KYAML: A Safer YAML Output Format is a useful follow-up.

When not to convert

Keep YAML as YAML when comments explain an operational decision, anchors reduce repeated configuration, or a consumer expects a multi-document stream. Keep a value quoted when its spelling—not only its numeric value—matters. Keep a schema-aware workflow when the target is Kubernetes, a CI configuration language, or an API with strict field types.

Convert when the next system speaks JSON, when you need to inspect the fully materialized result, or when a review requires a canonical data representation. The safe workflow is not “YAML is better” or “JSON is better.” It is: parse with a known schema, understand what cannot survive, inspect the resulting data, and validate it against the system that will use it.

Read next

• Try the YAML ↔ JSON converter.
• Run the Kubernetes YAML linter on a manifest.
• Read Kubernetes KYAML: A Safer YAML Output Format.

Tags: #yaml, #json, #kubernetes, #configuration, #devops