How a written value is spelt¶

Every write goes in as a Go value and comes out as YAML text. This page is the complete set of rules for what that text is. The contract behind all of them is one sentence: the value you write reads back as the same type and value under the document's own YAML version, and the source around it is not touched. Everything below is how the spelling is chosen to keep that true while looking like something a person would have written.

The rules are pinned by spelling_docs_test.go, which runs every row of the tables below; if the engine and this page disagree, the test fails.

Scalar kinds¶

A type the profile cannot represent, such as a float under Failsafe, is refused with ErrUnsupportedType rather than written as text.

Strings¶

A string is written plain when plain is safe, double-quoted when it is not, and as a literal block when it holds line breaks and a block can go there.

Plain¶

The text is written bare when, under the document's version, it would read back as exactly that string and nothing else:

k: new
k: 😀
k: a    b          # a tab is fine in a YAML 1.2 plain scalar
k: yes         # a string under YAML 1.2, where yes is not a boolean

Double-quoted¶

Anything that would change meaning or shape as a plain scalar goes in double quotes, with escapes where needed:

Single quotes are never chosen for a new value; they are kept where they already are (see Existing scalars).

Literal block¶

A string containing \n is written as a literal block scalar when the target is in block context: below a mapping key or on a sequence item's dash line, one indentation step in, using the document's own step and line ending.

The block's final line break replaces the scalar's own, so the file gains no blank line. The body reads back exactly, including under YAML 1.1.

It stays double-quoted, with \n escapes, where a block cannot go:

Existing scalars¶

Replacing a scalar keeps its spelling where the new value fits it. The rule is D60: the style is retained, no tag is added to keep it, and a style that cannot hold the value gives way.

A non-string value written over a quoted or block scalar takes its own spelling (k: 'old' → k: 42); a timestamp or binary keeps a quoted style for its content where there was one (!<…timestamp> '2001-01-02T03:04:05Z').

An existing scalar with an explicit tag keeps it when the new value is the same type (!!str old → !!str 42: the tag already makes it a string), and refuses a value of a different type with ErrTagIntent. An anchored scalar keeps its anchor.

Mapping keys¶

A new key is written plain when its text reads back as the same string key, and double-quoted otherwise, so 09 or true as a key becomes "09": and "true": rather than an integer or boolean key. An existing key is never respelt; it is matched by value, so StringStep("port") finds port: and KeyStep(IntKey(8080)) finds 8080: or 0x1f90:.

Collections¶

A Go map has no order, so its keys are written sorted; MappingInput writes entries in the order given. A scalar with a comment on its line that becomes a collection is written in flow style on that line, so the comment keeps its owner.

Version differences¶

Document.Version reports which rules a document is under.