Recursive AI

Preserve unknown YAML fields in C#

OneYaml is a free, open-source YAML library for .NET from Recursive AI. MIT or Apache-2.0, no native dependencies.

Keep extra plugin settings when you change a known field. This preserves values, not comments or layout.

Terminal
dotnet add package OneYaml

Targets .NET 8 and .NET 10 (used in the download).

C#
using System;
using System.Collections.Generic;
using OneYaml;
 
var plugin =
    YamlSerializer.Deserialize<Plugin>("""
    name: lint
    level: strict
    paths: [src, tests]
    """)!;
plugin.Name = "check";
Console.Write(
    YamlSerializer.Serialize(plugin));
 
class Plugin
{
    public string Name { get; set; } = "";
 
    [YamlExtensionData]
    public Dictionary<string, object?> Extras
        { get; set; } = [];
}

Unzip the example, then dotnet run.

The name changes to check; level and paths stay in the output.

Text
name: check
level: strict
paths:
  - src
  - tests

The full program

The download writes two YAML documents, separated by ---: first with the captured level, then with level changed to warn. A duplicate key in the input is a YamlException, not an extra setting.

C#
using System;
using System.Collections.Generic;
using OneYaml;
 
var plugin =
    YamlSerializer.Deserialize<Plugin>("""
    name: lint
    level: strict
    paths: [src, tests]
    """)!;
plugin.Name = "check";
Console.WriteLine("# After changing the name");
Console.Write(
    YamlSerializer.Serialize(plugin));
 
plugin.Extras["level"] = "warn";
Console.WriteLine("--- # After changing the level");
Console.Write(
    YamlSerializer.Serialize(plugin));
 
class Plugin
{
    public string Name { get; set; } = "";
 
    [YamlExtensionData]
    public Dictionary<string, object?> Extras
        { get; set; } = [];
}

dotnet run prints:

Text
# After changing the name
name: check
level: strict
paths:
  - src
  - tests
--- # After changing the level
name: check
level: warn
paths:
  - src
  - tests

Variations

Drop one extra setting. To remove paths while keeping level, replace the Console.Write in the snippet at the top with:

C#
plugin.Extras.Remove("paths");
Console.Write(
    YamlSerializer.Serialize(plugin));
Text
name: check
level: strict

The short answer

Put [YamlExtensionData] on a Dictionary<string, object?> property. When you call Deserialize<Plugin>, OneYaml binds name to Name and collects the other keys in the dictionary. After you change Name, Serialize writes those keys back at the same mapping level. There’s no extras: wrapper.

How do I deserialize YAML with known and unknown fields?

Give the fields you expect their own typed properties. In the example, Name is a string, so code that uses it doesn’t need to inspect a dictionary. The remaining fields are extension data: keys that belong to the plugin configuration but not to the current C# model. OneYaml also supports IDictionary<string, object?> for the extension member. The extension data guide shows the same arrangement.

Inspect the dictionary when you need one of the extras. The entries aren’t all strings: in this recipe level is a string, but paths is a List<object?> of two strings. Nested mappings become dictionaries. The untyped values guide lists the other possible values, including booleans and integers. If you promote a setting to a typed property later, it becomes a known key when you read the file with the new model.

What happens to unmapped YAML fields when I write the file back?

Without an extension data member, OneYaml skips unmatched keys by default, so a read-and-write can drop settings the application doesn’t know about. The dictionary keeps those settings in the object so they can be written later. The output has level: strict and both paths even though the C# class has no Level or Paths property.

This is a value round trip, not a text round trip. Notice how the inline list [src, tests] comes back as a list on separate lines, and how the known property is written before the extra settings. Use the in-place editing API instead if the task is to edit a hand-maintained file while keeping its comments and layout.

All oneyaml C# recipes