YAML 1.1 vs 1.2: The Values That Change Type

Version and schema are related, not interchangeable

A YAML document is not just indentation plus key-value pairs. The YAML 1.2.2 specification describes a presentation stream, a serialization tree, a representation graph, and construction into native application values. Syntax determines whether the character stream can be parsed. A schema supplies tags and rules for resolving plain, untagged scalars such as true, 42, or 2026-08-04.

YAML 1.2 recommends the core schema as the default. It extends the JSON schema with more readable forms of the same basic null, boolean, integer, floating-point, string, sequence, and mapping types. YAML 1.1 predates that simplification and ships a broader type library. That broader resolution is the source of famous cases where a country code such as NO, a feature switch such as on, or a date-looking identifier silently becomes a value of another type.

A parser option named “version” often selects a default schema, but implementations can expose those choices separately. Applications may also restrict YAML to a smaller subset or attach their own domain schema after parsing. Therefore, “this is valid YAML 1.2” and “this configuration is accepted by my deployment tool” are different claims.

YAML 1.1 and YAML 1.2 core comparison

The word “typical” matters in the YAML 1.1 column. Implementations differ in completeness, compatibility modes, and native types. A parser might construct a language-specific date object, preserve a tagged scalar node, or leave it as text. Portability comes from declaring intent rather than relying on the most permissive behavior you can find.

The boolean trap: yes, no, on, and off

Consider a service list keyed by two-letter region identifiers. Under a YAML 1.1 schema, an unquoted key named NO may resolve to boolean false. That can collide with another spelling that resolves to the same boolean, or it can produce a non-string mapping key that downstream JSON tools must coerce or reject. The file may look reasonable during review while its constructed data no longer contains the key the author intended.

regions:
  "NO": Norway
features:
  notifications: true
  display_label: "on"

YAML 1.2 core intentionally limits implicit boolean resolution to true and false spellings. That does not mean every application has migrated. Older libraries, compatibility modes, and tools configured for 1.1 still exist. If data crosses systems, quoting is a small cost for a large reduction in ambiguity.

Numbers, leading zeros, and date-shaped strings

YAML 1.1's leading-zero octal notation can turn a code such as 010 into the integer eight. YAML 1.2 uses the explicit 0o prefix for octal and interprets ordinary decimal forms more predictably. Values such as postal codes, account codes, semantic versions, and identifiers should generally be strings even when they contain only digits. Quote them to preserve leading zeros and prevent arithmetic interpretation.

Date resolution is another compatibility boundary. The YAML 1.1 schema supported timestamps as a distinct tag. The YAML 1.2 core schema does not include a timestamp tag, so a plain ISO-looking date remains a string under that schema. An application may still convert the string later. Separating YAML resolution from application-level date parsing makes time zones, accepted formats, invalid dates, and serialization rules explicit.

release_code: "010"
scheduled_date: "2026-08-04"
retry_count: 10
enabled: false

Non-finite floats are valid under YAML core resolution but cannot be represented by the JSON grammar in RFC 8259. A successful YAML parse therefore does not imply lossless YAML-to-JSON conversion.

What the %YAML directive does—and does not do

A version directive appears before a document and must be followed by a document start marker. It communicates the document's YAML version to a processor that recognizes it.

%YAML 1.1
---
switch: on
release_date: 2026-08-04

The directive is not a universal compatibility switch. A consumer may reject unsupported versions, apply its configured schema, warn about compatibility, or process only a documented subset. A multi-document stream can also have directives associated with individual documents. Test the complete stream rather than assuming a directive at the top governs every downstream library in the same way.

Explicit tags can disambiguate standard values, for example !!str 010. Custom tags such as !Duration 5m require an application that knows their meaning. They are not portable simply because a YAML parser can preserve their spelling.

Merge keys are not a YAML 1.2 inheritance system

The special << merge key was published as a YAML 1.1 language-independent type. It is not part of the YAML 1.2 specification. Some libraries enable it, some make it optional, and some treat << as an ordinary mapping key. An anchor and alias are core YAML graph features; a merge key is separate, legacy processing layered on top of them.

LiveParse deliberately does not apply merge-key expansion. Do not use its syntax result as evidence that a Kubernetes manifest, Compose file, CI configuration, or another consumer will merge the same mappings. Read the dedicated anchors, aliases, and merge keys guide, then validate with the target application's own tooling.

How LiveParse labels its behavior

The LiveParse YAML Validator defaults to YAML 1.2 with the core schema and offers YAML 1.1 as an explicit compatibility selection. It performs a strict local syntax check, rejects unresolved aliases, and detects duplicate scalar mapping keys. It does not deeply compare complex collection keys or load a Kubernetes OpenAPI schema, the Compose Specification, a CI vendor's schema, or application business rules.

The YAML Formatter parses and reserializes content. Formatting may change quoting, scalar style, flow versus block style, equivalent numeric spelling, comments, and whitespace. It stops before a precision-losing number or timestamp would change value, but it is still not a source-preserving fixer. The YAML Viewer exposes resolved scalar types, anchors, aliases, tags, non-string keys, and document boundaries so version differences are visible before conversion.

When using YAML to JSON, remember that JSON has fewer representational features. LiveParse stops on alias or complex mapping keys, !!omap, !!pairs, !!binary, !!set, custom or unresolved tags, non-finite values, and precision-losing numbers or timestamps. It uses a maximum alias count of 50 per YAML document, rejects cycles, converts a multi-document stream to a top-level JSON array, and reports presentation loss such as dropped comments. Under YAML 1.1, an unquoted << merge-tag key stops conversion; quoted YAML 1.1 "<<" and literal YAML 1.2 Core << remain ordinary keys. The reverse JSON to YAML path emits a YAML 1.2-compatible representation and preserves exact JSON number tokens in text, while warning that some later JavaScript consumers may still lose numeric precision.

After conversion, inspect generated data with the JSON Formatter and Validator. For a useful contrast, the XML Validator also separates basic syntax from grammar validity: different formats, same rule that parser success is not application-schema proof.

A safe YAML 1.1 to 1.2 migration checklist

1. Inventory actual consumers. Record each parser library, version, schema setting, and application that reads the file.
2. Parse under both schemas. Compare node types and mapping keys, not only formatted text. Pay special attention to boolean-like words, dates, leading-zero numbers, sexagesimal forms, and explicit tags.
3. Quote domain strings. Region codes, modes, dates kept as identifiers, version numbers, phone fragments, and labels should not depend on implicit resolution.
4. Normalize booleans and numbers. Prefer lowercase true/false, ordinary decimal notation, and the explicit 0o prefix only when octal is truly intended.
5. Audit merge keys. Replace undocumented inheritance with explicit mappings or a target-supported configuration feature. Test precedence if the consumer still requires merge behavior.
6. Test domain schemas separately. Run Kubernetes server-side or schema-aware validation, Compose validation, and vendor-specific checks after YAML syntax succeeds.
7. Diff constructed data. Compare the values delivered to the application before and after migration. A text diff cannot reveal every type change.