Serializing dates as dates and timestamps as timestamps

[soc]

Consider the following out of the box behavior (note that the change of WRITE_DATES_AS_TIMESTAMPS default from true to false in Jackson 3 is not relevant here).

Jackson 3:

 WRITE_DATES_AS_TIMESTAMPS   |          true          |          false
---------------------------------------------------------------------------------------
 java.util.Date              | "1596105045000"        | "\"2020-07-30T10:30:45.000Z\""
 java.util.GregorianCalendar | "1596105045000"        | "\"2020-07-30T10:30:45.000Z\""
 java.time.Instant           | "1596112245.000000000" | "\"2020-07-30T12:30:45Z\""
 java.time.LocalDateTime     | "[2020,7,30,12,30,45]" | "\"2020-07-30T12:30:45\""
 etc.

Jackson 2:

 WRITE_DATES_AS_TIMESTAMPS   |          true          |          false
---------------------------------------------------------------------------------------
 java.util.Date              | "1596105045000"        | "\"2020-07-30T10:30:45.000+00:00\""
 java.util.GregorianCalendar | "1596105045000"        | "\"2020-07-30T10:30:45.000+00:00\""
 java.time.Instant           | "1596112245.000000000" | "\"2020-07-30T12:30:45Z\""
 java.time.LocalDateTime     | "[2020,7,30,12,30,45]" | "\"2020-07-30T12:30:45\""
 etc.

Both settings do not result in the desirable outcome of serializing dates as dates and timestamps as timestamps, i. e.

• Timestamp: Date, Instant
• Date: ZonedDateTime, LocalDateTime, LocalDate, LocalTime, etc.

(Haven't checked whether GregorianCalendar, like Date, is just a timestamp in disguise.)

One could define a (de)serializer for each class in question and implement the correct behavior, but I wonder if there is a better/easier/more reliable way that feels less like fighting the out-of-the-box behavior of Jackson?

[saivarun1410]

There is no single representation that Jackson can infer as the semantically correct one here. WRITE_DATES_AS_TIMESTAMPS is a global representation preference, while the split in the question is a domain-specific, per-type policy.

In particular, LocalDate, LocalTime, and LocalDateTime cannot be converted to an epoch timestamp without supplying a zone/offset. That is why the Java-time module uses arrays for those types when timestamp output is enabled. GregorianCalendar, on the other hand, contains both an instant and a time zone, so it is closer to Date/Instant than to LocalDateTime.

For a mixed policy, I would use strings as the general default and configure the exceptions by type:

ObjectMapper mapper = JsonMapper.builder()
    .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS)
    .build();

mapper.configOverride(Date.class)
    .setFormat(JsonFormat.Value.forShape(JsonFormat.Shape.NUMBER));
mapper.configOverride(GregorianCalendar.class)
    .setFormat(JsonFormat.Value.forShape(JsonFormat.Shape.NUMBER));
mapper.configOverride(Instant.class)
    .setFormat(JsonFormat.Value.forShape(JsonFormat.Shape.NUMBER));

mapper.configOverride(LocalDate.class)
    .setFormat(JsonFormat.Value.forShape(JsonFormat.Shape.STRING));
mapper.configOverride(LocalTime.class)
    .setFormat(JsonFormat.Value.forShape(JsonFormat.Shape.STRING));
mapper.configOverride(LocalDateTime.class)
    .setFormat(JsonFormat.Value.forShape(JsonFormat.Shape.STRING));
mapper.configOverride(ZonedDateTime.class)
    .setFormat(JsonFormat.Value.forShape(JsonFormat.Shape.STRING));

This centralizes the policy without writing a serializer for every DTO property. Field-level @JsonFormat remains useful where one API field intentionally differs from the application default.

One caveat: numeric Date and numeric Instant do not automatically imply the same unit/precision. Legacy Date output is normally epoch milliseconds, while Instant can use fractional epoch seconds depending on WRITE_DATE_TIMESTAMPS_AS_NANOSECONDS. The wire contract should therefore document both shape and units.

The Java-time module documents the array behavior for local types here: https://github.com/FasterXML/jackson-modules-java8/tree/master/datetime#readme

[soc]

Hey @saivarun1410, I think the approach you propose is in fact the semantically correct one!

From a usage point of view, it might make sense to simply ban Date and GregorianCalendar from DTOs with some ArchUnit rule to enforce the use of Instant for timestamps (with WRITE_DATE_TIMESTAMPS_AS_NANOSECONDS disabled).

Then setting the dates from java.time to JsonFormat.Shape.STRING to be safe from changes to WRITE_DATES_AS_TIMESTAMPS should do the trick.
I guess ADJUST_DATES_TO_CONTEXT_TIME_ZONE requires further investigation from my side.

Thanks!