DATE, DATETIME, and INTERVAL conversions

The output format depends on the output mode, which you set in one of two places:

• When generating a client stub, with the --datetime-interval-format option of the fglrestful tool.
• When writing a REST service, with the datetimeSerializationMode and intervalSerializationMode options of json.Serializer.

The following table gives the json.Serializer option values for each output mode:

The iso8601-local mode includes the time zone offset of the server process at runtime. As a result, the same DATETIME value can produce different output on servers configured with different time zones.

DATE and DATETIME

OpenAPI represents date and time values as strings. The format keyword distinguishes between date-only and date-time values.

In the OpenAPI document of a Genero REST service, the GWS generates the date-time and duration formats only when the service uses the matching RFC 3339 or ISO 8601 mode. In the default "FGL" mode, the service writes the native BDL form, so the property has no format. Set the json.Serializer options before you call com.WebServiceEngine.Start(), so that the document and the values the service writes use the same form.

DATE

A DATE value is represented as a string with the date format, in every serialization mode:

schema
type         "string"
format       "date"

In this case, fglrestful generates a Genero BDL DATE type in the client stub.

DATETIME

For DATETIME values, GWS sets the format keyword based on the qualifier and on the datetimeSerializationMode option:

• A DATETIME YEAR TO DAY is mapped to the following, in every mode, because the value has no time component:

  schema
  type         "string"
  format       "date"

• A DATETIME YEAR TO MINUTE, YEAR TO SECOND, or YEAR TO FRACTION(n) is mapped to the following when datetimeSerializationMode is "RFC3339/UTC" or "RFC3339/TZO":

  schema
  type         "string"
  format       "date-time"

  In the default "FGL" mode, it is mapped to a plain string with no format:

  schema
  type         "string"

• A DATETIME with other qualifiers (for example, YEAR TO MONTH or HOUR TO MINUTE) is mapped to a plain string with no format, because no RFC 3339 representation is available:

  schema
  type         "string"

For a property with the date-time format, fglrestful generates a DATETIME YEAR TO SECOND type in the client stub. For a property with no format, it generates STRING.

You can control the fractional precision by setting the --datetime-fraction option in the fglrestful command. For example:

--datetime-fraction=3

This generates a DATETIME YEAR TO FRACTION(3) type.

INTERVAL

For INTERVAL values (both DAY TO SECOND and YEAR TO MONTH), GWS sets the format keyword based on the intervalSerializationMode option:

• When intervalSerializationMode is "ISO8601", an INTERVAL is mapped to the duration format:

  schema
  type         "string"
  format       "duration"

• In the default "FGL" mode, it is mapped to a plain string with no format:

  schema
  type         "string"

For a property with the duration format, fglrestful generates an INTERVAL DAY(9) TO FRACTION(5) type in the client stub. For a property with no format, it generates STRING.

You can override this behavior by using the --interval option of fglrestful to select a different qualifier or to restore the previous mapping to STRING.

The duration format is defined in the OpenAPI Format Registry (JSON Schema 2019-09 / OpenAPI 3.1). Tools that do not support this format treat the value as a plain string.