# `Formata.Codec.YAML`
[🔗](https://github.com/gsmlg-dev/formata/blob/v0.3.5/lib/formata/codec/yaml.ex#L1)

Single-document YAML codec: decoding with `Formata.YAML.Reader`, encoding
with `Formata.YAML.Writer`.

## Decoding

  * Exactly one document is accepted. A stream containing more than one
    document is rejected with `:parse` / `:multiple_documents`; Formata
    never silently picks one. An empty stream decodes to `nil`.
  * Mapping keys stay as decoded (strings for plain keys; YAML integer or
    boolean keys stay integers/booleans). No atoms are created from content.
  * Duplicate mapping keys are rejected with `:parse` / `:duplicate_key`,
    including the line/column reported by the parser.
  * Plain implicit merge keys (`<<`) are rejected with `:unsupported` /
    `:merge_key`; quoted or explicitly string-tagged `<<` keys stay literal.
  * Null and float scalar keys remain distinct values (including normalized
    special floats). Sequence/mapping keys are `:unsupported_key` errors.
  * Anchors and aliases are expanded; anchors, comments, formatting and key
    order are not preserved.
  * `.inf`, `-.inf`, `.nan` become `:infinity`, `:negative_infinity`, `:nan`.
  * Timestamps are not resolved by the parser's YAML core schema:
    `2001-12-14` decodes as the string `"2001-12-14"`.
  * Syntax errors carry the line/column reported by the parser.

Options (also enforced for encoding and its read-back check):

  * `:max_depth` — non-negative maximum node depth (default `128`); root
    depth is zero and mapping keys, values and sequence elements add one.
  * `:max_nodes` — positive maximum expanded node count (default `100_000`),
    including mapping keys and every occurrence of an aliased subtree.

Limits are finite and local to each call. Parsing stops before an alias
exceeds a limit; validation, normalization and conversion share one bounded
traversal. The parser also bounds pending syntax before construction. An
explicit `%YAML 1.1` directive selects that schema; otherwise YAML 1.2 core
scalar resolution applies. Timestamps remain strings in both schemas.

## Encoding

The YAML domain is `nil`, booleans, integers, floats (including the
special-float atoms), UTF-8 strings, lists, and maps whose keys are strings,
integers, or booleans. `Date`/`Time`/`DateTime` values are rejected because
they do not decode back to the same values; convert them explicitly with
`Formata.Transform.temporal_to_iso8601/1`.

Every encoded document is decoded again and compared with the input. If the
emitted YAML would read back as a different value (for example a string that
the emitter left unquoted although it resolves to a number), encoding fails
with `:encode` / `:roundtrip_mismatch` instead of returning lossy output.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
