Recursive AI

Deserialize YAML into an immutable record in C#

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

Read a YAML mapping into a C# record without adding writable properties.

Terminal
dotnet add package OneYaml

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

C#
using System;
using OneYaml;
var point =
    YamlSerializer.Deserialize<Point>("x: 1")!;
Console.WriteLine($"X={point.X}, Y={point.Y}");
record Point(int X, int Y = 7);

Unzip the example, then dotnet run.

The YAML sets X to 1; the constructor supplies 7 for the omitted Y.

Text
X=1, Y=7

The full program

The download also supplies y: 0 to show that an explicit value wins. A scalar that can’t bind to the declared parameter type throws YamlException.

C#
using System;
using OneYaml;
var point =
    YamlSerializer.Deserialize<Point>("x: 1")!;
Console.WriteLine($"X={point.X}, Y={point.Y}");
var explicitY =
    YamlSerializer.Deserialize<Point>("x: 1\ny: 0")!;
Console.WriteLine($"X={explicitY.X}, Y={explicitY.Y}");
 
record Point(int X, int Y = 7);

dotnet run prints:

Text
X=1, Y=7
X=1, Y=0

Variations

Require x and leave y optional. Put [property: YamlRequired] on the positional parameter to mark the generated X property. This input has only y, so OneYaml reports the missing key.

C#
using System;
using OneYaml;
 
try
{
    YamlSerializer.Deserialize<Point>("y: 0");
}
catch (YamlException error)
{
    Console.WriteLine(error.Message);
}
 
record Point([property: YamlRequired] int X, int Y = 7);
Text
The required key 'x' is missing. (line 1, column 1)

The short answer

Call YamlSerializer.Deserialize<Point> on the mapping. A positional record declares its properties and constructor together. For Point(int X, int Y = 7), x: 1 supplies X, and the binder uses Y’s constructor default because there’s no y key. No attribute or set accessor is needed for this record.

How do YAML keys match the parameters of a C# record constructor?

Use the names of the record’s members as OneYaml writes them. The default naming policy is camel case, which gives x and y for properties X and Y. The default is also case-sensitive, so Y in a file does not match the key y. You can keep names as declared with PropertyNamingPolicy = null, or turn on PropertyNameCaseInsensitive if files vary in capitalization. When an expected value seems to be missing, check the key spelling before changing the record.

The constructor gets the parsed values, not the text as it appeared in the YAML. x: 1 supplies an integer, while x: "1" is a quoted string. The serializer guide notes that a quoted number doesn’t bind to int. Keep quotes for values meant to be strings.

What happens when a YAML key for a constructor argument is missing?

An optional argument keeps its declared default. The full program shows the distinction: omitting y gives 7, but y: 0 gives 0. This is useful when adding optional settings: older files can omit the new key while newer files can still explicitly select zero.

A constructor parameter without a default is not by itself a check that the key was present. The pinned binder example shows that the empty mapping {} produces Point(0, 7): the missing nonoptional integer becomes zero, while the optional one becomes seven. If omission should be an error, mark the property with YamlRequired, as in the variation.

All oneyaml C# recipes