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

Single-document YAML codec: decoding with `Formata.YamlElixir` (yamerl), encoding
with `Formata.Ymlr`.

## 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 yamerl.
  * Merge keys (`<<`) are rejected with `:unsupported` / `:merge_key`.
  * 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 YAML core schema used by yamerl:
    `2001-12-14` decodes as the string `"2001-12-14"`.
  * Syntax errors carry the line/column reported by yamerl.

Options: none.

## 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*