[API Proposal]: System.Text.Json: Add JsonSerializerOptions.DateTimeUnspecifiedKindHandling property

[wdnijdam]

Background and motivation

Currently, System.Text.Json does not provide a way to control how DateTimeKind.Unspecified values are handled during serialization and deserialization.
This can lead to inconsistent behavior across systems, especially when working with APIs that require all dates to be UTC or Local.

Problem
Serialization: When DateTime.Kind == Unspecified, the serializer writes the value without a timezone offset, which can be misinterpreted by consumers.
Deserialization: When parsing a date string without an offset or Z suffix, the resulting DateTime has Kind == Unspecified, which can cause ambiguity and bugs in time-sensitive applications.
There is no built-in option to:
Force Unspecified to be treated as UTC or Local.
Automatically assign a Kind during deserialization.

API Proposal

namespace System.Text.Json
{
    public enum DateTimeUnspecifiedKindHandling
    {
        AssumeUtc,  // Treat as UTC
        AssumeLocal // Treat as Local (default)
    }

    public partial class JsonSerializerOptions
    {
        public DateTimeUnspecifiedKindHandling DateTimeUnspecifiedKindHandling { get; set; }
    }
}

API Usage

var options = new JsonSerializerOptions
{
    DateTimeUnspecifiedKindHandling = DateTimeUnspecifiedKindHandling.AssumeUtc
};

var json = JsonSerializer.Serialize(new { Date = new DateTime(2024, 01, 01) }, options);
// Output: {"Date":"2024-01-01T00:00:00Z"}

var obj = JsonSerializer.Deserialize<MyDto>("{\"Date\":\"2024-01-01T00:00:00\"}", options);
// obj.Date.Kind == DateTimeKind.Utc

Alternative Designs

Workarounds Today
A custom JsonConverter can be implemented to enforce this behavior, but:

It must be manually registered.
It adds boilerplate for every project.
It’s easy to forget to apply it, leading to subtle bugs.
Rationale
Improves interoperability with APIs that require consistent date kinds.
Reduces ambiguity and potential time zone bugs.
Aligns with similar options in other serializers (e.g., Newtonsoft.Json’s DateTimeZoneHandling).
Alternatives
Continue using custom converters (less discoverable, more error-prone).
Post-process DateTime values after deserialization (inefficient).
Additional Context
This feature would be especially useful in:

Distributed systems where UTC is the standard.
Applications that must comply with strict date/time handling rules.
Migration scenarios from Newtonsoft.Json where DateTimeZoneHandling is already in use.
If you want, I can also add a working prototype implementation so the .NET team can see exactly how it could be integrated into System.Text.Json.

Risks

No response

[dotnet-policy-service]

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

[MihuBot]

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

• System.Text.Json default DateTimeZoneHandling #1566

[huoyaoyuan]

DateTimeOffset should be used instead of DateTime. It handles time zone correctly, and carries enough information corresponds to ISO8601.

[wdnijdam]

The issue is that we deal with external sites created in other technologies. These produce date-time values WITHOUT the timezone information (not ending with Z or +01:00). Thus, we must tell our application how to treat these timestamps while deserializing the json. The default behavior is to use the local time zone from the machine. We need a feature to override the default to UTC. Also when using the local time zone the local machine time zone may not be the time zone the source data is in.

It is clear that when we communicate between .net application to allways use the full information as produced by datetimeoffset.

Also the best solution would be to always transfer the time zone information. We experience a similar issue with DateOnly submission where no time zone is included.

[wdnijdam]

This item is indeed a duplicate of #1566