Table of Contents

Built-in converter catalog

Every type that YamlSerializer handles without a user converter is served by a built-in converter. This page catalogs that set - which .NET types are provisioned, how each appears in YAML on write, and what the read path accepts. Resolution order and the rules for overriding a built-in with your own converter are in Writing converters.

YAML carries the JSON-compatible core scalar kinds - string, integer, float, Boolean, and null - so most everyday .NET types map without any converter at all. The writer emits block-style collections (an empty container falls back to flow [] / {}), and mappings preserve insertion order.

Scalars

.NET type YAML representation (write) Read accepts Notes
string string scalar string The scalar style (plain / quoted / block) is chosen by the writer and recorded on read by ScalarStyle.
char single-character string single-character string A source of any other length raises YamlSerializationException.
Guid string, canonical 36-character form any Guid.Parse-accepted form
Uri string, the original URI text a scalar whose text is an absolute or a relative URI Relative and absolute URIs round-trip. Text that is neither raises YamlSerializationException.
bool Boolean (true / false) Boolean Under SpecVersion = V1_1, the read path also accepts yes / no / on / off and y / n.
sbyte byte short ushort int uint long nint integer scalar integer Checked conversions; a value outside the target type raises YamlSerializationException.
ulong nuint Int128 UInt128 integer scalar, or the invariant decimal text outside the signed 64-bit range integer or string A value the writer's signed 64-bit integer surface cannot hold is emitted as its exact decimal text (quoted only when a leading sign would otherwise resolve it numerically) and converts back exactly on read.
double float scalar float NaN, +∞, and −∞ write as .nan, .inf, and -.inf.
float float scalar float Widens to double on write; narrows on read, where a finite value outside the float range raises YamlSerializationException rather than becoming an infinity. Rounding and underflow are accepted, and .inf, -.inf, and .nan read as float's own values.
decimal quoted string of the exact invariant text float scalar or string Quoted because the exact text would otherwise resolve as a double; the quoting preserves the full decimal precision.
DateTime string, round-trip ("o") ISO-8601 string Read with DateTimeStyles.RoundtripKind. There is no native YAML timestamp type; the value travels as a string scalar.
DateTimeOffset string, round-trip ("o") ISO-8601 string As DateTime, preserving the offset.
TimeSpan string, the invariant TimeSpan form string
null the null scalar (null) null, ~, or the empty scalar A null member is omitted instead when DefaultIgnoreCondition requests it.
enum (any) string, the member name string (a name, as described below) or integer Integers instead of names when WriteEnumsAsStrings = false.
Note

decimal, DateTime, DateTimeOffset, and TimeSpan are not YAML core-schema kinds - there is no native timestamp or high-precision decimal scalar. The serializer carries each as a string (a decimal is additionally quoted so plain resolution does not turn it back into a double), and the read path parses that string with CultureInfo.InvariantCulture. They therefore round-trip exactly through Serialize / Deserialize, but a value typed object reads back as the underlying string, not as the original CLR type.

The YamlNumberHandling option governs the integer/float boundary on read: Strict (the default) rejects a non-integral or out-of-range float bound to an integer target, while AllowFloatToInteger truncates an integer-valued float toward zero. A plain integer scalar binds to a floating-point target under either policy. Integer scalars are resolved across the YAML radix forms - decimal, hexadecimal (0x), and the 0o octal prefix (plus YAML 1.1's leading-zero octal under SpecVersion = V1_1) - so 0xFF, 0o17, and 255 all bind to the same int.

Structural and document-model types

.NET type YAML representation Notes
arrays, List<T>, IEnumerable<T> and its interfaces, sets, and concrete collections with a parameterless constructor and Add sequence Block-style on write; an empty collection writes as flow []. On read the elements are bound into a List<T> and copied into the requested concrete type.
IDictionary<TKey,TValue> / IReadOnlyDictionary<TKey,TValue> and concrete dictionaries mapping Written in insertion order. Keys are stringified in invariant text, and enum keys by name, as described under Enums; on read a non-string key type is parsed back (enum keys by name, other keys via Convert.ChangeType). Mapping keys resolve to unique scalar strings (the Bodu YAML Core Tree Profile) - a duplicate stringified key on write raises YamlSerializationException.
plain classes and structs mapping The catch-all object converter, consulted last; properties first (reflection order), then public fields when IncludeFields is set. Read requires a public parameterless constructor and sets each writable member. Delegates, reflection types (Type and the other MemberInfo types) and pointers are not plain objects: without a converter of your own, a member of one fails with NotSupportedException naming its type.
object-typed members the runtime type's form on write On read, an object target binds to a loosely-typed graph: a Dictionary<string, object?> for a mapping, a List<object?> for a sequence, and bool / long / double / string / null for scalars - not a YamlElement.
Nullable<T> the underlying value, or the null scalar A null scalar binds to null; otherwise the value binds as T.
YamlNode (and YamlObject / YamlArray / YamlValue) the node's own kind Mutable DOM bridge: Deserialize<YamlNode> materializes the value as a node tree (aliases and merge keys already resolved), and a node - standalone or as a member - writes its own kind.
YamlElement the element's own kind Read produces an element view backed by an internal document that shares the reader's row store - no disposal needed.
YamlDocument the document's root A deserialized document shares the reader's immutable row store; disposal is optional.

Fields

Properties map by default. Public fields participate when IncludeFields is true, following the same naming-policy, [PropertyName], and [Ignore] rules as properties:

public sealed class Counter
{
    public int Total { get; set; }
    public int Retries;   // included when IncludeFields is true
}

var options = new YamlSerializerOptions { IncludeFields = true };
string yaml = YamlSerializer.Serialize(new Counter { Total = 3, Retries = 1 }, options);
Total: 3
Retries: 1

Enums

By default an enum is written as its member-name string and read back by name (or as an integer). Set WriteEnumsAsStrings to false to write the underlying integer instead; a ulong-based value above long.MaxValue, beyond the writer's signed 64-bit integers, is written as its plain text, as a ulong member is:

public enum Status { Active, OnHold }

string asString = YamlSerializer.Serialize(new { State = Status.OnHold });
// State: OnHold

var asInt = new YamlSerializerOptions { WriteEnumsAsStrings = false };
string asInteger = YamlSerializer.Serialize(new { State = Status.OnHold }, asInt);
// State: 1

On read an enum binds from a name, as described below, or from an integer scalar within the range of its underlying type, regardless of WriteEnumsAsStrings - the flag affects only the write side. An integer outside that range raises YamlSerializationException with the scalar's line, column and path rather than being narrowed into the type, so Level: 300 never binds a byte-based enum as 44; an integer inside the range binds whether or not it names a member. Individual members rename on the wire with the shared StringEnumMemberNameAttribute, honored by the default handling and by the public enum converters:

  • YamlStringEnumConverter / YamlStringEnumConverter<TEnum> - member-name strings with an optional naming policy and an integers-on-read flag; register on the options for every enum, or reference the generic form from a [Converter(...)] attribute. Like System.Text.Json's JsonStringEnumConverter, the converter writes names whatever WriteEnumsAsStrings says, and with the flag off it reads names only, as that converter does from .NET 9: it rejects an integer scalar, and any other scalar that is not a member's wire name and whose text has an integer in any of its comma-separated parts (an optional sign and the digits 0 to 9, ignoring white space around them), such as "2", !!str 2, a plain integer beyond the 64-bit range, or Read, 2, with YamlSerializationException at the scalar. A member renamed with [StringEnumMemberName("1")] still reads from the string "1", because the wire names are matched first. On write it refuses a value that is neither a member nor a combination of defined flags, such as (Status)99 or a flags value with an undefined bit, and raises YamlSerializationException rather than writing the decimal text it would reject on read.
  • YamlNumberEnumConverter<TEnum> - the underlying numeric value as a YAML integer, regardless of WriteEnumsAsStrings. A ulong-based value above long.MaxValue is written as its plain text, as a ulong member is, and YAML resolves such a plain integer as a string, which the converter reads back up to ulong.MaxValue, as a ulong member does; a quoted or tagged string is rejected.

Names are matched as System.Text.Json's JsonStringEnumConverter matches them, by the default handling and by the string-enum converter alike. A member's wire name, from [StringEnumMemberName] or the converter's naming policy, binds only in its own case. The CLR name of a member that [StringEnumMemberName] does not rename also binds, in any case, but a renamed member's CLR name does not: with [StringEnumMemberName("on")] on Enabled, on binds, and ON, Enabled and enabled do not. A combination of flags is written as the comma-separated wire names of its flags, in the order Enum.ToString lists them, so under NamingPolicy.SnakeCaseLower CanRead | CanExecute is can_read, can_execute. It is read from such a list in any order, each name trimmed of white space, with a trailing comma tolerated but no empty name anywhere else. A list holds names only: an integer binds, where integers are allowed, only as the whole scalar, so 1, 4 is rejected. A float scalar never binds, even an integral one such as 2.0, whether integers are allowed or not, as JsonStringEnumConverter never binds a number that is not an integer.

var options = new YamlSerializerOptions();
options.Converters.Add(new YamlStringEnumConverter(NamingPolicy.SnakeCaseLower, allowIntegerValues: false));

// Status.OnHold now serializes as on_hold everywhere.

An enum used as a dictionary key follows the same names, as System.Text.Json's enum converter reads and writes a property name. A key is written by its wire name, a combination of flags by its flags' wire names, and any other value as its decimal text, whatever the rule for integer values and whatever WriteEnumsAsStrings says, so with [StringEnumMemberName("on")] on Enabled a Dictionary<Toggle, int> writes the key on, reads it back, and rejects Enabled with YamlSerializationException. Where a YamlStringEnumConverter handles the key type, keys also follow its naming policy and its rule for integer values, so with allowIntegerValues: false the key 1 is rejected. Otherwise, under the default handling or YamlNumberEnumConverter<TEnum>, keys are written by name with no naming policy, and integer text binds.

What YAML does not need a decision for

Unlike TOML, YAML has no decimal-handling or byte[]-handling option: decimal always travels as quoted exact text (above), and a byte[] is treated as an ordinary sequence of byte elements rather than a single encoded scalar. Anything outside the provisioned set - a value type rendered as one scalar, a type with a bespoke mapping shape, or a base64 byte[] - is the job of a custom converter.

Where to go next