Making something a first-class entity may seem like an unquestinably good idea, but it's not always the case. Sometimes it creates more problems than it solves.

I fear TOML's first-class dates is one of those cases. Here's why.

Behaviour is ambiguous

The TOML spec does a good job at specifying acceptable date and time formats. However, it doesn't say what implementations are supposed to do with them.

What it says:

To unambiguously represent a specific instant in time, you may use an RFC 3339 formatted date-time with offset.

RFC3339 dates indeed specify a specific instant in time in the past. They aren't good for things like "an offer valid until 2038-01-19 in Nebraska" because the UTC offset of the Nebraska time zone isn't guaranteed to stay the same until 2038. Timezone changes aren't even that rare and haven't all occured decades ago: for example, Brazil stopped using DST in 2019.

But, that's not really my point. My point is that the spec doesn't say whether the result of deserializing a TOML date should be a timezone-aware object or converting it to a UNIX timestamp is acceptable. In practice... it varies.

Why this matters? If an implementation doesn't preserve timezone information (which it isn't required to do), then dump(load(toml)) is a lossy operation. It can be quite a serious issue for tools that automatically manipulate TOML files.

There's no natural datetime type choice for every language

Some languages, like Python or Go have datetime types and functions in their standard library. Whether a "batteries included" is a good approach or not is debatable.

What isn't debatable is that other languages like Rust or OCaml do not have it built-in—they leave choice of a datetime library to use developer.

However, it means that a TOML parsing library will have to either force a datatime library choice on developers who want to use it, or provide an abstraction mechanism.

Conclusion

All in all, I think TOML would really be better off without first-class dates, which aren't even used all that often in the wild.