Proposal to Refine the Representation of datetime and datetime with offset

[Seddryck]

Currently, the specification represents both datetime (without offset) and datetime with offset using the same type, datetime. As a result, the default format for this type is not unique, leading to ambiguity and practical challenges when handling such values programmatically.

We propose (one of the alternatives):

1. Introducing a distinct type for datetime with offset, e.g., datetimeoffset, to differentiate it from datetime (without offset).
2. Alternatively, adding a property (e.g., useOffset: true/false) to explicitly indicate whether an offset is expected for a datetime field.
3. Restricting the default datetime format to only allow %Y-%m-%dT%H:%M:%S (without timezone information). If a timezone or offset is needed, the format must explicitly indicate it, and consumers are then expected to use a datetime with offset type.

---

Context of datetime and datetime with offset

In .NET, the distinction between DateTime and DateTimeOffset is critical:

• DateTime:

  • Represents a date and time, which can be unspecified, local, or UTC.
  • Lacks inherent offset information and relies on context (e.g., the system’s time zone) for interpretation.

• DateTimeOffset:

  • Represents a specific point in time with an explicit offset from UTC.
  • Provides a safer, unambiguous way to store and manipulate datetime values in distributed or cross-time-zone systems.

By conflating these two representations into a single datetime type in the specification, the following issues arise:

---

1. Safe Typing is Obstructed

Currently, it is impossible to determine whether a DateTime or DateTimeOffset should be used in .NET based solely on the type property in the specification. This leads to:

• Ambiguity in serialization and deserialization processes.
• A risk of incorrectly interpreting or manipulating datetime values, especially in applications where timezone correctness is critical.

---

2. Ambiguity in Parsing and Default Formats

The specification allows for a datetime value to optionally include an offset (e.g., 2025-01-07T15:30:00+02:00) or not (e.g., 2025-01-07T15:30:00). When a format is explicitly provided, it is sometimes possible to infer whether a timezone or offset is expected. However:

• Default formats remain ambiguous: Without an explicit format, there is no way to reliably distinguish between datetime and datetimeoffset.
• This ambiguity makes it difficult to handle these values consistently across systems, particularly when strict type safety is required.

---

3. Parsing at Runtime is Problematic

When reading or parsing datetime values, the current approach assumes producers can mix both datetime and datetimeoffset values within the same field. This introduces several issues:

• Parsing logic must guess whether a given value includes an offset or not.
• Mixing datetime and datetimeoffset values in the same field is inconvenient to handle and prone to errors, as it burdens the consumer with reconciling inconsistent representations.
• This undermines interoperability and increases the risk of subtle bugs, particularly in distributed systems where timezone handling is critical.

---

Proposed Benefits

1. Clear Type Distinction:

   • Introducing a datetimeoffset type or a useOffset property would enable producers and consumers to unambiguously identify the intended representation and enforce type safety at both design time and runtime.

2. Improved Parsing Logic:

   • By explicitly distinguishing between datetime and datetimeoffset, parsing logic becomes straightforward, eliminating the need for guessing based on the value format.

3. Consistency Across Producers and Consumers:

   • Restricting the default datetime format to %Y-%m-%dT%H:%M:%S ensures clarity. Consumers can then infer that if a format includes timezone information (e.g., %Y-%m-%dT%H:%M:%S%z), they should expect a datetime with offset type. This approach avoids mixing representations within the same field and enforces clear expectations for data handling.

---

Implementation Suggestions

1. Introduce datetimeoffset as a New Type:

   • Define a distinct type in the specification to represent datetime values with an explicit offset.
   • Ensure this type has a unique default format (e.g., YYYY-MM-DDTHH:mm:ss±hh:mm).

2. Add an Explicit useOffset Property:

   • Augment the existing datetime type with a property, e.g., useOffset, to clarify whether an offset is required for the field.

3. Restrict Default datetime Format:

   • Allow only %Y-%m-%dT%H:%M:%S as the default format for datetime.
   • Enforce that any format requiring timezone information should use datetime with offset. Consumers should rely on the format to determine the expected type and handle it accordingly.

---

Conclusion

By adopting this proposal, the specification would align better with robust, type-safe handling of datetime values in programming environments like .NET. This change would eliminate ambiguities, improve parsing reliability, and ensure consistent handling of datetime values across producers and consumers.

[khughitt]

Thanks for taking the time to write up this clear discussion of the issue and possible solutions!

Having dealt with datetime ambiguity myself, I'm sympathetic to the argument and this seems like a good idea to me.

I'm not sure about which solution makes the most sense though. I'm curious to hear what other people think.