---
title: "oneyaml-csharp"
url: https://recursiveai.org/oneyaml/csharp/docs/overview/
description: "The package README: what OneYaml is, the quick start, where to go next, and the three packages."
version: "1.2.1"
source: https://github.com/recursive-ai-oss/oneyaml-csharp/blob/7818048c4be434333767c47d66176fc626d1da8e/README.md
---
# oneyaml-csharp
**Lossless, comment-preserving editing and a System.Text.Json-style
serializer for YAML 1.2, in one .NET package.** Both run on one parser,
so a typed read and an edit never disagree about what a file means.
Pure C#, correct YAML 1.2 by default; nesting, alias expansion and
integer size are bounded unless you lift the limits.
[](https://www.nuget.org/packages/OneYaml)
[](https://github.com/recursive-ai-oss/oneyaml-csharp/actions/workflows/ci.yml)
[](https://recursiveai.org/oneyaml/csharp/docs/stability/)
[](#license)
How many times faster oneyaml-csharp is than the strongest other .NET
YAML library on each task, on real configuration files (wall-clock
time, log scale, higher is better; a task where oneyaml-csharp is
slower shows as a slower bar):
[Full results, with memory and the method →](https://github.com/recursive-ai-oss/oneyaml-csharp/blob/v1.2.1/docs/performance.md)
## Why oneyaml-csharp
- **Edits that keep your file.** `YamlDocument` changes only what you
touch, in the old value's style; comments and layout elsewhere stay
byte for byte. JSON Patch and Merge Patch apply the same way
([editing](https://recursiveai.org/oneyaml/csharp/docs/editing/), [patches](https://recursiveai.org/oneyaml/csharp/docs/patches/)).
- **A serializer you already know.** Options, naming policies,
converters, polymorphism and the System.Text.Json attributes, with a
source generator in the package for trimmed and native AOT apps
([serializer](https://recursiveai.org/oneyaml/csharp/docs/serializer/)).
- **Correct YAML 1.2 by default.** `yes` is a string and `0755` the
integer 755; YAML 1.1 forms come only from `MergeKeys` or the
compatibility packages. Checked against the full yaml-test-suite,
with every deviation listed ([conformance](https://recursiveai.org/oneyaml/csharp/docs/conformance/)).
- **Safe on outside input.** Depth, alias expansion and integer size
are bounded by default; input size, scalar size and document count
are bounded when you set them, and `YamlLimits.Untrusted` sets them
([limits](https://recursiveai.org/oneyaml/csharp/docs/limits/)). No unsafe code, no dependencies outside
.NET, and fuzzed ([fuzzing](https://github.com/recursive-ai-oss/oneyaml-csharp/blob/7818048c4be434333767c47d66176fc626d1da8e/tests/OneYaml.Fuzz/README.md)).
- **Fast, with the losses shown.** Ahead of every other .NET YAML
library at typed load, generic load, dump, document parse, editing
and writing back an unedited file, through reflection and generated
metadata alike, and level or lower on memory throughout. Not on
every file: writing back some unedited files was slower than
SharpYaml's syntax tree in our run, the generated-metadata column
was slower on a few tiny files, and a few files are level
([every loss](https://recursiveai.org/oneyaml/csharp/docs/performance/#results-at-a-glance)).
[How oneyaml-csharp compares](https://recursiveai.org/oneyaml/csharp/docs/comparison/) with YamlDotNet,
SharpYaml and VYaml, including when one of them is the better choice.
## Install
```sh
dotnet add package OneYaml
```
Moving from YamlDotNet or SharpYaml? A [compatibility package](#packages)
covers the common serializer and model calls; its guide lists what it
leaves out and what differs.
## Quick start
Change two values in a file, keeping the comment, the block scalar and
every other byte as they were; then bind the original text to a record.
```csharp
using OneYaml;
string src = """
# Build settings
script: |
make build
replicas: 2 # the CI job scales this
""";
using var doc = YamlDocument.Parse(src);
doc.Set("/script", "make build\nmake test\n"); // still a block literal
doc.Root["replicas"] = 3; // only the 2 changes
Console.WriteLine(doc);
// # Build settings
// script: |
// make build
// make test
// replicas: 3 # the CI job scales this
var cfg = YamlSerializer.Deserialize(src)!;
Console.WriteLine($"{cfg.Replicas} replicas"); // 2 replicas
record Config(int Replicas, string Script);
```
Keys bind in camel case by default. Read [what an edit keeps, and what
it does not](https://recursiveai.org/oneyaml/csharp/docs/editing/#what-an-edit-keeps-and-what-it-does-not);
for native AOT, use [generated metadata](https://recursiveai.org/oneyaml/csharp/docs/serializer/#source-generation-and-native-aot).
## Where to go
- **Using it:** [serializer](https://recursiveai.org/oneyaml/csharp/docs/serializer/),
[editing](https://recursiveai.org/oneyaml/csharp/docs/editing/), [patches](https://recursiveai.org/oneyaml/csharp/docs/patches/),
[limits](https://recursiveai.org/oneyaml/csharp/docs/limits/), [reader and emitter](https://recursiveai.org/oneyaml/csharp/docs/reader-emitter/).
The API reference is the XML documentation your IDE shows.
- **Migrating:** [from YamlDotNet](https://recursiveai.org/oneyaml/csharp/docs/migrate-yamldotnet/),
[from SharpYaml](https://recursiveai.org/oneyaml/csharp/docs/migrate-sharpyaml/).
- **Choosing a library:** [how oneyaml-csharp compares](https://recursiveai.org/oneyaml/csharp/docs/comparison/),
including where the others win.
- **Evidence:** [benchmark tables](https://recursiveai.org/oneyaml/csharp/docs/performance/#results-at-a-glance)
(the numbers behind the chart, every loss and the method),
[yaml-test-suite conformance](https://recursiveai.org/oneyaml/csharp/docs/conformance/),
[fuzzing](https://github.com/recursive-ai-oss/oneyaml-csharp/blob/7818048c4be434333767c47d66176fc626d1da8e/tests/OneYaml.Fuzz/README.md).
- **What changed, and what stays stable:** [CHANGELOG.md](https://recursiveai.org/oneyaml/csharp/docs/changelog/),
[stability and supported .NET versions](https://recursiveai.org/oneyaml/csharp/docs/stability/).
- **Contributing and security:** [CONTRIBUTING.md](https://github.com/recursive-ai-oss/oneyaml-csharp/blob/7818048c4be434333767c47d66176fc626d1da8e/CONTRIBUTING.md),
[SECURITY.md](https://github.com/recursive-ai-oss/oneyaml-csharp/blob/7818048c4be434333767c47d66176fc626d1da8e/SECURITY.md), [CODE_OF_CONDUCT.md](https://github.com/recursive-ai-oss/oneyaml-csharp/blob/7818048c4be434333767c47d66176fc626d1da8e/CODE_OF_CONDUCT.md).
- **Other languages:**
[oneyaml-go](https://github.com/recursive-ai-oss/oneyaml-go) and
[oneyaml-rust](https://github.com/recursive-ai-oss/oneyaml-rust), all
measured by [oneyaml-kit](https://github.com/recursive-ai-oss/oneyaml-kit).
## Packages
| Package | What it is |
|---|---|
| [`OneYaml`](https://www.nuget.org/packages/OneYaml) | The library: `YamlSerializer`, `YamlDocument`, patches, limits. Start here. |
| [`OneYaml.Compat.YamlDotNet`](https://www.nuget.org/packages/OneYaml.Compat.YamlDotNet) | A subset of YamlDotNet's API on top of `OneYaml`: the serializer builders and the representation model, tested against YamlDotNet 18.1.0. Not covered: static contexts, type inspectors, node deserializers, the scanner and comment events; [what is covered and every difference](https://recursiveai.org/oneyaml/csharp/docs/compat-yamldotnet/). |
| [`OneYaml.Compat.SharpYaml`](https://www.nuget.org/packages/OneYaml.Compat.SharpYaml) | A subset of SharpYaml's API on top of `OneYaml`: the serializer, its options and attributes, tested against SharpYaml 3.14.0. Not covered: custom converters, polymorphism, generated contexts, the `Model` and `Syntax` namespaces; [what is covered and every difference](https://recursiveai.org/oneyaml/csharp/docs/compat-sharpyaml/). |
## License
Licensed under either of [Apache License, Version 2.0](https://github.com/recursive-ai-oss/oneyaml-csharp/tree/7818048c4be434333767c47d66176fc626d1da8e/LICENSE-APACHE) or
[MIT license](https://github.com/recursive-ai-oss/oneyaml-csharp/tree/7818048c4be434333767c47d66176fc626d1da8e/LICENSE-MIT) at your option.
