OfficeIMO.Yaml

Edit configuration files without rewriting them

OfficeIMO.Yaml loads a YAML file into a document you can edit and saves only what changed. Comments, blank lines, quoting, indentation, key order and spellings such as TRUE or 0x1F stay exactly as they were everywhere else, so a pull request that changes one value shows one changed line.

using OfficeIMO.Yaml;

using YamlDocument document = YamlDocument.Load("deployment.yaml");
document.Set("spec.replicas", 3);
document.Set("spec.template.spec.containers[0].image", "nginx:1.27");
document.Save();   // only the two values change in the file

Merge overlays the way Helm does

Layer per-environment values over a base file. The result is a minimal diff of the base, and a report lists every added, replaced and removed path.

using var values = YamlDocument.Load("values.yaml");
using var production = YamlDocument.Load("values.prod.yaml");
YamlMergeReport report = values.Merge(production, new YamlMergeOptions { NullRemovesKey = true });
values.Save("values.merged.yaml");

Serialize objects, including in NativeAOT

YamlSerializer follows the System.Text.Json API. A source generator ships in the package, so trimmed and NativeAOT applications get generated metadata instead of reflection.

[YamlSerializable(typeof(AppConfig))]
internal partial class AppYamlContext : YamlSerializerContext { }

AppConfig? config = YamlSerializer.Deserialize(File.ReadAllText("app.yaml"), AppYamlContext.Default.AppConfig);
string yaml = YamlSerializer.Serialize(config!, AppYamlContext.Default.AppConfig);

Features

• Lossless document model: unchanged files save byte for byte, including encoding and byte-order mark.
• YAML 1.2.2: checked against the yaml-test-suite, with Failsafe, JSON, Core and YAML 1.1 schemas, anchors, aliases, merge keys, tags and multi-document streams.
• Real-world files: reads the indentation and merge-key forms that CI, Compose and Helm files use, with a positioned warning for each; Strict applies the specification's exact rules.
• Safe output: new strings are quoted wherever a YAML 1.1 reader such as PyYAML would read them as something else, so yes, on and 012 stay strings.
• Streaming reader and writer: YamlReader allocates nothing per event, and YamlWriter output is deterministic.
• Bounded input: limits on depth, nodes, alias expansion, scalar size and input size, with UntrustedDefaults for files from outside.
• No third-party parser: depends only on OfficeIMO.Core.

Compatibility

Related guides