The syntax of YAML has changed little since 2005. What changed most between 1.1 and 1.2 is what plain values mean. Many readers still follow 1.1, so the same file can read differently in different programs.
Versions of the specification
| Version | Date | Notes |
|---|---|---|
| 1.0 | 29 January 2004 | The first release of the specification |
| 1.1 | 18 January 2005 | The version libyaml and PyYAML implement |
| 1.2 | 21 July 2009 | Makes YAML a superset of JSON, and replaces the type repository with schemas |
| 1.2.1 | 1 October 2009 | Corrections to the text |
| 1.2.2 | 1 October 2021 | Clarifications. No changes to the language |
What a plain value means
A plain value with no tag gets its type from its form. YAML 1.1 used the regular expressions on yaml.org/type, and YAML 1.2 uses its core schema.
| Written | YAML 1.1 type repository | YAML 1.2 core schema |
|---|---|---|
yes, no, on, off | Boolean | String |
y, n | Boolean | String |
010 | Integer 8 (octal) | Integer 10 |
0o10 | String | Integer 8 |
0b101 | Integer 5 | String |
1_000 | Integer 1000 | String |
1:30:00 | Integer 5400 (base 60) | String |
2001-12-14 | Timestamp | String |
1e3 | String | Float 1000 |
<< | Merge key | String |
= | Default value key | String |
The classic result is the country code NO, read as the boolean false by a
reader using the 1.1 rules. Writing a value in quotes makes it a string under either
version.
country: NO # false in YAML 1.1, the string "NO" in YAML 1.2
version: 1.20 # a float in both, so a version number loses its last digit
hours: 1:30:00 # 5400 in YAML 1.1
safe: "NO" # a string in bothOther differences
| Area | YAML 1.1 | YAML 1.2 |
|---|---|---|
| JSON | Not a goal | Every JSON text is YAML |
NEL, LS, PS | Line breaks | Ordinary characters |
Escape \/ | Not defined | A slash, for JSON compatibility |
| Type repository | !!binary, !!omap, !!pairs, !!set, !!timestamp, !!merge, !!value | Not part of any schema |
Choosing how to read a file
A reader that implements 1.2 must accept a document with %YAML 1.1.
The specification says it should process that document as 1.2 and warn where they
differ. A document with no directive is read by whatever the reader implements.
The viewer on this site reads YAML by the 1.2 syntax, applies the 1.1 types to a document
that declares %YAML 1.1, and notes where a value would read differently
under 1.1.
For a file that must work everywhere, write booleans as true and
false, and quote anything that looks like a number or date but is
text.
Specification
Section 6.8.1 of YAML 1.2.2 covers version handling. Earlier specifications are at yaml.org/spec.