Change default `Date` serialization to ISO 8601 format
- Dominant language
- Java
- Stars
- 24.2k
- Forks
- 4.5k
- Avg merge
- 6d 4h
- Merged PRs (30d)
- 12
Description
# Problem solved by the feature
The current default `java.util.Date` serialization uses `DateFormat.getDateTimeInstance(DateFormat.DEFAULT, DateFormat.DEFAULT, Locale.US)` ([source line](https://github.com/google/gson/blob/gson-parent-2.10.1/gson/src/main/java/com/google/gson/internal/bind/DateTypeAdapter.java#L61)), which produces output like the following:
```json
"Jan 1, 1970, 1:00:00 AM"
```
The problem is that this is a locale dependent format intended to be human-readable, and not necessarily to be parsed by computers. The formatting is also dependent on the CLDR data, which changes between Java versions. This has happened for Java 9 already (#1210), and possibly again for Java 20 respectively also older versions using updated CLDR data (https://github.com/google/gson/pull/2450#issuecomment-1652362725, and [JDK-8304925](https://bugs.openjdk.org/browse/JDK-8304925)).
This leads to backward compatibility issues (#1682), and makes this format unsuitable for transferring data to other applications or services. However, users might not even be aware of these pitfalls until they encounter the issues when switching Java versions.
Related issues:
- #223
- #2365 (see also comments there)
# Feature description
- Change the default serialization format for `java.util.Date`, `java.sql.Date`, `java.sql.Timestamp` and `java.sql.Time` to use ISO 8601 format
For this can probably either construct a `SimpleDateFormat` with `Locale.ROOT` which matches the ISO 8601 format (in case that is possible), or use the existing internal Gson class `ISO8601Utils`.
- Deprecate `GsonBuilder` methods `setDateFormat(int)` and `setDateFormat(int, int)`
Because they encourage serializing using a non-stable format. The deprecation message for `setDateFormat(int, int)` could show how a user can write their own `TypeAdapter` if they really need this date formatting. `setDateFormat(String)` would not have to be marked as deprecated because the provided format might be stable and independent of locale settings and CLDR data (I hope).
The existing `Date` deserialization logic already has multiple fallbacks in case parsing fails, including `ISO8601Utils`, so that might work without issues.
Optional changes:
- Change the deserialization logic to try ISO 8601 deserialization first, and only if that fails fall back to the other `SimpleDateFormat` patterns. That might yield better performance.
Risks:
- In some cases applications might be directly displaying the date value to the user, and therefore a human readable format is appreciated
However, serialization always use the US locale, and especially on Android that might not be desired since you want to match the device locale; so it is questionable how many applications actually rely on this.
- The ISO 8601 code (either existing one in Gson, or new one we write) could be faulty; this can cause interoperability issues with other libraries and if we need to fix it in future Gson version, that could be a backward incompatible change
- If a `SimpleDateFormat` is used for ISO 8601 serialization (instead of `ISO8601Utils`), care must be taken that it is not accidentally still dependent on any system settings (locale, timezone, ...) or on the CLDR data
(Note that this is really only a feature request for now; this is not something which has been agreed upon as future Gson change.)
# Alternatives
- Change the `Date` adapter to mimic (or rather duplicate) the US locale default formatting of a certain Java version, without relying (implicitly) on CLDR data, so the pattern remains stable.
The main problem is that this is probably not feasible, or worth the effort.
# Workarounds
Users can either specify a custom date format using `GsonBuilder.setDateFormat(String)`, or register a custom type adapter for `Date` to work around these issues. See also https://github.com/google/gson/issues/2689#issuecomment-2140931166.
Contributor guide
Assessment
This issue has not been assessed yet.