oneyaml C# docs
Everything about oneyaml for C#: getting started, the serializer, editing, patches, limits, moving from YamlDotNet and SharpYaml, how it compares, and the reference.
Start
Guides
SerializerYamlSerializer reads YAML into .NET types and writes .NET values as YAML. Its shape is the shape of System.Text.Json: static Serialize and Deserialize methods, an immutable options object, naming policies, converters, attributes, and a source generator for trimmed and native…EditingYamlDocument holds a whole YAML stream with its text, comments and layout. Writing it back unedited gives the input byte for byte, and an edit changes only the text of the value it touches. Use it for files that people also edit by hand, where the diff of a change must hold…PatchesYamlDocument applies JSON Patch operations (RFC 6902) with YAML value equality for test, and JSON Merge Patch (RFC 7396), to a YAML file and keeps its layout: every value the patch does not touch keeps its text, comments included, and every value it writes is placed and…LimitsYAML can describe far more work than its size suggests: an alias can stand for a whole subtree, so a few hundred bytes can expand to a billion values, and deep nesting can exhaust the stack. YamlLimits bounds that work. Exceeding a limit throws a YamlException with category…Reader and emitterUtf8YamlReader and Utf8YamlEmitter are the token-level types under the serializer, in the shape of Utf8JsonReader and Utf8JsonWriter. You meet the reader inside a custom YamlConverter, and you can use the emitter on its own to write YAML token by token.
Migrating
From YamlDotNetThere are two ways to move code written against YamlDotNet:From SharpYamlSharpYaml 3 and OneYaml share the System.Text.Json shape, so most code moves with few changes. There are two ways:OneYaml.Compat.YamlDotNetThe package covers a subset of YamlDotNet's API: the common paths through the serializer builders (SerializerBuilder, DeserializerBuilder, naming conventions, IYamlTypeConverter, the attributes) and the representation model (YamlStream and its nodes), with the parser events…OneYaml.Compat.SharpYamlThe package covers a subset of SharpYaml's API: the common serializer paths (YamlSerializer, YamlSerializerOptions, the attributes and the exceptions), listed in What is covered. It reproduces the documented behaviour of SharpYaml for those paths, never its defects. It is…
Choosing
ComparisonHow oneyaml-csharp compares with the .NET YAML libraries it is most often weighed against: YamlDotNet, SharpYaml and VYaml.PerformanceHow oneyaml-csharp compares with the other .NET YAML libraries on speed and memory. Every task runs on the same inputs for every library, through the oneyaml benchmark kit, oneyaml-kit. The tables and charts below are generated from the kit's result file; none of the numbers…
Reference
ConformanceWhat oneyaml-csharp is measured against, the latest results, and every case it is known not to pass.StabilityWhat a release of oneyaml-csharp promises, and which .NET versions it supports. This is the only place this policy is stated; other pages link here.ChangelogAll notable changes are listed here, newest first. The format follows Keep a Changelog, and versions follow Semantic Versioning. A change that can break your code is marked Breaking and says what to write instead. What a release promises, and the supported .NET versions, are…