---
title: "Reject unknown YAML properties in C#"
url: https://recursiveai.org/oneyaml/csharp/cookbook/reject-unknown-yaml-properties/
description: "Reject unknown YAML properties in C# with OneYaml. Catch a misspelled config key and report its filename, line, column, and YAML path."
version: "1.2.1"
---

# Reject unknown YAML properties 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/reject-unknown-yaml-properties/reject-unknown-yaml-properties.zip)

Set `UnmappedMemberHandling` to `Disallow` to catch typos like `prot` instead of `port`.

```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 options = new YamlSerializerOptions
{
    UnmappedMemberHandling =
        YamlUnmappedMemberHandling.Disallow,
    SourceName = "app.yaml",
};

try
{
    YamlSerializer.Deserialize<App>(
        "host: api\nprot: 8080\n",
        options);
}
catch (YamlException error)
{
    Console.WriteLine(error.Message);
}

record App(string Host, int Port = 80);
```

Unzip [the example](https://recursiveai.org/oneyaml/csharp/cookbook/reject-unknown-yaml-properties/reject-unknown-yaml-properties.zip), then `dotnet run`.

`dotnet run` prints:

```text
app.yaml: The key 'prot' is not a member of App. (line 2, column 1, path /prot)
```

`Deserialize` throws `YamlException` at the unexpected key. `app.yaml` is a label set by `SourceName`; this example reads the YAML from the string shown in the code, not from disk.

## Variations

**Allow different capitalization, but still reject typos.** Add `PropertyNameCaseInsensitive = true,` to the options and replace the contents of the `try` block with:

```csharp
var app = YamlSerializer
    .Deserialize<App>(
        "HOST: api\nPORT: 8080\n",
        options)!;
Console.WriteLine(app.Port);
```

```text
8080
```

## Related recipes

- [Report YAML errors with line and column](https://recursiveai.org/oneyaml/csharp/cookbook/errors-with-line-and-column/)
- [Require a YAML property](https://recursiveai.org/oneyaml/csharp/cookbook/require-yaml-properties/)
- [Preserve unknown YAML fields](https://recursiveai.org/oneyaml/csharp/cookbook/round-trip-unknown-yaml-fields/)

## The short answer

An *unmapped* key is a YAML key that matches no member of the C# type you’re reading into. `SourceName` adds the filename or path you supply to the error message, so readers know which file to fix. With `Disallow`, the application gets an error instead of an object that silently uses defaults. Catch `YamlException` to show the key, its line and column, and its YAML path.

## What happens to unknown YAML properties during deserialization?

The [default is `Skip`](https://github.com/recursive-ai-oss/oneyaml-csharp/blob/7818048c4be434333767c47d66176fc626d1da8e/docs/serializer.md#L46-L61). In this example `host` matches `Host`, but `prot` matches nothing, so skipping the typo would leave `Port` at `80` rather than set it to `8080`. Strict binding refuses that input. This is not a YAML syntax error: `prot: 8080` is a valid YAML entry. The error depends on which C# type you ask OneYaml to bind it to.

Before treating every unexpected key as a typo, check how your model names its keys. The [default naming policy](https://github.com/recursive-ai-oss/oneyaml-csharp/blob/7818048c4be434333767c47d66176fc626d1da8e/docs/serializer.md#L53-L67) maps `Port` to `port` and matches case. If you change the policy or use `[YamlPropertyName]`, the resulting YAML name is the one that must match. Turning on case-insensitive matching lets `PORT` match `port`; it still won’t make `prot` a match.

## How do I reject extra YAML keys without requiring every property?

`Disallow` checks keys that **are present**. It doesn’t require `port` when there’s no such key in the input. Keep defaults for settings that are genuinely optional. For a setting the user must supply, mark its member with [`[YamlRequired]`](https://github.com/recursive-ai-oss/oneyaml-csharp/blob/7818048c4be434333767c47d66176fc626d1da8e/docs/serializer.md#L98-L106). You can use both controls on the same model: one catches a key you didn’t expect, the other catches a key you did expect but didn’t get.

Use strict binding when the app owns the file format and a typo should stop startup. For a file shared with another version of the app, rejecting every new key means an older reader may refuse a file written by a newer one. If you need to accept and write back extra plugin settings, [capture them as extension data](https://github.com/recursive-ai-oss/oneyaml-csharp/blob/7818048c4be434333767c47d66176fc626d1da8e/docs/serializer.md#L268-L270) instead of using this strict model.
