YAML Specification

https://github.com/yaml/yaml-spec
Admin
The YAML Specification defines the syntax and semantics of the YAML (YAML Ain't Markup Language)...
Tokens:112,005
Snippets:1,127
Trust Score:7.4
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Play by Play Feed from a Game (Example 2.8)

Source: https://github.com/yaml/yaml-spec/blob/main/www/external/spec-2009/yaml-spec-12.html

Shows two documents in a stream, each with a mapping of game events. The first document ends with '...' and the second starts with '---'. Demonstrates document separation and end markers.

```yaml
---
time: 20:03:20
player: Sammy Sosa
action: strike (miss)
...
---
time: 20:03:47
player: Sammy Sosa
action: grand slam
...

```

--------------------------------

### Global tag prefix example

Source: https://github.com/yaml/yaml-spec/blob/main/spec/1.2.2/spec.md

Example of global tag prefix with a custom prefix.

```yaml
%TAG !e! tag:example.com,2000:app/
---
- !e!foo "bar"

```

```yaml
- !<tag:example.com,2000:app/foo> "bar"

```

--------------------------------

### Plain lines example (JSON output)

Source: https://github.com/yaml/yaml-spec/blob/main/spec/1.2.2/spec.md

Expected JSON representation of the plain lines example, showing how line folding is applied.

```yaml
"1st non-empty\n2nd non-empty 3rd non-empty"

```

--------------------------------

### Plain implicit keys example (JSON output)

Source: https://github.com/yaml/yaml-spec/blob/main/spec/1.2.2/spec.md

Expected JSON representation of the plain implicit keys example.

```yaml
{ "implicit block key":
  [ { "implicit flow key": "value" } ] }

```

--------------------------------

### Flow Mappings example with JSON equivalent

Source: https://github.com/yaml/yaml-spec/blob/main/spec/1.2.2/spec.md

Example of flow mappings in YAML and their JSON equivalent. Shows that spaces around ':' and ',' are optional and trailing commas are allowed.

```yaml
- { one : two , three: four , }
- {five: six,seven : eight}
```

```yaml
[ { "one": "two",
    "three": "four" },
  { "five": "six",
    "seven": "eight" } ]
```

--------------------------------

### Tag shorthands example

Source: https://github.com/yaml/yaml-spec/blob/main/spec/1.2.2/spec.md

Example of tag shorthands with a TAG directive, showing local, standard, and custom tags.

```yaml
%TAG !e! tag:example.com,2000:app/
---
- !local foo
- !!str bar
- !e!tag%21 baz

```

```yaml
[ !<!local> "foo",
  !<tag:yaml.org,2002:str> "bar",
  !<tag:example.com,2000:app/tag!> "baz" ]

```

--------------------------------

### Secondary tag handle example

Source: https://github.com/yaml/yaml-spec/blob/main/spec/1.2.2/spec.md

Example of secondary tag handle with a custom prefix.

```yaml
%TAG !! tag:example.com,2000:app/
---
!!int 1 - 3 # Interval, not integer

```

```yaml
!<tag:example.com,2000:app/int> "1 - 3"

```

--------------------------------

### Node properties example

Source: https://github.com/yaml/yaml-spec/blob/main/spec/1.2.2/spec.md

Example of node properties in block and flow styles, showing anchors and tags.

```yaml
!!str &a1 "foo":
  !!str bar
&a2 baz : *a1

```

```yaml
{ &B1 "foo": "bar",
  "baz": *B1 }

```

--------------------------------

### Flow Sequence example with JSON equivalent

Source: https://github.com/yaml/yaml-spec/blob/main/spec/1.2.2/spec.md

Example of flow sequences in YAML and their equivalent JSON representation. Shows that trailing commas are allowed and that spaces around commas are optional.

```yaml
- [ one, two, ]
- [three ,four]
```

```yaml
[ [ "one",
    "two" ],
  [ "three",
    "four" ] ]
```

--------------------------------

### Primary tag handle example

Source: https://github.com/yaml/yaml-spec/blob/main/spec/1.2.2/spec.md

Example of primary tag handle with default local tag and overridden global tag.

```yaml
# Private
!foo "bar"
...
# Global
%TAG ! tag:example.com,2000:app/
---
!foo "bar"

```

```yaml
!<!foo> "bar"
---
!<tag:example.com,2000:app/foo> "bar"

```

--------------------------------

### YAML 1.2 directive with flow mapping

Source: https://github.com/yaml/yaml-spec/blob/main/www/external/spec-2009/yaml-spec-12.html

Shows the use of the percent indicator to start a directive line. The example includes a YAML 1.2 directive followed by a flow mapping with explicit string keys and values.

```yaml
%YAML 1.2---
!!map {
  ? !!str "single"
  : !!str "text",
  ? !!str "double"
  : !!str "text",
}

```

--------------------------------

### Plain characters example (JSON output)

Source: https://github.com/yaml/yaml-spec/blob/main/spec/1.2.2/spec.md

Expected JSON representation of the plain characters example, showing how the scalars are interpreted.

```yaml
[ "::vector",
  ": - ()",
  "Up, up, and away!",
  -123,
  "https://example.com/foo#bar",
  [ "::vector",
    ": - ()",
    "Up, up, and away!",
    -123,
    "https://example.com/foo#bar" ] ]

```

--------------------------------

### Block Mapping Example

Source: https://github.com/yaml/yaml-spec/blob/main/spec/1.2.2/spec.md

Example of a block mapping with a single key-value pair, shown in YAML and its JSON equivalent.

```yaml
block mapping:
·key: value↓

```

```json
{ "block mapping": {
    "key": "value" } }

```

--------------------------------

### Verbatim tags example

Source: https://github.com/yaml/yaml-spec/blob/main/spec/1.2.2/spec.md

Example of verbatim tags in block and flow styles.

```yaml
!<tag:yaml.org,2002:str> foo :
  !<!bar> baz

```

```yaml
{ "foo": !<!bar> "baz" }

```

--------------------------------

### Named tag handle example

Source: https://github.com/yaml/yaml-spec/blob/main/spec/1.2.2/spec.md

Example of named tag handle with a custom prefix.

```yaml
%TAG !e! tag:example.com,2000:app/
---
!e!foo "bar"

```

```yaml
!<tag:example.com,2000:app/foo> "bar"

```

--------------------------------

### Example 2.27: Invoice YAML document

Source: https://github.com/yaml/yaml-spec/blob/main/www/external/spec-2009/yaml-spec-12.html

Full-length YAML example of an invoice document. Demonstrates custom tags, anchors and aliases, block scalars, and a sequence of mapping items.

```yaml
--- !<tag:clarkevans.com,2002:invoice>invoice: 34843
date   : 2001-01-23
bill-to: &id001
    given  : Chris
    family : Dumars
    address:
        lines: |
            458 Walkman Dr.
            Suite #292
        city    : Royal Oak
        state   : MI
        postal  : 48046
ship-to: *id001
product:
    - sku         : BL394D
      quantity    : 4
      description : Basketball
      price       : 450.00
    - sku         : BL4438H
      quantity    : 1
      description : Super Hoop
      price       : 2392.00
tax  : 251.42
total: 4443.52
comments:
    Late afternoon is best.
    Backup contact is Nancy
    Billsmer @ 338-4338.

```

--------------------------------

### Literal content example

Source: https://github.com/yaml/yaml-spec/blob/main/spec/1.2.2/spec.md

Example of literal content with empty lines and a comment. The output shows the literal content with normalized line breaks.

```yaml
|
·
··
··literal↓
···↓
··
··text↓
↓
·# Comment
```

```json
"\n\nliteral\n·\n\ntext\n"
```

--------------------------------

### Implicit Block Mapping Entries Example

Source: https://github.com/yaml/yaml-spec/blob/main/spec/1.2.2/spec.md

Example of implicit block mapping entries with plain, empty, and quoted keys, shown in YAML and its JSON equivalent.

```yaml
plain key: in-line value
°:° # Both empty
"quoted key":
- entry

```

```json
{ "plain key": "in-line value",
  null: null,
  "quoted key": [ "entry" ] }

```

--------------------------------

### Node Property Indicators Example

Source: https://github.com/yaml/yaml-spec/blob/main/www/external/spec-2009/yaml-spec-12.html

Example 5.6 shows node property indicators. The first block is the YAML input, the second is a legend, and the third is the corresponding YAML representation.

```yaml
anchored: !local &anchor valuealias: *anchor

```

```text
Legend:
  c-tag c-anchor c-alias

```

```yaml
%YAML 1.2---
!!map {
  ? !!str "anchored"
  : !local &A1 "value",
  ? !!str "alias"
  : *A1,
}

```

--------------------------------

### Plain lines example (YAML)

Source: https://github.com/yaml/yaml-spec/blob/main/spec/1.2.2/spec.md

Example YAML showing line folding in plain scalars. The '↓' and '→' symbols represent line breaks and spaces.

```yaml
1st non-empty↓
↓
·2nd non-empty·
→3rd non-empty

```

--------------------------------

### Block Folding example with input and output

Source: https://github.com/yaml/yaml-spec/blob/main/spec/1.2.2/spec.md

Example of block folding in the folded block style. The first block is the YAML input, the second is the resulting string value.

```yaml
>
··foo·↓
·↓
··→·bar↓
↓
··baz↓
```

```yaml
"foo \n\n\t bar\n\nbaz\n"
```

--------------------------------

### Block sequence example with JSON output

Source: https://github.com/yaml/yaml-spec/blob/main/spec/1.2.2/spec.md

Example of a block sequence with two entries: a plain scalar and a mapping. The JSON output shows the parsed structure.

```yaml
block sequence:
··- one↓
  - two : three↓

```

```json
{ "block sequence": [
    "one",
    { "two": "three" } ] }

```

--------------------------------

### Plain characters example (YAML)

Source: https://github.com/yaml/yaml-spec/blob/main/spec/1.2.2/spec.md

Example YAML document showing valid plain scalars in block and flow contexts. Note the quoted strings for scalars that would otherwise be ambiguous.

```yaml
# Outside flow collection:
- ::vector
- ": - ()"
- Up, up, and away!
- -123
- https://example.com/foo#bar
# Inside flow collection:
- [ ::vector,
  ": - ()",
  "Up, up and away!",
  -123,
  https://example.com/foo#bar ]

```

--------------------------------

### Comment lines example

Source: https://github.com/yaml/yaml-spec/blob/main/spec/1.2.2/spec.md

Example of comment lines. The first block shows a comment line with indentation and blank lines; the second block shows a stream containing only comments.

```yaml
··# Comment↓
···↓
↓

```

```yaml
# This stream contains no
# documents, only comments.

```

--------------------------------

### Empty Lines example with input and output

Source: https://github.com/yaml/yaml-spec/blob/main/spec/1.2.2/spec.md

Example showing how empty lines are interpreted in flow and block scalars. The first block is the YAML input, the second is the resulting JSON-like representation.

```yaml
Folding:
  "Empty line
···→
  as a line feed"
Chomping: |
  Clipped empty lines
·
```

```yaml
{ "Folding": "Empty line\nas a line feed",
  "Chomping": "Clipped empty lines\n" }
```

--------------------------------

### More Indented Lines Example 8.11

Source: https://github.com/yaml/yaml-spec/blob/main/www/external/spec-2009/yaml-spec-12.html

Demonstrates more-indented lines (starting with spaces) that are not folded. The output preserves the extra spaces and line breaks for those lines.

```yaml
>
 folded
 line

 next
 line
···* bullet↓
↓
···* list↓
···* lines↓

 last
 line

# Comment

```

```yaml
%YAML 1.2---
!!str "\n\
      folded line\n\
      next line\n\
      \  * bullet\n
      \n\
      \  * list\n\
      \  * lines\n\
      \n\
      last line\n"

```

--------------------------------

### Full-length YAML log file example

Source: https://github.com/yaml/yaml-spec/blob/main/spec/1.2.2/spec.md

A full-length YAML example showing a sample log file with multiple documents separated by ---. It demonstrates block scalars (| and |-), sequences, and nested mappings.

```yaml
---
Time: 2001-11-23 15:01:42 -5
User: ed
Warning:
  This is an error message
  for the log file
---
Time: 2001-11-23 15:02:31 -5
User: ed
Warning:
  A slightly different error
  message.
---
Date: 2001-11-23 15:03:17 -5
User: ed
Fatal:
  Unknown variable "bar"
Stack:
- file: TopClass.py
  line: 23
  code: |
    x = MoreObject("345\n")
- file: MoreClass.py
  line: 58
  code: |-
    foo = bar

```

--------------------------------

### Folded Lines Example 8.10

Source: https://github.com/yaml/yaml-spec/blob/main/www/external/spec-2009/yaml-spec-12.html

Illustrates folded lines with more-indented lines (starting with spaces) that are not folded. The output preserves the indentation and line breaks for those lines.

```yaml
>
·folded↓
·line↓
↓
·next
·line↓
   * bullet

   * list
   * lines

·last↓
·line↓

# Comment

```

```yaml
%YAML 1.2---
!!str "\n\
      folded line\n\
      next line\n\
      \  * bullet\n
      \n\
      \  * list\n\
      \  * lines\n\
      \n\
      last line\n"

```

--------------------------------

### Non-Specific Tags (Example 6.28)

Source: https://github.com/yaml/yaml-spec/blob/main/www/external/spec-2009/yaml-spec-12.html

Shows how non-specific tags are resolved: plain scalars get the '?' tag, while quoted scalars and the explicit '!' tag get the '!' non-specific tag. The first block is the YAML input, the second is the legend for the syntax diagram, and the third is the corresponding YAML representation tree.

```yaml
# Assuming conventional resolution:
- "12"
- 12
- ! 12
```

```text
Legend:
  c-non-specific-tag
```

```yaml
%YAML 1.2
---
!!seq [
  !<tag:yaml.org,2002:str> "12",
  !<tag:yaml.org,2002:int> "12",
  !<tag:yaml.org,2002:str> "12",
]
```

--------------------------------

### Bare Documents example

Source: https://github.com/yaml/yaml-spec/blob/main/spec/1.2.2/spec.md

Shows a bare document followed by a document end marker and a second bare document, with the parsed output.

```yaml
Bare
document
...
# No document
...
|
%!PS-Adobe-2.0 # Not the first line
```

```yaml
"Bare document"
---
"%!PS-Adobe-2.0\n"
```

--------------------------------

### Example: Line Prefixes

Source: https://github.com/yaml/yaml-spec/blob/main/spec/1.2.2/spec.md

Example showing line prefixes in YAML and the corresponding JSON representation. The YAML uses spaces and tabs for line prefixes, which are presentation details and do not affect the content.

```yaml
plain: text
··lines
quoted: "text
··→lines"
block: |
··text
···→lines

```

```json
{ "plain": "text lines",
  "quoted": "text lines",
  "block": "text\n \tlines\n" }

```

--------------------------------

### Folded scalar example

Source: https://github.com/yaml/yaml-spec/blob/main/spec/1.2.2/spec.md

Example of a folded scalar and its parsed value.

```yaml
>
folded
text

```

```yaml
"folded text\n"

```

--------------------------------

### Indentation Spaces example (YAML input and JSON output)

Source: https://github.com/yaml/yaml-spec/blob/main/spec/1.2.2/spec.md

Example showing how indentation spaces are handled in YAML. The first block is the YAML input, and the second is the corresponding JSON output. It demonstrates that leading spaces in comments and flow style are neither content nor indentation, and that block scalar content can be further indented.

```yaml
··# Leading comment line spaces are
···# neither content nor indentation.
····
Not indented:
·By one space: |
····By four
······spaces
·Flow style: [    # Leading spaces
···By two,        # in flow style
··Also by two,    # are neither
··→Still by two   # content nor
····]             # indentation.

```

```json
{ "Not indented": {
    "By one space": "By four\n  spaces\n",
    "Flow style": [
      "By two",
      "Also by two",
      "Still by two" ] } }

```

--------------------------------

### Folded lines example

Source: https://github.com/yaml/yaml-spec/blob/main/spec/1.2.2/spec.md

Example of folded lines with a comment and its parsed value.

```yaml
>

folded
line

next
line
   * bullet

   * list
   * lines

last
line

# Comment

```

```yaml
"\nfolded line\nnext line\n  \
* bullet\n \n  * list\n  \
* lines\n\nlast line\n"

```

--------------------------------

### TAG directive example

Source: https://github.com/yaml/yaml-spec/blob/main/spec/1.2.2/spec.md

Example of a TAG directive with a named handle and its output.

```yaml
%TAG !yaml! tag:yaml.org,2002:
---
!yaml!str "foo"

```

```yaml
"foo"

```

--------------------------------

### YAML !!int tag examples

Source: https://github.com/yaml/yaml-spec/blob/main/www/external/spec-2009/yaml-spec-12.html

Shows the canonical form of the integer tag and how to explicitly tag integer values.

```yaml
negative: !!int -12zero: !!int 0
positive: !!int 34
```

--------------------------------

### More-indented lines example

Source: https://github.com/yaml/yaml-spec/blob/main/spec/1.2.2/spec.md

Example of more-indented lines in folded style and its parsed value.

```yaml
>

 folded
 line

 next
 line
···* bullet

···* list
···* lines

 last
 line

# Comment

```

```yaml
"\nfolded line\nnext line\n  \
* bullet\n \n  * list\n  \
* lines\n\nlast line\n"

```

--------------------------------

### Invalid verbatim tags example

Source: https://github.com/yaml/yaml-spec/blob/main/spec/1.2.2/spec.md

Invalid verbatim tags example with error output.

```yaml
- !<!> foo
- !<$:?> bar

```

```yaml
ERROR:
- Verbatim tags aren't resolved,
  so ! is invalid.
- The $:? tag is neither a global
  URI tag nor a local tag starting
  with '!'.

```

--------------------------------

### Example: Tabs and Spaces in YAML

Source: https://github.com/yaml/yaml-spec/blob/main/spec/1.2.2/spec.md

Example showing how tabs and spaces are represented in YAML and the corresponding JSON output. The YAML uses the glyphs '→' for tab and '·' for space for clarity.

```yaml
# Tabs and spaces
quoted:·"Quoted →"
block:→|
··void main() {
··→printf("Hello, world!\n");
··}

```

```json
{ "quoted": "Quoted \t",
  "block": "void main()
    {\n\tprintf(\"Hello, world!\\n\");\n}\n" }
```

--------------------------------

### Non-specific tags example

Source: https://github.com/yaml/yaml-spec/blob/main/spec/1.2.2/spec.md

Example of non-specific tags, showing how explicit '!' disables tag resolution.

```yaml
# Assuming conventional resolution:
- "12"
- 12
- ! 12

```

```yaml
[ "12",
  12,
  "12" ]

```

--------------------------------

### Indentation Indicators example (YAML input and JSON output)

Source: https://github.com/yaml/yaml-spec/blob/main/spec/1.2.2/spec.md

Example showing how the '-', '?', and ':' characters used for block collection entries are perceived as part of the indentation. The first block is the YAML input, and the second is the corresponding JSON output. It demonstrates that these indicators are handled on a case-by-case basis by the relevant productions.

```yaml
?·a
:·-→b
··-··-→c
·····-·d

```

```json
{ "a":
  [ "b",
    [ "c",
      "d" ] ] }

```

--------------------------------

### Local tag prefix example

Source: https://github.com/yaml/yaml-spec/blob/main/spec/1.2.2/spec.md

Example of local tag prefix with two documents in the same stream.

```yaml
%TAG !m! !my-
--- # Bulb here
!m!light fluorescent
...
%TAG !m! !my-
--- # Color here
!m!light green

```

```yaml
!<!my-light> "fluorescent"
---
!<!my-light> "green"

```

--------------------------------

### Empty separation lines example

Source: https://github.com/yaml/yaml-spec/blob/main/spec/1.2.2/spec.md

Example of empty separation lines in folded style and its parsed value.

```yaml
>

 folded
 line

 next
 line
   * bullet

   * list
   * lines

 last
 line

# Comment

```

```yaml
"\nfolded line\nnext line\n  \
* bullet\n \n  * list\n  \
* lines\n\nlast line\n"

```

--------------------------------

### Literal scalar example

Source: https://github.com/yaml/yaml-spec/blob/main/spec/1.2.2/spec.md

Example of a literal scalar. All indented characters are content, and line breaks are normalized.

```yaml
|↓
·literal↓
·→text↓
↓
```

```json
"literal\n\ttext\n"
```

--------------------------------

### YAML !!bool tag examples

Source: https://github.com/yaml/yaml-spec/blob/main/www/external/spec-2009/yaml-spec-12.html

Shows the canonical forms of the boolean tag and how to explicitly tag boolean values.

```yaml
YAML is a superset of JSON: !!bool truePluto is a planet: !!bool false
```

--------------------------------

### Load YAML v1 and expose as npmYAML1

Source: https://github.com/yaml/yaml-spec/blob/main/www/jekyll/_includes/head-npm-yaml.html

Imports the YAML object and testEvents from the YAML v1 browser build, attaches events to YAML, and exposes it as window.npmYAML1.

```javascript
import { YAML } from '{{site.baseurl}}/ext/npm-yaml/v1/browser/dist/index.js'; import { testEvents } from '{{site.baseurl}}/ext/npm-yaml/v1/browser/dist/test-events.js'; YAML.events = testEvents; window.npmYAML1 = YAML;
```

--------------------------------

### Example 5.1: Byte Order Mark

Source: https://github.com/yaml/yaml-spec/blob/main/www/external/spec-2009/yaml-spec-12.html

Example 5.1 shows a YAML stream that begins with a byte order mark (displayed as ⇔) followed by a comment. The legend identifies the c-byte-order-mark production, and the final comment notes that the stream contains no documents, only comments.

```yaml
⇔# Comment only.
```

```yaml
Legend:
  c-byte-order-mark
```

```yaml
# This stream contains no# documents, only comments.
```

--------------------------------

### Block Structure Indicators Example

Source: https://github.com/yaml/yaml-spec/blob/main/www/external/spec-2009/yaml-spec-12.html

Example 5.3 shows block sequence and mapping indicators. The first block is the YAML input, the second is a legend, and the third is the corresponding YAML representation.

```yaml
sequence:- one
- two
mapping:
  ? sky
  : blue
  sea : green

```

```text
Legend:
  c-sequence-entry
  c-mapping-key c-mapping-value

```

```yaml
%YAML 1.2---
!!map {
  ? !!str "sequence"
  : !!seq [ !!str "one", !!str "two" ],
  ? !!str "mapping"
  : !!map {
    ? !!str "sky" : !!str "blue",
    ? !!str "sea" : !!str "green",
  },
}

```

--------------------------------

### Block sequence entry types example with JSON output

Source: https://github.com/yaml/yaml-spec/blob/main/spec/1.2.2/spec.md

Example showing the four entry types in a block sequence: empty, block node, compact sequence, and compact mapping. The JSON output shows the parsed values.

```yaml
-° # Empty
- |
 block node
-·- one # Compact
··- two # sequence
- one: two # Compact mapping

```

```json
[ null,
  "block node\n",
  [ "one", "two" ],
  { "one": "two" } ]

```

--------------------------------

### Mapping between Sequences (Example 2.11)

Source: https://github.com/yaml/yaml-spec/blob/main/www/external/spec-2009/yaml-spec-12.html

Shows complex mapping keys using '?' and ':' to map sequences to other sequences. The first key is a block sequence, the second is a flow sequence.

```yaml
? - Detroit Tigers
  - Chicago cubs
:
  - 2001-07-23

? [ New York Yankees,
    Atlanta Braves ]
: [ 2001-07-02, 2001-08-12,
    2001-08-14 ]

```

--------------------------------

### Separated comment example

Source: https://github.com/yaml/yaml-spec/blob/main/spec/1.2.2/spec.md

Example of a separated comment after a key. The YAML input has a comment after the key, and the JSON output shows the resulting value.

```yaml
key:····# Comment↓
  value_eof_

```

```json
{ "key": "value" }

```

--------------------------------

### Quoted Scalar Indicators Example

Source: https://github.com/yaml/yaml-spec/blob/main/www/external/spec-2009/yaml-spec-12.html

Example 5.8 shows quoted scalar indicators. The first block is the YAML input, the second is a legend.

```yaml
single: 'text'double: "text"

```

```text
Legend:
  c-single-quote c-double-quote

```

--------------------------------

### YAML !!null tag examples

Source: https://github.com/yaml/yaml-spec/blob/main/www/external/spec-2009/yaml-spec-12.html

Shows the canonical form of the null tag and how to explicitly tag a null value in a mapping.

```yaml
!!null null: value for null keykey with null value: !!null null
```
Tokens:
Raw