Add support for Date/TimeOnly to STJ

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.

@layomia

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).

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

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.

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));
    }
}

@tarekgh

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?

@ericstj

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.

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

Are XmlSerializer and DataContractSerializer also going to be supported?

@LaughingJohn

@LaughingJohn I created a separate issue on that question to be considered by the area owners of those serializers.

@eiriktsarpalis

Thanks @eiriktsarpalis!

Closing in favor of #53539.

Navigation Menu

Repository navigation

Add support for Date/TimeOnly to STJ #51302

Background and Motivation

Proposed API

Usage Examples

Alternative Designs

Risks

Updates

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Add support for Date/TimeOnly to STJ #51302

Description

Background and Motivation

Proposed API

Usage Examples

Alternative Designs

Risks

Updates

Activity

eiriktsarpalis commented on Apr 15, 2021

devsko commented on Apr 15, 2021

devsko commented on Apr 16, 2021

mattjohnsonpint commented on May 7, 2021

ericstj commented on May 25, 2021

tarekgh commented on May 25, 2021

layomia commented on Jun 1, 2021

LaughingJohn commented on Aug 2, 2021

eiriktsarpalis commented on Aug 2, 2021

LaughingJohn commented on Aug 2, 2021

eiriktsarpalis commented on Oct 22, 2021

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions