Skip to content

DateTime adapters

The standard defines different types for representing date and time elements. For some of them multiple options are compliant for their string representation in the XML. To accommodate the flexibility and variability in representing date and time elements as per ISO standards and specific usage guidelines, the library employs type adapters.

The Java model is annotated with generic type adapters, allowing multiple implementation options for marshalling and unmarshalling the different date and time values.

Default Adapters

The default implementations of these type adapters are designed to handle the most common cases. These default adapters ensure that date and time elements are serialized and deserialized in a manner that aligns with ISO conventions.

For example, the default implementation for IsoDateTimeAdapter ensures that date-time values are represented as local time with a UTC offset in the format YYYY-MM-DDThh:mm:ss[.sss]+/-hh:mm. Similarly, the IsoDateAdapter handles date values in the format YYY-MM-DD, and the IsoTimeAdapter manages time values in the format hh:mm:ss[.sss]+/-hh:mm.

This implementation by default will replace the Zulu indicator Z with the +00:00 offset, and will also trim meaningless zeros in the fractional seconds. However, you can customize this behavior by providing your own adapter.

Customization for Specific Use Cases

While the default adapters cover a wide range of scenarios, there may be cases where you need to tailor the serialization and/or deserialization of date and time elements to meet specific requirements. In such situations, the library allows you to override or replace the default adapters with your custom implementations.

By creating custom adapters, you can precisely control how date and time values are represented in XML. This customization is particularly valuable when your XML documents need to adhere to specific standards or conventions that deviate from the default representations.

The TypeAdaptersConfiguration holder DTO is used to set up a collection of adapters. This configuration is then used by the MxWriteConfiguration and MxReadConfiguration to set up the adapters in the JaxbContext.

There are many ways to create custom adapters by just implementing the XmlAdapter interface.

The following example leverage the default adapters to create custom adapters that preserve the default behavior but add additional customization with a simple string replace to preserve the Zulu indicator Z for offset date times in UTC.

    public class CustomDateTimeAdapter extends OffsetDateTimeAdapter {
        @Override
        public String marshal(OffsetDateTime offsetDateTime) throws Exception {
            return StringUtils.replace(super.marshal(offsetDateTime), "+00:00", "Z");
        }
    }
The custom implementation can then be passed to the MxWriteConfiguration to override the default adapter. 
    MxWriteConfiguration config = new MxWriteConfiguration();
    config.adapters.dateTimeAdapter = new IsoDateTimeAdapter(new CustomDateTimeAdapter());
    xml = mx.message(config);

Date and time values without offset

The ISO 20022 date time and time types allow three lexical forms: UTC (2026-06-29T12:30:00Z), local time with an offset (2026-06-29T12:30:00+02:00) and plain local time without any offset (2026-06-29T12:30:00). In XML Schema terms the last form is a local time with an indeterminate zone.

The Java model maps these elements to OffsetDateTime and OffsetTime, types that always carry an offset. When the XML value has no offset, the default adapters have to resolve one, and they use a fallback zone to do it. By default the fallback zone is the JVM default time zone, so the same document parsed on servers with different time zone settings produces different offsets, and the information that the source carried no offset is not kept in the model.

Since version 10.3.11 the fallback zone is configurable. The simplest way is the TypeAdaptersConfiguration.withFallbackZone factory, which creates the default adapters for date time and time with the given zone, and can be used both when parsing and when writing.

    MxReadConfiguration conf = new MxReadConfiguration();
    conf.adapters = TypeAdaptersConfiguration.withFallbackZone(ZoneOffset.UTC);
    MxSeev00100112 mx = MxSeev00100112.parse(xml, conf);

    // <DtTm>2026-06-29T12:30:00</DtTm> is now 2026-06-29T12:30:00Z in every environment
    OffsetDateTime meeting = mx.getMtgNtfctn().getMtgDtls().get(0).getDtAndTm().getDtOrDtTm().getDtTm();

Any ZoneId is accepted. With a region zone such as Europe/Berlin the offset in effect at the parsed date is applied, so daylight saving is honoured (+02:00 in summer, +01:00 in winter). The same option is available directly in the constructors of OffsetDateTimeAdapter, OffsetTimeAdapter and ZuluOffsetDateTimeAdapter, for configurations that combine it with a custom format.

Two details to keep in mind:

  • Values with an explicit offset or Z in the XML are never affected by the fallback zone.
  • A time element carries no date, so for OffsetTime values without offset the zone offset in effect at parsing time is applied.

The fallback zone makes the parsing deterministic, but the model still cannot represent "no offset": once the value is in an OffsetDateTime there is no way to tell whether the source document carried one. When the application needs that distinction, check the raw element value in the source XML (whether it ends in Z, +hh:mm or -hh:mm) and keep the flag alongside the parsed model.

When the parsed message is then translated to MT, the translation detects the injected offset against the translator's reference time zone; see the Reference time zone option in the MX to MT translations page and use the same zone in both configurations.

The option applies to every model bound to the generic adapters, which includes the SIC restricted model. The CBPR+ restricted model binds its own date time and time adapters on most elements (for example the group header creation date time), and those keep resolving values without offset in the JVM default time zone; only the few CBPR+ elements bound to the generic adapters follow the configured fallback zone.