Guidance for handling Null vs Undefined in .NET JSON

[fern-support]

The Problem

We've been building HTTP SDKs and OpenAPI clients in C#, and we've been running into this issue with representing three distinct states for a field:

1. Undefined: Field not provided (e.g., PATCH request - don't update this field)
2. Null: Field explicitly set to null (e.g., PATCH request - clear this field)
3. Value: Field set to a specific value (e.g., PATCH request - update to this value)

The problem is that C#'s nullable types (string?, int?) can only represent two states: null or value. There's no way to distinguish between "not provided" and "explicitly set to null."

Example

Let's say you have a PATCH endpoint for updating a user profile:

PATCH /users/123
{
  "name": "Alice",        // Update name to "Alice"
  "email": null,          // Clear email (set to null)
  // age not present      // Don't touch age (leave unchanged)
}

With standard C# types, you can't express this:

• string? Email = null - Does this mean "clear it" or "not provided"?
• There's no way to tell if the user omitted a field vs explicitly sent null

What I've Built So Far

I ended up implementing an Optional<T> type that wraps nullable types to give us that third state:

public readonly struct Optional<T> : IOptional, IEquatable<Optional<T>>
{
    public static Optional<T> Undefined { get; }
    public static Optional<T> Of(T value) { }

    public bool IsDefined { get; }
    public bool IsUndefined { get; }
    public T Value { get; }
}

How It Works

Here's what using it looks like:

public class UpdateUserRequest
{
    // null => null, or value => value
    [Nullable]
    public string? Description { get; set; }

    // Optional, nullable - can be undefined => undefined, null => null, or value => null
    [Optional, Nullable]
    public Optional<string?> Email { get; set; } = Optional<string?>.Undefined;

    // null => undefined, value => value
    [Optional]
    public string? Name { get; set; }
}

// Usage
var request = new UpdateUserRequest
{
    Name = "Alice",                        // Update name
    Email = Optional<string?>.Of(null),    // Clear email (explicit null)
    // Description omitted                 // Don't touch description
};

Serialization Behavior

Quick reference for how different combinations serialize:

Property Type	Value	JSON Behavior
string? Field	null	Omitted (JsonIgnoreCondition.WhenWritingNull)
[Nullable] string? Field	null	Included as null
[Nullable] string? Field	Of("text")	Included as "text"
[Optional] string? Field	null	Omitted
[Optional] string? Field	Of("text")	Included as "text"
[Optional] Optional<string> Field	Undefined	Omitted
[Optional] Optional<string> Field	Of("text")	Included as "text"
[Optional, Nullable] Optional<string?> Field	Undefined	Omitted
[Optional, Nullable] Optional<string?> Field	Of(null)	Included as null
[Optional, Nullable] Optional<string?> Field	Of("text")	Included as "text"

What's in the Repo

The implementation includes:

1. Core Type: Optional<T> struct with IEquatable support
2. JSON Serialization: Custom JsonConverter and JsonTypeInfoResolver using reflection to check [Optional] and [Nullable] attributes
3. Testing Support: NUnit extensions for comparing Optional<T> values in assertions
4. Complete Test Suite: 20+ tests covering all serialization/deserialization scenarios

Key files in this repository:

• Optional.cs - Core implementation with IOptional interface
• OpenApiSerialization.cs - JSON serialization with attribute-based modifiers
• OptionalAttribute.cs & NullableAttribute.cs - Attribute markers
• OpenApiSerializationTests.cs - Comprehensive test coverage
• OptionalComparerExtensions.cs - NUnit test helpers

Questions

I'm looking for guidance on whether this is the right approach:

1. Is there an existing .NET pattern I should be using instead?

• Are there plans to add first-class support for "undefined vs null" in future C# versions?
• Should I be using a different approach with System.Text.Json?
• Are there existing BCL types or patterns that address this?

2. JSON serialization - am I doing this right?

• Is using JsonTypeInfoResolver with reflection on custom attributes reasonable?
• Should I be leveraging different System.Text.Json features?
• Any performance implications I should be aware of?

3. API design - the Optional<T?> question

I chose to separate concerns:

• Optional<T> = "Is the field present in the request?"
• T? = "Can the field value be null?"

This leads to Optional<T?> for optional nullable fields. Is this the right approach, or should I build null handling into Optional<T> itself (like having an Optional<T>.Null state)?

---

Full working implementation with tests is in this repo. All tests pass on .NET 8.0, .NET 10.0, and .NET Framework 4.6.2.

Would really appreciate any guidance on the recommended .NET approach here!

[MihuBot]

I'm a bot. Here are possible related and/or duplicate issues (I may be wrong):

• Implicit vs Explicit Null (aka Null vs Not-Set) - JSON and WebAPI Related #53868
• [System.Text.Json] About difference between property with null and does not exists #29468

[dotnet-policy-service[bot]]

Tagging subscribers to this area: @dotnet/area-system-text-json
See info in area-owners.md if you want to be subscribed.

[Swimburger]

I didn't notice I was posting under the Fern support account. I'm the author of this issue.

[eiriktsarpalis]

Is there an existing .NET pattern I should be using instead?

In my opinion, the best way to encode the presence or absence of a property within JSON is to use one of the JSON DOM types. Using a POCO is bound to lose some fidelity since there is no native concept of a property being absent. If I absolutely needed to I would probably go for a wrapper type like the one you described, although I think the [Nullable] and [Optional] attributes are adding more complexity than necessary and I would just got with a converter based approach like so:

using System.Text.Json;
using System.Text.Json.Serialization;

string json = JsonSerializer.Serialize(new MyPoco() { Null = null, Defined = "defined" });
Console.WriteLine(json);
var result = JsonSerializer.Deserialize<MyPoco>(json);
Console.WriteLine(result.Undefined.HasValue);
Console.WriteLine(result.Null.HasValue);

public class MyPoco
{
    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)]
    public Option<string?> Undefined { get; set; }
    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)]
    public Option<string?> Null { get; set; }
    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)]
    public Option<string?> Defined { get; set; }
}

[JsonConverter(typeof(OptionConverterFactory))]
public readonly struct Option<T>
{
    public bool HasValue { get; }
    public T Value { get; }

    public Option(T value)
    {
        HasValue = true;
        Value = value;
    }

    public static implicit operator Option<T>(T value) => new(value);
}

public sealed class OptionConverterFactory : JsonConverterFactory
{
    public override bool CanConvert(Type typeToConvert) =>
        typeToConvert.IsGenericType &&
        typeToConvert.GetGenericTypeDefinition() == typeof(Option<>);

    public override JsonConverter? CreateConverter(Type typeToConvert, JsonSerializerOptions options)
    {
        Type valueType = typeToConvert.GetGenericArguments()[0];
        Type converterType = typeof(OptionConverter<>).MakeGenericType(valueType);
        return (JsonConverter?)Activator.CreateInstance(converterType);
    }
}

public sealed class OptionConverter<T> : JsonConverter<Option<T>>
{
    public override bool HandleNull => true;

    public override Option<T> Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        return new(JsonSerializer.Deserialize<T>(ref reader, options)!);
    }

    public override void Write(Utf8JsonWriter writer, Option<T> value, JsonSerializerOptions options)
    {
        if (!value.HasValue)
        {
            // If absolutely necessary, write undefined values as null although
            // this should be gated using JsonIgnoreCondition.WhenWritingDefault
            writer.WriteNullValue();
            return;
        }

        JsonSerializer.Serialize(writer, value.Value, options);
    }
}

[Danielku15]

We use a pattern similar to the OData deltas: https://github.com/OData/AspNetCoreOData/blob/main/src/Microsoft.AspNetCore.OData/Deltas/DeltaOfT.cs

The specialized JSON serializer for the deltas store the the information in a key-value property bag. Then you can either obtain the values/nested values via the getters (by name, by expression, looping through them) or you apply the modifications directly to a given object.

It's a bit tricky to get everything aligned (JSON serialization, OpenAPI docs with correct optional/required field declaratiosn etc.) but once you got the main things in place, the approach is really nice for strict RESTful services. You can then simply accept a Delta<TResource> on your PATCH methods.

[Swimburger]

That sounds great. Is the UX similar to updating the underlying TResource instance?