util.JSON.setDatetimeSerializationMode

The util.JSON.setDatetimeSerializationMode() class method globally defines the formatting mode for DATETIME values when using util.JSON classes.

The "RFC3339/*" format modes can be used to conform to JSON standards, in order to produce date/time strings that conform to the RFC 3339 specification.

Default FGL mode

By default, the serialization format is the legacy "FGL" format, which is also used when converting a DATETIME to a STRING, or when displaying a DATETIME value to a form field.

The RFC3339/TZO mode

DATETIME YEAR TO MINUTE/SECOND/FRACTION values convert into RFC 3339 format as local date/time, by adding the T separator and the ±hh:mm time zone offset (automatically computed from the current system TZ settings). Since RFC-3339 requires a complete time part with seconds, then resulting string will always be in the form YYYY-MM-DDThh:mm:ss[.fffff]±hh:mm: If the DATETIME lower qualifier is MINUTE, the resulting string will be completed with :00 seconds to conform to RFC 3339.

DATETIME YEAR TO HOUR cannot be converted to RFC 3339, because it’s impossible to compute a proper timezone offset, since there can be timezones with half-hour offsets like TZ=Asia/Kolkata (UTC+5:30). Consequently, such DATETIME is serialized by using the default FGL format.

With DATETIME HOUR TO MINUTE/SECOND/FRACTION, the result will be a local time without any timezone indicator, because the timezone offset cannot be computed when date part is missing. The resulting string will be in the form hh:mm[:ss[.fffff]], as a local wall-clock time, depending on the precision of the last qualifier. DATETIME HOUR TO MINUTE will produce hh:mm (accepted by ISO 8601, RFC 3339 defines only date+time data format)

For DATETIME YEAR TO DAY (or TO MONTH/YEAR) with only date info, the ±hh:mm offset makes no sense, and is not RFC 3339 anyway (there must be a time part)

DATETIME with partial date information (such as DATETIME MONTH TO MINUTE) cannot have a valid RFC 3339 representation. For example, 10-15T12:00 is ambiguous and invalid in RFC 3339. Consequently, it must be serialized with the default FGL format rules, as a local date/time value.

The RFC3339/UTC mode

DATETIME YEAR TO MINUTE/SECOND/FRACTION values are converted to a UTC date/time value according to system settings (TZ), and formatted by adding the T separator between the date and the time parts, plus the trailing Z indicator. The date/time value is converted from local date/time to UTC .

Other DATETIME types will be serialized in the default FGL format, because the precision of the DATETIME is not sufficient to make proper UTC conversion. Even DATETIME YEAR TO HOUR can’t be properly converted, because of half-hour timezones like +05:30.