1. Home
2. Docs
3. Serialization
4. Converters

Converters allow custom serialization/deserialization for specific CLR types.

Register a converter

You can register converters globally via options:

var options = new YamlSerializerOptions
{
    Converters =
    [
        new MyConverter(),
    ],
};

Attribute-based converters

Use YamlConverterAttribute on a type or member:

using SharpYaml.Serialization;

[YamlConverter(typeof(MyTypeConverter))]
public sealed class MyType
{
}

Converter shape

Converters operate on YamlReader and YamlWriter:

public sealed class MyIntConverter : YamlConverter<int>
{
    public override int Read(YamlReader reader)
    {
        // Read and advance the reader.
        reader.Skip();
        return 123;
    }

    public override void Write(YamlWriter writer, int value)
        => writer.WriteScalar("123");
}

Reader and writer basics

• YamlReader is positioned on a token; converters must consume the current value and advance the reader.
• YamlWriter writes YAML in a streaming manner; converters should write a complete value (scalar/sequence/mapping).

For most custom scenarios, prefer writing scalars (writer.WriteScalar(...)) unless you need to emit complex YAML structures.