---
title: "Preserve unknown YAML fields in C#"
url: https://recursiveai.org/oneyaml/csharp/cookbook/round-trip-unknown-yaml-fields/
description: "Use YamlExtensionData to keep unknown plugin settings when reading and rewriting YAML in C#. Keep the extra values without keeping comments or layout."
version: "1.2.1"
---

# 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.

[NuGet](https://www.nuget.org/packages/OneYaml) · [GitHub](https://github.com/recursive-ai-oss/oneyaml-csharp) · [Docs](https://recursiveai.org/oneyaml/csharp/docs/) · [Download example (.zip)](https://recursiveai.org/oneyaml/csharp/cookbook/round-trip-unknown-yaml-fields/round-trip-unknown-yaml-fields.zip)

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

```shell
dotnet add package OneYaml
```

Targets .NET 8 and [.NET 10](https://dotnet.microsoft.com/download/dotnet/10.0) (used in the download).

```csharp
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](https://recursiveai.org/oneyaml/csharp/cookbook/round-trip-unknown-yaml-fields/round-trip-unknown-yaml-fields.zip), 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.

```csharp
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:

```csharp
plugin.Extras.Remove("paths");
Console.Write(
    YamlSerializer.Serialize(plugin));
```

```text
name: check
level: strict
```


## Related recipes

- [Edit YAML and keep comments](https://recursiveai.org/oneyaml/csharp/cookbook/edit-yaml-keep-comments/)
- [Read YAML without a class](https://recursiveai.org/oneyaml/csharp/cookbook/read-yaml-without-a-class/)

## 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](https://github.com/recursive-ai-oss/oneyaml-csharp/blob/7818048c4be434333767c47d66176fc626d1da8e/docs/serializer.md#L268-L295) 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](https://github.com/recursive-ai-oss/oneyaml-csharp/blob/7818048c4be434333767c47d66176fc626d1da8e/docs/serializer.md#L297-L299) 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](https://github.com/recursive-ai-oss/oneyaml-csharp/blob/7818048c4be434333767c47d66176fc626d1da8e/docs/serializer.md#L49-L61), 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](https://recursiveai.org/oneyaml/csharp/docs/editing/) instead if the task is to edit a hand-maintained file while keeping its comments and layout.
