YAML 1.2 Released — Full JSON Compatibility

The Problem with YAML 1.1 and JSON

Before YAML 1.2, YAML and JSON were incompatible at the edges despite appearing similar. Several valid JSON constructs were invalid or interpreted differently in YAML 1.1:

• Boolean values: YAML 1.1 treated a large set of unquoted strings as booleans: yes, no, on, off, true, false, and their capitalised variants. JSON only recognises true and false. A YAML 1.1 parser would silently convert "yes" (unquoted) to true in a JSON document, changing the meaning.
• Number parsing: YAML 1.1 supported octal literals in the form 0777 (a leading zero). JSON has no octal syntax. The value 0777 in JSON should be the integer 777; in YAML 1.1 it was the integer 511.
• Special float values: YAML 1.1 treated .inf, -.inf, and .nan as floating-point values. JSON does not permit infinity or NaN.

What Changed in YAML 1.2

YAML 1.2, published in July 2009, made YAML a proper superset of JSON. Every valid JSON document is now a valid YAML 1.2 document with the same interpretation. The key changes:

• Boolean values: YAML 1.2's Core Schema recognises only true and false as booleans (lowercase). The yes, no, on, off forms are removed from the implicit type resolution rules.
• Octal syntax: The leading-zero octal format is removed. Octals now require an explicit 0o prefix (e.g., 0o777), matching ECMAScript's syntax.
• JSON-compatible scalars: The Core Schema's implicit type resolution aligns with JSON's value types. Any value that JSON would parse as a string, number, boolean, or null is parsed identically by YAML 1.2.

Preserved YAML Features

YAML 1.2 kept all the features that make YAML more human-friendly than JSON:

• Comments: Lines starting with # remain valid
• Multi-line strings: Block scalars (| and >) are preserved
• Anchors and aliases: &anchor and *alias for reusing values
• Bare keys: Object keys without quotes in block mappings
• Multiple documents: --- document separators

JSON documents use none of these features, so adding support for them in YAML without breaking JSON compatibility is straightforward.

Adoption and Parser Support

YAML 1.2 adoption among parser libraries has been gradual. Many widely-used libraries (PyYAML, older versions of SnakeYAML) continued to implement YAML 1.1 for years after 1.2 was published, in part because the breaking changes to boolean handling would affect existing YAML files that relied on yes/no syntax.

By the early 2020s, most major YAML libraries had either switched to YAML 1.2 defaults or made it configurable. The YAML 1.2.2 specification (2021) and the activation of the public GitHub repository (2023) have accelerated this process by providing a clear authoritative document and a community forum for implementation questions.

If you need to convert YAML to JSON or vice versa in practice, see How to Format JSON — it covers YAML-to-JSON conversion in Python and in the browser.