---
title: "Deserialize YAML into an immutable record in C#"
url: https://recursiveai.org/oneyaml/csharp/cookbook/bind-yaml-to-immutable-record/
description: "Bind YAML keys to a C# record’s constructor with OneYaml, and keep the constructor’s optional default when a key is missing from the mapping."
version: "1.2.1"
---

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

[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/bind-yaml-to-immutable-record/bind-yaml-to-immutable-record.zip)

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

```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 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](https://recursiveai.org/oneyaml/csharp/cookbook/bind-yaml-to-immutable-record/bind-yaml-to-immutable-record.zip), 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`.

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

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

## Related recipes

- [Parse YAML into C# classes](https://recursiveai.org/oneyaml/csharp/cookbook/parse-yaml-into-classes/)
- [Report YAML errors with a line and column](https://recursiveai.org/oneyaml/csharp/cookbook/errors-with-line-and-column/)

## 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](https://github.com/recursive-ai-oss/oneyaml-csharp/blob/7818048c4be434333767c47d66176fc626d1da8e/docs/serializer.md#L55-L61) 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](https://github.com/recursive-ai-oss/oneyaml-csharp/blob/7818048c4be434333767c47d66176fc626d1da8e/docs/serializer.md#L48-L50) 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](https://github.com/recursive-ai-oss/oneyaml-csharp/blob/7818048c4be434333767c47d66176fc626d1da8e/tests/OneYaml.Tests/BinderTests.cs#L279-L284) 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`](https://github.com/recursive-ai-oss/oneyaml-csharp/blob/7818048c4be434333767c47d66176fc626d1da8e/docs/serializer.md#L106), as in the variation.
