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 withYamlSerializer,YamlSerializerOptions, and resolver-based metadata (IYamlTypeInfoResolver). See the migration guide for details.
System.Text.Json-style API: familiar surface withYamlSerializer,YamlSerializerOptions,YamlTypeInfo<T>- YAML 1.2 Core Schema: spec-compliant parsing with configurable schema (Failsafe, JSON, Core, Extended)
- Source generation: NativeAOT / trimming friendly via
YamlSerializerContextwith[YamlSerializable]roots System.Text.Jsonattribute 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)
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).
dotnet add package SharpYamlSharpYaml ships the source generator in-package (analyzers/dotnet/cs) - no extra package needed.
using SharpYaml;
// Serialize
var yaml = YamlSerializer.Serialize(new { Name = "Ada", Age = 37 });
// Deserialize
var person = YamlSerializer.Deserialize<Person>(yaml);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).
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);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 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>In the included benchmarks, SharpYaml is typically ~5x to ~29x faster than YamlDotNet and allocates ~9x less memory, depending on the scenario (POCO vs generic vs source-generated). See the benchmark page for the results, the scenarios and the comparison with ShapeShift.Yaml.
Full documentation is available at https://xoofx.github.io/SharpYaml.
This software is released under the MIT license.
Alexandre Mutel aka xoofx.
