Add support for Date/TimeOnly to STJ

[devsko]

Background and Motivation

The recently added types DateOnly and TimeOnly should be fully supported by System.Text.Json. Even when it's possible to make them serializable via a built-in or custom converter, adding support to Utf8JsonReader/Writer brings them on par with other types like DateTimeOffset.

Proposed API

namespace System.Text.Json
{
    public ref partial struct Utf8JsonReader
    {
+        public DateOnly GetDateOnly();
+        public TimeOnly GetTimeOnly();
+        public bool TryGetDateOnly(out DateOnly value);
+        public bool TryGetTimeOnly(out TimeOnly value);
    }

    public sealed partial class Utf8JsonWriter
    {
+        public void WriteString(JsonEncodedText propertyName, DateOnly value);
+        public void WriteString(JsonEncodedText propertyName, TimeOnly value);
+        public void WriteString(string propertyName, DateOnly value);
+        public void WriteString(string propertyName, TimeOnly value);
+        public void WriteString(ReadOnlySpan<char> propertyName, DateOnly value);
+        public void WriteString(ReadOnlySpan<char> propertyName, TimeOnly value);
+        public void WriteString(ReadOnlySpan<byte> utf8PropertyName, DateOnly value);
+        public void WriteString(ReadOnlySpan<byte> utf8PropertyName, TimeOnly value);
+        public void WriteStringValue(DateOnly value);
+        public void WriteStringValue(TimeOnly value);
    }

    public readonly partial struct JsonElement
    {
+        public DateOnly GetDateOnly();
+        public TimeOnly GetTimeOnly();
+        public bool TryGetDateOnly(out DateOnly value)
+        public bool TryGetTimeOnly(out TimeOnly value)
    }
}

namespace System.Text.Json.Node
{
    public abstract partial class JsonNode
    {
+        public static explicit operator DateOnly(JsonNode value);
+        public static explicit operator TimeOnly(JsonNode value);
+        public static explicit operator DateOnly?(JsonNode? value);
+        public static explicit operator TimeOnly?(JsonNode? value);
+        public static implicit operator JsonNode(DateOnly value);
+        public static implicit operator JsonNode(TimeOnly value);
+        public static implicit operator JsonNode?(DateOnly? value);
+        public static implicit operator JsonNode?(TimeOnly? value);
    }
}

namespace System.Text.Json.Serialization.Metadata
{
    public static partial class JsonMetadataServices
    {
+        public static JsonConverter<DateOnly> DateOnlyConverter { get; }
+        public static JsonConverter<TimeOnly> TimeOnlyConverter { get; }
    }
}

namespace System.Buffers.Text
{
    public static partial class Utf8Formatter
    {
+        public static bool TryFormat(DateOnly value, Span<byte> destination, out int bytesWritten, StandardFormat format = default);
+        public static bool TryFormat(TimeOnly value, Span<byte> destination, out int bytesWritten, StandardFormat format = default);
    }
    public static partial class Utf8Parser
    {
+        public static bool TryParse(ReadOnlySpan<byte> source, out DateOnly value, out int bytesConsumed, char standardFormat = default);
+        public static bool TryParse(ReadOnlySpan<byte> source, out TimeOnly value, out int bytesConsumed, char standardFormat = default);
    }
}

Usage Examples

    var value = reader.GetDateOnly();
    writer.WriteStringValue(value);

Alternative Designs

As mentioned it would be possible to just add serialization converters for these types without supporting the Utf8Reader/Writer scenarios.

Risks

Obviously this API cannot be added to platforms prior .NET 6. Thus it would be necessary to only include it in the .NET 6 version of STJ.

Updates

• Added Utf8Formatter.TryFormat and Utf8Parser.TryParse overloads.

Tagging subscribers to this area: @eiriktsarpalis, @layomia
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Background and Motivation

The recently added types DateOnly and TimeOnly should be fully supported by System.Text.Json. Even when it's possible to make them serializable via a built-in or custom converter, adding support to Utf8JsonReader/Writer brings them on par with other types like DateTimeOffset.

Proposed API

namespace System.Text.Json
{
    public ref partial struct Utf8JsonReader
    {
+        public System.DateOnly GetDateOnly();
+        public System.TimeOnly GetTimeOnly();
+        public bool TryGetDateOnly(out System.DateOnly value);
+        public bool TryGetTimeOnly(out System.TimeOnly value);
    }

    public sealed partial class Utf8JsonWriter
    {
+        public void WriteString(JsonEncodedText propertyName, System.DateOnly value);
+        public void WriteString(JsonEncodedText propertyName, System.TimeOnly value);
+        public void WriteString(string propertyName, System.DateOnly value);
+        public void WriteString(string propertyName, System.TimeOnly value);
+        public void WriteString(ReadOnlySpan<char> propertyName, System.DateOnly value);
+        public void WriteString(ReadOnlySpan<char> propertyName, System.TimeOnly value);
+        public void WriteString(ReadOnlySpan<byte> utf8PropertyName, System.DateOnly value);
+        public void WriteString(ReadOnlySpan<byte> utf8PropertyName, System.TimeOnly value);
+        public void WriteStringValue(System.DateOnly value);
+        public void WriteStringValue(System.TimeOnly value);
    }

    public readonly partial struct JsonElement
    {
+        public System.DateOnly GetDateOnly();
+        public System.TimeOnly GetTimeOnly();
+        public bool TryGetDateOnly(out System.DateOnly value)
+        public bool TryGetTimeOnly(out System.TimeOnly value)
    }
}

namespace System.Text.Json.Node
{
    public abstract partial class JsonNode
    {
+        public static explicit operator System.DateOnly(JsonNode value);
+        public static explicit operator System.TimeOnly(JsonNode value);
+        public static explicit operator System.DateOnly?(JsonNode? value);
+        public static explicit operator System.TimeOnly?(JsonNode? value);
+        public static implicit operator JsonNode(System.DateOnly value);
+        public static implicit operator JsonNode(System.TimeOnly value);
+        public static implicit operator JsonNode?(System.DateOnly? value);
+        public static implicit operator JsonNode?(System.TimeOnly? value);
    }
}

namespace System.Text.Json.Serialization.Metadata
{
    public static partial class JsonMetadataServices
    {
+        public static JsonConverter<System.DateOnly> DateOnlyConverter { get; }
+        public static JsonConverter<System.TimeOnly> TimeOnlyConverter { get; }
    }
}

Usage Examples

    var value = reader.GetDateOnly();
    writer.WriteStringValue(value);

Alternative Designs

As mentioned it would be possible to just add serialization converters for these types without supporting the Utf8Reader/Writer scenarios.

Risks

Obviously this API cannot be added to platforms prior .NET 6. Thus it would be necessary to only include it in the .NET 6 version of STJ.

Author:	devsko
Assignees:	-
Labels:	api-suggestion, area-System.Text.Json, untriaged
Milestone:	-

[eiriktsarpalis]

Tagging @layomia and @steveharter for thoughts. It stands to reason that we should aim to release support for the new types in .NET 6 (presumably conforming to ISO 8601 date only/time only formats).

[devsko]

A small collection of ISO 8601 related issues:

• Add flexible ISO 8601 support to Utf8Parser/Formatter (and beyond?) Add flexible ISO 8601 support to Utf8Parser/Formatter (and beyond?) #28942
• API Suggestion: Additional time format pattern for concise ISO8601 format API Suggestion: Additional time format pattern for concise ISO8601 format #26362
• DateTimeParse.Parse lacks full ISO8601 support DateTimeParse.Parse lacks full ISO8601 support #9364
• System.Text.Json default DateTimeZoneHandling System.Text.Json default DateTimeZoneHandling #1566
• Support 24:00 in hh:mm for ISO8601 dates Support 24:00 in hh:mm for ISO8601 dates #12197
• DateTimeOffset Json Deserialization Inconsistent Across Time Zones DateTimeOffset Json Deserialization Inconsistent Across Time Zones #46879

[devsko]

IMO the formatting/parsing of the new types should be implemented identically as for DateTime(Offset) (and TimeSpan). Any changes wrt ISO 8601 are orthogonal and should be applied to all of these types in the same way.

[mattjohnsonpint]

I agree these should have full parity with the other date/time types.

In the meantime, here's some simple converters that will do the trick. (Though ultimately, they should not be needed.)

public class DateOnlyJsonConverter : JsonConverter<DateOnly>
{
    private const string DateFormat = "yyyy-MM-dd";

    public override DateOnly Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        return DateOnly.ParseExact(reader.GetString(), DateFormat, CultureInfo.InvariantCulture);
    }

    public override void Write(Utf8JsonWriter writer, DateOnly value, JsonSerializerOptions options)
    {
        writer.WriteStringValue(value.ToString(DateFormat, CultureInfo.InvariantCulture));
    }
}

public class TimeOnlyJsonConverter : JsonConverter<TimeOnly>
{
    private const string TimeFormat = "HH:mm:ss.FFFFFFF";

    public override TimeOnly Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        return TimeOnly.ParseExact(reader.GetString(), TimeFormat, CultureInfo.InvariantCulture);
    }

    public override void Write(Utf8JsonWriter writer, TimeOnly value, JsonSerializerOptions options)
    {
        writer.WriteStringValue(value.ToString(TimeFormat, CultureInfo.InvariantCulture));
    }
}

[ericstj]

cc @tarekgh - should we look for elsewhere in the framework that has special handling for DateTime/DateTimeOffset and ensure we add handling for DateOnly/TimeOnly as well?

[tarekgh]

should we look for elsewhere in the framework that has special handling for DateTime/DateTimeOffset and ensure we add handling for DateOnly/TimeOnly as well?

@ericstj yes this is in our radar but not really planned for 6.0 release. It would be good candidate for 7.0 release. If we get a chance before then we should consider it.

[layomia]

We likely won't get to this level of support in .NET 6.0, but can support them in JsonSerializer now - #53539.