Propose Jackson 3 should serialise date/time classes as RFC 3339 / ISO 8601 by default

[Terry M]

Hi Tatu,

Thank you for your work on Jackson.

Could I propose date/time classes (in particular java.time.*) serialise as RFC 3339 / ISO 8601 interchange format by default for Jackson 3, and not as an epoch second, milli, micro or nano, etc.

It is the recommended practice by many in the industry (E.g. Google / Microsoft / json-schema validation, see links below) that RFC 3339 / ISO 8601 be used for the serialisation format for date/times in JSON and in particular JSON REST API design.

It is also generally the default format used by java.time.* .toString() and .parse() methods.

RFC 3339 / ISO 8601, I would say, is a better format than an epoch as

• it is human readable
• can preserve timezone information
• has nano precision
• has a maximum timestamp value that is not limited by the bit-length of a double/long (platform specific) and
• does not have unambiguous precision when inspecting the value (milli/micro, etc).

Additionally, is a more intuitive format for serialising LocalDate, rather than the current default of a JSON numeric array of [year, month, day]

Speaking from my experience, its seems a common source of bugs for developers not realising that either overriding global config defaults (e.g. disable SerializationFeature.WRITE_DATES_AS_TIMESTAMPS) or field level annotations (@JsonFormat(shape = STRING)) are necessary (or possible) to serialise as such. 

Other frameworks may for instance try to do this already, for example Spring Boot's JacksonAutoConfiguration does this by default.

I did see JSTEP-2: Changes to date/time defaults and JSTEP-5: Unify Date/Time handling but it seems it hadn't come to a firm conclusion what the default behaviour for date time serialisation in Jackson should be.

Thanks for your consideration.

References which consider RFC 3339 / ISO 8601 for datetime:

• Google JSON style guide - Date Time Property values
• Microsoft API guidelines - JSON serialisation of dates and times
• JSON Schema - dates and times
• API Stylebook - date time - Collection of other vendor Styleguides

[Tatu Saloranta]

Thank you for this well-researched proposal. I think that it would
make sense to change the defaults here.

But how do others feel? Does anyone think that the use of
(Java-centric) timestamps as the default would be better choice?

-+ Tatu +-

[Mark Derricutt]

Bring on ISO!

Makes things so much more useful when dealing with timezones as well. It’s handy to know what timezone something was requested in - so you could return in the matching zone if needed/desired.  Much easier to debug when looking at logs of payloads IMHO.

Retaining an option to revert to timestamps tho for compatibility.

Mark

--
"Great artists are extremely selfish and arrogant things" — Steven Wilson, Porcupine Tree

--
You received this message because you are subscribed to the Google Groups "jackson-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to jackson-dev...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/jackson-dev/CAL4a10iQ%2By__wLq3DX5mhX4kM1KX3ib4_p8CiXmUmqDcteuhHw%40mail.gmail.com.

[Michael]

+1 from me also on the RFC / ISO for serialization. 

It looks like it would solve a few sticky issues for the Jackson date/time classes where we've been trying to avoid adding more config options, which as pointed out are already a little complex for developers to get right. Along the same lines, this fits even more with the JSON "readability" design guideline, i.e. the JSON itself is more self-explanatory, without needing to know special config settings. Finally, if this is already recommended practice in the industry, that is another strong point. Not to say the standards are always right, and we should just follow the crowd, but here it seems to make sense.

Just making sure, you meant "does not have ambiguous precision" here? I think that's a big selling point.

does not have unambiguous precision when inspecting the value (milli/micro, etc).

Thanks for bringing this forward!

To view this discussion on the web visit https://groups.google.com/d/msgid/jackson-dev/CALYGm1x8BMtp1ZqAx%3DKG%2Bm%3DJX9aE6ZEJqz6K%2BsyiBrO4ka56Xw%40mail.gmail.com.

--

Written on a glass keyboard.

[Terry M]

Just making sure, you meant "does not have ambiguous precision" here? I think that's a big selling point.

Ah yes! It should read  "does not have ambiguous precision" - excuse the double negative.  

[Tatu Saloranta]

Ok seems like there is a wide consensus on this -- I will add a note
on the relevant Wiki page(s).

Obviously if anyone has opinions to share feel free to continue
discussion but so far I haven't seen anyone objecting to it.

-+ Tatu +-

> To view this discussion on the web visit https://groups.google.com/d/msgid/jackson-dev/CAEBemP0dLK_-WBq_TS-4m8FfuN2r%2B-oo%2B0_%3DoViBEG%3Dj%3D%2Bc4Pg%40mail.gmail.com.