SharpYaml 3.10.2

SharpYaml

<img align="right" width="256px" height="256px" src="https://raw.githubusercontent.com/xoofx/SharpYaml/master/img/SharpYaml.png">

SharpYaml is a high-performance .NET YAML parser, emitter, and object serializer - NativeAOT ready.

Note: SharpYaml v3 is a major redesign with breaking changes from v2. It uses a System.Text.Json-style API with YamlSerializer, YamlSerializerOptions, and resolver-based metadata (IYamlTypeInfoResolver). See the migration guide for details.

✨ Features

• System.Text.Json-style API: familiar surface with YamlSerializer, YamlSerializerOptions, YamlTypeInfo<T>
• YAML 1.2 Core Schema: spec-compliant parsing with configurable schema (Failsafe, JSON, Core, Extended)
• Source generation: NativeAOT / trimming friendly via YamlSerializerContext with [YamlSerializable] roots
• System.Text.Json attribute interop: reuse [JsonPropertyName], [JsonIgnore], [JsonPropertyOrder], [JsonConstructor]
• Flexible I/O: serialize/deserialize from string, ReadOnlySpan<char>, TextReader, TextWriter
• Rich options: naming policies, indent control, null handling, duplicate key behavior, reference handling, polymorphism
• Low-level access: full scanner, parser, emitter, and syntax tree APIs for advanced YAML processing
• NativeAOT and trimming oriented (IsAotCompatible, IsTrimmable)

📐 Requirements

SharpYaml targets net8.0, net10.0, and netstandard2.0.

• Consuming the NuGet package works on any runtime that supports netstandard2.0 (including .NET Framework) or modern .NET (net8.0+).
• Building SharpYaml from source requires the .NET 10 SDK (C# 14).

📦 Install

dotnet add package SharpYaml

SharpYaml ships the source generator in-package (analyzers/dotnet/cs) - no extra package needed.

🚀 Quick Start

using SharpYaml;

// Serialize
var yaml = YamlSerializer.Serialize(new { Name = "Ada", Age = 37 });

// Deserialize
var person = YamlSerializer.Deserialize<Person>(yaml);

Options

var options = new YamlSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
    WriteIndented = true,
    IndentSize = 4,
    DefaultIgnoreCondition = YamlIgnoreCondition.WhenWritingNull,
};

var yaml = YamlSerializer.Serialize(config, options);
var model = YamlSerializer.Deserialize<MyConfig>(yaml, options);

By default, PropertyNamingPolicy is null, meaning CLR member names are used as-is for YAML mapping keys (same default as System.Text.Json).

Source Generation

Declare a context with [YamlSerializable] roots:

using SharpYaml.Serialization;

[YamlSerializable(typeof(MyConfig))]
internal partial class MyYamlContext : YamlSerializerContext { }

Then consume generated metadata:

var context = MyYamlContext.Default;
var yaml = YamlSerializer.Serialize(config, context.MyConfig);
var roundTrip = YamlSerializer.Deserialize(yaml, context.MyConfig);

Cross-Project Polymorphism

When a base type lives in one assembly and the derived types live in another, you can register mappings where the composition root already references both sides.

Reflection-based serialization can register mappings at runtime:

var options = new YamlSerializerOptions
{
    PolymorphismOptions = new YamlPolymorphismOptions
    {
        DerivedTypeMappings =
        {
            [typeof(Animal)] =
            [
                new YamlDerivedType(typeof(Dog), "dog") { Tag = "!dog" },
                new YamlDerivedType(typeof(Cat), "cat") { Tag = "!cat" },
            ]
        }
    }
};

Source-generated contexts can register the same relationship at compile time:

[YamlSerializable(typeof(Zoo))]
[YamlDerivedTypeMapping(typeof(Animal), typeof(Dog), "dog", Tag = "!dog")]
[YamlDerivedTypeMapping(typeof(Animal), typeof(Cat), "cat", Tag = "!cat")]
internal partial class ZooYamlContext : YamlSerializerContext { }

Context-level mappings are additive to [YamlDerivedType] and JsonDerivedType attributes. Attribute-based entries win when the same derived type or discriminator is registered more than once.

Reflection Control

Reflection fallback can be disabled globally before first serializer use:

AppContext.SetSwitch("SharpYaml.YamlSerializer.IsReflectionEnabledByDefault", false);

When reflection is disabled, POCO/object mapping requires metadata (use generated YamlTypeInfo<T>, the overloads that accept a YamlSerializerContext, or pass MyYamlContext.Default.Options to an options-based overload). Primitive scalars and untyped containers (object, Dictionary<string, object>, List<object>, object[]) still work without reflection.

When publishing with NativeAOT (PublishAot=true), the SharpYaml NuGet package disables reflection-based serialization by default. You can override the default by setting the following MSBuild property in your app project:

<PropertyGroup>
  <SharpYamlIsReflectionEnabledByDefault>true</SharpYamlIsReflectionEnabledByDefault>
</PropertyGroup>

🚀 Benchmarks

In the included benchmarks, SharpYaml is typically ~2x to ~6x faster than YamlDotNet and uses ~2x to ~9x less memory allocations, depending on the scenario (POCO vs generic vs source-generated).

BenchmarkDotNet v0.15.8, Windows 11 (10.0.26200.8655/25H2/2025Update/HudsonValley2)
AMD Ryzen 9 9950X 4.30GHz, 1 CPU, 32 logical and 16 physical cores
.NET SDK 10.0.301
  [Host]     : .NET 10.0.9 (10.0.9, 10.0.926.27113), X64 RyuJIT x86-64-v4
  DefaultJob : .NET 10.0.9 (10.0.9, 10.0.926.27113), X64 RyuJIT x86-64-v4

📖 Documentation

Full documentation is available at https://xoofx.github.io/SharpYaml.

🪪 License

This software is released under the MIT license.

🤗 Author

Alexandre Mutel aka xoofx.