.YAML File Format – Reading YAML in the explorer

The tree and the Text tab

The tree has a node for every document, mapping, sequence, entry, key, colon and scalar, with its style, and the bytes of every node, so each byte of the file belongs to one node. A comment, a property (&anchor, !tag) and a directive are bytes in the tree too. An alias shows the anchor it refers to and the line it is on, and is never copied. The Text tab shows the file coloured, with the same colouring as the code blocks on this site. Errors and notes are attached to the node where they are, with the line and column.

The Data tab

The Data tab lists every document of the file as the data it stands for, one row per value: its path (indented by depth), its type and its value. It is worked out a page of 200 rows at a time, by counting what is in each node, so a list of a million items, or the second document after a list of 100,000 items, is reached by paging and costs no more than the first page. Nothing is cut off. A row with bytes behind it selects them. The first row of each document says which schema it was read with.

• Lazy expansion. An alias is listed as the node it points at, with that node’s rows under it. An alias that would add more than 100,000 rows is one row that says “expanded lazily”, with the number of keys or items it stands for: the same data is listed in full once, where its anchor is, so every value is still reachable. This is what keeps a “billion laughs” file small. An alias to a node that contains it (a recursive structure) is one row that says so.

• Types. A plain scalar gets its type from the document’s schema: null, boolean, integer or float under the 1.2 core schema, and under the 1.1 type repository also base 60 numbers, octal, binary, underscores and timestamps. A quoted or block scalar is a string. An explicit tag from the YAML tag repository decides the type instead. Infinity and NaN are written as such, a timestamp as an ISO string, and !!binary data as its base 64 text.
• Aliases show as sequence (alias), mapping (alias) or the scalar’s type with (alias), and the value starts with *name.
• Merge keys (<<) are expanded as the YAML 1.1 merge type says: the entries of the merged mapping, or of each mapping of a sequence, are added, an entry written in the mapping itself wins, and an earlier mapping of the sequence wins over a later one. Each merged entry says (merged from *name). This is done in every document: a strict 1.2 reader would keep << as an ordinary key, but nearly every library expands it. A << whose value is not a mapping or a sequence of mappings is an ordinary key.
• Sets, ordered mappings and pairs: !!set lists its keys, and !!omap and !!pairs are sequences of one-key mappings, as they are.
• Keys that are not strings give their path as their value and their type, 1 (integer), and a key that is a collection as its source text.
• Anchors and other tags start the value (&base, !local); a custom tag is not interpreted.

Which version a document is read as

A document with %YAML 1.0 or %YAML 1.1 (or %YAML:1.0, see YAML 1.0) is read as 1.0 or 1.1. Every other document, with no directive or with %YAML 1.2, is read as 1.2. The version is chosen for each document, so a stream can hold both. It decides three things:

• the types of plain scalars (the 1.1 type repository or the 1.2 core schema);
• whether NEL (U+0085), LS (U+2028) and PS (U+2029) end a line: they do in 1.0 and 1.1, where a comment, a plain scalar or a key stops at one and a block scalar line ends there, and they are ordinary characters in 1.2. A NEL inside a quoted or plain scalar folds like a line feed, and LS and PS are kept as they are and are not folded. In a literal or folded block scalar of a 1.0 or 1.1 document a NEL ends a line like a line feed, and an LS or PS ends the line and is kept in the text in place of a line feed (and is not folded);
• whether an anchor or alias name can hold a comma, bracket or brace (1.0 and 1.1 outside flow collections: yes; 1.2: no);
• for 1.0, the tag shorthands, the ^ tag prefix with its two errors, the \^ escape, the %YAML:1.0 directive and the rule that a first document with no --- must be a collection.

The Overview tab lists, for a file with no directive, every value that 1.1 would read differently (no, 010, 1:30) with its first line.

Checks that give notes

The syntax errors are on Errors and pitfalls. These checks give notes, and the file still reads:

Each failure is labelled “Tag check” on the node. A local tag (!local) and a tag from another domain are valid and are not interpreted: nothing is known about their meaning, which belongs to the program that reads the file.

Repeated keys are found by value, not by text. Two keys of one mapping are the same key when their type and value are the same: 1 and 0x1, 1.0 and 1.00, ~ and null, [a, b] written twice, and in a 1.1 document yes and true. 1 and "1", or 1 and 1.0, are different keys. A << key is not a repeat.

Specification

Resolving a node is section 3.3 of YAML 1.2.2, the tags are in chapter 10 and the 1.1 types and the merge type are on yaml.org/type. Comparing keys is section 3.2.1.3.