Enhancement/1.x datetime serialization

[russcam]

Comparison of how NEST, which uses IsoDateTimeConverter for DateTime, serializes DateTime and DateTimeOffset, compared to the default JSON.Net behaviour which does not use IsoDateTimeConverter.

A summary of how NEST serializes, in conjunction with Json.Net's DateTimeZoneHandling

NEST's behaviour (IsoDateTimeConverterHandlingTests)

DateTime

DateTimeZoneHandling.RoundTripKind (Default)

DateTimeKind are handled differently:
Unspecified:

• Serialized without any time zone id or offset.
• Deserialized to datetime represented by IS08601 string with DateTimeKind.Unspecified

Utc:

• Serialized with Z UTC timezone identifier
• Deserialized to datetime represented by IS08601 string with DateTimeKind.Utc

Local:

• Serialized with offset from UTC
• Deserialized to datetime represented by IS08601 string with DateTimeKind.Local

DateTimeZoneHandling.Unspecified

Serialized without any time zone id or offset.
Deserialized to datetime represented by IS08601 string with DateTimeKind.Unspecified

DateTimeZoneHandling.Utc

DateTimeKind are handled differently:
Unspecified:

• Serialized with Z UTC timezone identifier
• Deserialized to datetime represented by IS08601 string with DateTimeKind.Utc

Essentially, DateTimeKind.Unspecified is serialized as though it were DateTimeKind.Utc and deserialized as though it were DateTimeKind.Utc

Utc:

• Serialized with Z UTC timezone identifier
• Deserialized to datetime represented by IS08601 string with DateTimeKind.Utc

Local:

• Serialized with offset from UTC
• Deserialized to UTC datetime with offset applied to IS08601 string representation, and DateTimeKind.Utc. Calling .ToLocalTime() on this instance would return a DateTime instance with DateTimeKind.Local.

DateTimeZoneHandling.Local

DateTimeKind are handled differently:
Unspecified:

• Serialized without any time zone id or offset.
• Deserialized to local datetime represented by IS08601 string with DateTimeKind.Local

Essentially, DateTimeKind.Unspecified is serialized as DateTimeKind.Unspecified and deserialized as though it were DateTimeKind.Local

Utc:

• Serialized with Z UTC timezone identifier
• Deserialized to local datetime with local offset applied to the IS08601 string representation, and DateTimeKind.Local. Calling .ToUniversalTime() on this instance would return a DateTime instance with DateTimeKind.Utc.

Local:

• Serialized with offset from UTC
• Deserialized to local datetime represented by IS08601 string with DateTimeKind.Local

DateTimeOffset

DateTimeOffset always serialize to an ISO8601 string representation that includes the offset as per the DateTimeOffset instance.

DateTimeOffset always deserialize to datetime as represented by IS08601 string with an Offset set to the offset within the ISO8601 representation.

Json.NET's default behaviour (DateTimeZoneConverterHandlingTests)

DateTime

DateTimeZoneHandling.RoundTripKind (Default)

DateTimeKind are handled differently:
Unspecified:

• Serialized without any time zone id or offset.
• Deserialized to datetime represented by IS08601 string with DateTimeKind.Unspecified

Utc:

• Serialized with Z UTC timezone identifier
• Deserialized to datetime represented by IS08601 string with DateTimeKind.Utc

Local:

• Serialized with offset from UTC
• Deserialized to datetime represented by IS08601 string with DateTimeKind.Local

DateTimeZoneHandling.Unspecified

Serialized without any time zone id or offset.
Deserialized to datetime represented by IS08601 string with DateTimeKind.Unspecified

DateTimeZoneHandling.Utc

DateTimeKind are handled differently:
Unspecified:

• Serialized with Z UTC timezone identifier
• Deserialized to datetime represented by IS08601 string with DateTimeKind.Utc

Essentially, DateTimeKind.Unspecified is serialized as though it were DateTimeKind.Utc and deserialized as though it were DateTimeKind.Utc

Utc:

• Serialized with Z UTC timezone identifier
• Deserialized to datetime represented by IS08601 string with DateTimeKind.Utc

Local:

• local datetime is converted to UTC then serialized as UTC representation with Z UTC timezone identifier
• Deserialized to UTC datetime represented by IS08601 string, and DateTimeKind.Utc. Calling .ToLocalTime() on this instance would return a DateTime instance with DateTimeKind.Local.

DateTimeZoneHandling.Local

DateTimeKind are handled differently:
Unspecified:

• Serialized with local offset from UTC
• Deserialized to local datetime represented by IS08601 string with DateTimeKind.Local

Essentially, DateTimeKind.Unspecified is serialized as DateTimeKind.Local and deserialized as though it were DateTimeKind.Local

Utc:

• UTC datetime is converted to local datetime then serialized as local representation with local offset from UTC
• Deserialized to local datetime represented by the IS08601 string, and DateTimeKind.Local. Calling .ToUniversalTime() on this instance would return a DateTime instance with DateTimeKind.Utc.

Local:

• Serialized with local offset from UTC
• Deserialized to local datetime represented by IS08601 string with DateTimeKind.Local

DateTimeOffset

DateTimeOffset always serialize to an ISO8601 string representation that includes the offset as per the DateTimeOffset instance.

DateTimeOffset always deserialize to datetime as represented by IS08601 string with an Offset set to the offset within the ISO8601 representation.

Summary

The key difference between NEST's serialization and Json.NET's serialization is

• How DateTime of DateTimeKind.Local are serialized when using DateTimeZoneHandling.Utc
• How DateTime of all 3 DateTimeKind are serialized when using DateTimeZoneHandling.Local

[Mpdreamz]

LGTM can we have one additional test file that shows off our default handling datetime handling in isolation?

[russcam]

Thanks for reviewing @Mpdreamz! I've added a test to show the defaults within NEST.

@gmarz, would you mind reviewing?