yaml

Overview ¶

Package yaml — the block structure: mappings, sequences, keys and values.

Package yaml is the SDK's YAML codec: a native, standard-library-only reader and writer of a NAMED SUBSET of YAML 1.2.2, sized for configuration.

The subset ¶

Read: block mappings and sequences (by indentation, including a sequence at its key's own indentation and the compact "- key: value" form), flow mappings and sequences across lines, plain, single-quoted and double-quoted scalars with every YAML escape, literal (|) and folded (>) block scalars with their chomping and indentation indicators, comments, and one document with an optional "---" start and "..." end. Plain scalars resolve by the YAML 1.2 core schema: null and ~, true and false — never yes, no, on or off — decimal, 0o octal and 0x hexadecimal integers, floats with .inf and .nan.

Refused BY NAME, each with its own code and the line and column it starts at: anchors (&), aliases (*), tags (! and !!), merge keys (<<), a second document, complex keys (?, or a collection as a key), directives (%YAML, %TAG), and a mapping holding the same key twice. An integer written with a leading zero (0644) is octal to YAML 1.1 and decimal to YAML 1.2; it reads as text into a string, and is refused by name wherever its value matters.

A refusal never quotes the document: it carries a line, a column, a constant detail and, for a value its Go target cannot hold, the Go type.

Bounds ¶

A document holds at most 10 MiB, 1 048 576 nodes and 100 levels of nesting; an implicit key at most 1024 characters, as YAML itself bounds it. Nothing the decoder is given can make it panic.

Go values ¶

Struct fields use the yaml tag as gopkg.in/yaml.v3 does: a field's key is its tag's name or its own name in lower case, "-" leaves it out, and the flags are omitempty, flow (write the collection inline) and inline (merge a struct's fields, or collect the remaining keys into a map with string keys). An unknown key is ignored. A type may implement MarshalYAML() (any, error), UnmarshalYAML(func(any) error) error, encoding.TextMarshaler and encoding.TextUnmarshaler; time.Time and time.Duration are written and read as text. An untyped target receives nil, bool, int, int64 or uint64, float64, string, []any and map[string]any — a mapping keyed by each key's text.

Writing ¶

The encoder writes deterministic block style, indented by two spaces: struct fields in declaration order, map keys sorted. A string is written plain only when every YAML reader — the core schema, YAML 1.1, a timestamp parser — reads it back as the same string; otherwise it is double-quoted, and a multi-line string is a literal block. A float always carries its dot.

Streams ¶

Unmarshal reads exactly one document and refuses a second by name, where gopkg.in/yaml.v3 silently ignored it. NewDecoder reads a stream of "---"-separated documents, each one read by the same subset and bounded at 10 MiB; NewEncoder writes one.

The whole of YAML — every construct this package refuses — remains available through the opt-in third-party/codec/yaml package, registered as "yaml-full".

Package yaml — the streaming decoder: one document per Decode.

Package yaml — the streaming encoder: one document per Encode.

Package yaml — how a refusal is built: the position every decoding refusal carries, a syntax error at it, a construct refused by name, and an encoding failure. The codes (range 0.3.4.*) and the sentinels are declared in internal/core/data/codec/yaml (ADR 0160).

Package yaml — flow collections: [a, b] and {k: v}, across lines.

Package yaml — the hooks a Go type implements, read once per type.

Package yaml — the hooks a Go type may implement to choose its YAML.

Package yaml — encoding: Go values resolved, then written in block style.

Package yaml — encoding: the block layout of mappings, sequences and keys.

Package yaml — encoding: collections in flow style, for the flow tag.

Package yaml — encoding: how a scalar is written so every reader reads it back.

Package yaml — the parsed document: an arena of nodes and the bounds on it.

Package yaml — the parser: its state, its cursor, and one document.

Package yaml — the YAML 1.2 core schema: what a plain scalar means.

Package yaml — scalars: plain, single-quoted, double-quoted, and block.

Package yaml — what a struct's yaml tags say, read once per type.

Package yaml — decoding: the source checked, the document parsed, values built.

Package yaml — decoding into typed targets, by reflection.