YAML guides

Recipe-style walk-throughs for Bodu.Text.Yaml (YamlSerializer) - the indentation-structured format member of the Bodu serializer family. YAML keeps the family architecture and the shared attribute family: member shaping is naming policies, the [PropertyName] / [Ignore] attributes (and the wider Bodu.Text.Serialization set), options flags, and custom YamlConverter<T> converters. Each guide below is written against the real surface.

If you are new to the family, start with the introduction for the format specifics and the core concepts for the three-tier mental model, then work through the guides in order.

Guides

Using YAML

YamlSerializer - round-trip an object, configure YamlSerializerOptions, both DOMs, multi-document streams via ParseAllDocuments, spec-version selection, anchors and merge keys on read, and error handling.

Mapping attributes

Shaping members with [PropertyName], [Ignore], and the wider shared attribute family, the naming policies, and the options flags.

Writing converters

Derive YamlConverter<T>, implement Read(ref Utf8YamlReader, Type, YamlSerializerOptions) and Write(Utf8YamlWriter, T, YamlSerializerOptions), and register on options.Converters.

Polymorphic converters

YamlConverterFactory for open-generic families and tagged (discriminated) hierarchies - what the built-ins do for an abstract member without one, reading and writing a discriminator, and the two registration placements.

Serialization callbacks

The four shared IOnSerializing / IOnSerialized / IOnDeserializing / IOnDeserialized lifecycle hooks - defaults that survive omitted keys, post-deserialization validation, derived state on write, and the YAML-specific invocation-order notes.

Built-in converter catalog

Which .NET types map without a user converter, and exactly how each appears in YAML - scalars, enums, collections, dictionaries, objects, and fields.

Suggested reading path

1. Using YAML - the end-to-end walk-through of the serializer and both DOMs.
2. Mapping attributes - declarative shaping covers most customization needs.
3. Writing converters - when a type needs a wire form the defaults do not provide; check the built-in catalog first so you do not rewrite a provisioned one.
4. Polymorphic converters - when a member is declared as a base type or an open generic.
5. Serialization callbacks - lifecycle hooks for defaults, validation, and derived state.

Where to go next

• Serializer options: freezing, caching, and thread safety and Migrating from System.Text.Json - the cross-format guides.
• Bodu serializers guides - the family parent guide hub. The sibling TOML and Bencode hubs cover the twin libraries.
• Bodu.Text.Yaml introduction and core concepts - the format specifics and family vocabulary.
• Text & Serialization guides - how these guides sit alongside the encoding and format guides.
• API reference - Bodu.Text.Yaml.