Convert YAML to JSON

Indentation is the syntax

In JSON the braces tell you where a structure ends. In YAML the left margin does, and that single decision causes most of the errors people hit. Three rules worth knowing before you debug anything:

• Tabs are illegal as indentation. Not discouraged — forbidden by the specification. An editor that inserts a tab produces a file no conforming parser will read, and the error message rarely says so. This one does.
• A sequence under a key may sit at the key's own indentation. Both of these mean the same thing, which surprises people coming from other formats: a steps: line followed by dashes indented two spaces, and the same line followed by dashes at the same margin as steps.
• How much you indent is up to you, but it must be consistent within a block. Two spaces is the convention. Mixing two and four inside one mapping is where files silently change shape.

YAML 1.2 is a strict superset of JSON, so any valid JSON document is also valid YAML. That is occasionally useful when you need to paste a fragment into a config file and cannot be bothered with the indentation.

Scalars that are not what they look like

Unquoted values are resolved by pattern, and the patterns have famous casualties. The best-known is the Norway problem: in YAML 1.1, no is a boolean, so a country list written as - no gives you false where you expected "NO". The same applies to y, yes, on and off.

It applies to keys too, which is the version most people meet first: under 1.1 rules the on: line at the top of a GitHub Actions workflow is the boolean true, not the word "on". Turn the checkbox above on and watch it happen to the sample.

YAML 1.2 removed all of that. Only true and false are booleans, which is the default here. Many real parsers — PyYAML's default loader among them — still behave like 1.1, so the checkbox lets you see the file the way they will. If a value could be mistaken for something else, quote it. Quoting is the fix for every ambiguity in this section.

Numbers have their own traps. version: 1.0 is the float 1, so it reprints as 1 and no longer matches the string "1.0". 1.2.3 has two dots and stays a string. Leading zeros are kept in YAML but the value is still a number, and in YAML 1.1 a value like 08:30 was read as base-60 arithmetic. An empty value, ~ and null all mean null. None of this is guessable, which is why configuration files that matter tend to quote everything.

Block scalars

The two most useful pieces of YAML that JSON has no answer for. | keeps the line breaks exactly as written, which is what you want for a shell script or an embedded certificate. > folds the lines into a paragraph, joining them with spaces, which is what you want for a long description. Both strip the common indentation, so the text does not carry your file's layout into the value.

The trailing character controls what happens to the final newline. Plain | keeps exactly one, |- keeps none, and |+ keeps every blank line at the end. That distinction matters more than it sounds: a key with an accidental trailing newline is a common cause of a signature or a token failing to validate.

What this converter refuses

It covers block mappings, block sequences, flow collections, comments, quoting, block scalars, folded plain scalars and the core scalar types. It stops at the features that cannot be represented honestly:

• Anchors and aliases (&base and *base) and merge keys (<<). These duplicate or share structure, and expanding them changes the meaning of the document in ways you should decide on, not a web page.
• Tags such as !!str or custom application tags. JSON has no type annotations to put them in.
• Multiple documents. Only the first is converted, and you get told how many there were.
• Complex keys (? key syntax) and non-string keys. JSON object names are strings, so 1: one becomes "1": "one".

Each of those raises an error with a line number instead of producing a plausible-looking result. That is the deliberate trade: a converter that quietly drops an anchor is worse than one that stops.

Two more things to be aware of. Numbers go through JavaScript, so an integer above 9,007,199,254,740,991 loses precision on the way through — quote long IDs. And .inf and .nan are left as the strings they were written as, because JSON has no way to spell either one.

One thing you get for free: this parser only ever produces plain data. Some YAML libraries in other languages can construct arbitrary objects from a tag in the file, which is why loading untrusted YAML with the wrong function has been a real source of remote code execution. Nothing here can do anything but build strings, numbers, arrays and objects.

Last updated September 19, 2026