JsonGuard 0.1.0

JsonGuard

An efficient, allocation free JSON validation library for System.Text.Json, based on Source Generation.

Motivation

By default, System.Text.Json allows you to validate required properties using the [JsonRequired] attribute or the required keyword. However, these built-in methods introduce significant performance overhead, especially in Source-Generated and Native AOT scenarios.

JsonGuard circumvents this overhead by using a Roslyn Source Generator to implement IJsonOnDeserialized. Instead of evaluating requirements property-by-property during the deserialization pipeline, JsonGuard does a single, highly optimized null-check pass at the very end of object construction.

How it works

When you apply the [JsonGuard] attribute to a partial class, the source generator creates an implementation of IJsonOnDeserialized. This generated code runs immediately after deserialization completes, performing a highly optimized check to ensure no non-nullable reference type properties are null. If any are, a JsonException is thrown with the missing property information. Furthermore, because it relies on the standard IJsonOnDeserialized interface, System.Text.Json automatically triggers this validation regardless of whether the object is the root payload or deeply nested within the JSON document.

Example

Let's say you have the following class:

[JsonGuard]
public partial class User
{
    public string Name { get; set; }

    public string? Nickname { get; set; }

    public int Age { get; set; }

    public string Email { get; set; }
}

The generated code will effectively do the following:

public partial class User : IJsonOnDeserialized
{
    void IJsonOnDeserialized.OnDeserialized()
    {
        if (Name is null)
            ThrowHelper.Throw(nameof(Name));

        if (Email is null)
            ThrowHelper.Throw(nameof(Email));
    }
}

Additionally, JsonGuard suppresses nullability warnings for validated properties, so you won't get any warnings about potential null references for Name and Email.

Compatibility

• C#: 11+
• System.Text.Json: 6.0.0+
• .NET: Any that supports System.Text.Json 6.0.0+, including .NET 5.0+, .NET Core 2.0+, .NET Framework 4.6.1+, and .NET Standard 2.0+

Installation

Install the package via NuGet:

dotnet add package JsonGuard

Features

• Supports both JIT and Native AOT compilation.
• Works with both reflection-based and source-generated serialization.
• Skips nullable properties and value-type properties.
• Automatically suppresses nullability warnings for validated properties.
• Supports deeply nested objects (validation runs at any depth in the JSON payload).
• Supports complex type hierarchies (including inherited properties).
• Supports classes, structs, records, and record structs.
• Supports virtual and abstract properties without duplicating the validation logic.
• Supports [JsonConstructor] and init properties.
• Respects [JsonIgnore], automatically skipping ignored properties.

Benchmarks

The source code of benchmarks can be found in the JsonGuard.Benchmarks directory.

The benchmarks evaluate performance across two runtimes (JIT and Native AOT) using two distinct workloads:

• Complex Scenario: A large JSON document (a large Discord guild payload).
• Simple Scenario: A small JSON document (basic user information).

JIT

Host Environment

BenchmarkDotNet v0.15.8, Linux Ubuntu 24.04.4 LTS (Noble Numbat)
12th Gen Intel Core i9-12900K 3.19GHz, 1 CPU, 24 logical and 12 physical cores
.NET SDK 10.0.401
  [Host]    : .NET 10.0.12 (10.0.12, 10.0.1226.42308), X64 RyuJIT x86-64-v3
  .NET 10.0 : .NET 10.0.12 (10.0.12, 10.0.1226.42308), X64 RyuJIT x86-64-v3

Job=.NET 10.0  Runtime=.NET 10.0  Toolchain=net10.0

Complex, reflection based

Complex, source generated

Simple, reflection based

Simple, source generated

Native AOT

Host Environment

BenchmarkDotNet v0.15.8, Linux Ubuntu 24.04.4 LTS (Noble Numbat)
12th Gen Intel Core i9-12900K 3.19GHz, 1 CPU, 24 logical and 12 physical cores
.NET SDK 10.0.401
  [Host]         : .NET 10.0.12 (10.0.12, 10.0.1226.42308), X64 RyuJIT x86-64-v3
  NativeAOT 10.0 : .NET 10.0.12, X64 NativeAOT x86-64-v3

Job=NativeAOT 10.0  Runtime=NativeAOT 10.0  Toolchain=Latest ILCompiler

Complex, source generated

Simple, source generated

What it is not

Unlike [JsonRequired] and the required keyword, JsonGuard does not intercept the deserialization pipeline to check if a property was physically present in the JSON payload. Instead, it runs after deserialization is complete to verify that the final state of the object honors your C# nullability annotations.

For example, if an integer property is missing from the JSON, it defaults to 0 and JsonGuard ignores it (as it is a value type). However, if a non-nullable string property is missing, it defaults to null. JsonGuard detects this invalid state and throws an exception.

License

This project is released under the MIT License.