Removed Features: Dates & Times

[nitz]

Continued from an offshoot in #6 (here):

I had initially agreed with kdl's removal of sdl's date formats. The way sdl offered various formats, in my opinion far outweighed the benefit, and I felt I'd more often than not end up storing dates/times in a manor that suited my application as it were anyways. (e.g.: unix timestamp/windows filetime)

However, @lilyball brought up using specifically ISO8601/RFC3339:

What’s wrong with ISO8601 dates (specifically the profile in RFC3339)? Preferably supporting both date-only and date-time (with optional microseconds).

That solves some of my issues with sdlang's date/time formats that I couldn't quite put a finger on why I didn't like it — their format uses a forward slash as a Y/M/D separator, which felt non-standard when seeing a date in year-month-day order, to me. As well, ISO8601 has (optionally) no whitespace in it's format, where as the sdlang implementation explicitly has a space between the end of the date and the start of the time.

RFC3339 carries with it a bit of a double-edge sword, though: It is a very specific definition of ISO8601 that disallows many of the things that would make parsing more complicated. The other side of that is that it leaves little room for users to hand-write a value in kdl without adhering directly to the format. I agree it'd be nicest to allow a date-only/time-only/date-time, but again that's would add to the complexity of parsing, and reduce flexibility in terms of the language as a whole.

If dates/times were to be considered, I see these as the questions/topics worth covering first:

• Use RF3339 directly, or a subset that would specify using things like the T separator between date-time?
• Should it be allowed to have only a date, only a time, and a full date time?
• Would the language allow specifically for time spans/durations (as in [date]time->[date]time)? SDL does timespans as unadorned times, or specifying things like 2d:14:03:22.
• Is a date/time a universal enough data-type that it can be reasonably expected to be represented by any particular parser? (e.g.: .NET has the DateTime/TimeSpan types that would do very well to directly represent these, mostly. But in C, things like the tm struct comes close, but doesn't allow for things like milliseconds/microseconds. Would this be an implementation detail? Could cause portability issues.)

I'm sure I had more thoughts but I'm going to press start discussion before I get even more rambley than I had intended!

[lilyball]

I'm definitely in favor of supporting datetimes and dates. I'm less convinced about time-only. I think they're potentially useful in some cases, but do not necessarily have a standard representation in many languages. Times could I suppose be represented, in the absence of something more structured, as just a duration from the start of the day, but this would pose issues on DST transitions (e.g. if I represent 02:30:00 as 9000.0, and then apply this to a date that has a DST transition, this will end up mapping to 01:30:00 or 03:30:00 instead). Solo dates also don't always have a conventional representation, but using the time 00:00:00 is fairly standard in the absence of something better and don't have issues with DST, though you have to be careful not to shift time zones.

I don't actually know offhand how to handle dates and times in many languages. Though dates, datetimes, and times can all be handled in Swift/Obj-C (using DateComponents), and can be handled in Rust's chrono crate (using NaiveDate, NaiveTime, and DateTime/NaiveDateTime).

Regarding specific formatting, I think RFC3339 is the way to go. It seems to be the most standard profile of ISO8601. The BNF in RFC3339 specifies the "T" separator. It's followed by a note saying applications may choose to allow separation by e.g. spaces, but we should require the use of "T". Here's my recommendations:

• I think we should definitely allow solo date (full-date in RFC3339's grammar), and datetime (date-time in the grammar).
• I'm inclined to say we should allow solo time as well, without time zone (partial-time in the grammar). If there's no obvious choice for a solo time in a language, the parser can always define their own struct for it. No time zone here because it really doesn't make sense to declare a time zone without an associated date (can't do time zone conversions without dates, and time zones shift on DST boundaries). I'm open to dropping solo times though.
• Times should support subsecond precision. I think we can state this something like "parsers MUST parse the optional subsecond precision on times. parsers SHOULD store the subsecond precision, but MAY truncate to second precision. Note that truncating to second precision may produce data loss when reserializing a parsed KDL file and should be avoided if possible".
• ISO8601 has a defined format for durations. RFC3339 does not cover this. The format looks like P2DT5H for 2 days 5 hours. And it also allows for describing time intervals using pairs of datetimes or datetime+duration. This gets rather complicated though. I think we should just skip this. Anyone that wants to represent durations can use strings, or write something like start=2020-12-17T01:02:03Z end=2020-12-17T05:02:03Z. Durations are sufficiently rare that I only recently even learned about the ISO8601 duration syntax.

Questions:

• RFC3339 requires the time offset on datetimes. Do we want to do this, or should we allow for omitting it in order to represent a "floating" time? If we support time-only values then floating times could be represented as something like date=2020-12-27 time=01:02:03, but this is a little awkward. I like the idea of supporting floating times, my biggest worry is really just parsers choosing to decode floating datetimes as datetimes in the local time zone, causing issues for round-trip fidelity. Granted, we may already have this issue for datetimes with time zones as parsers may not necessarily preserve the time zone information. But converting a datetime between time zones is less of an issue than converting a floating datetime into UTC.

  Ideally a parser would use a "date components" object (like Swift/Obj-C's DateComponents), though I don't know how common these are in other languages. Parsers could always just define their own of course.

[junosuarez]

I'm strongly in favor of the document format staying neutral on DateTime semantics at the syntax and data type level.

The currently proposed structure is rich enough to encode whatever an application might need, whether as an ISO date string, a numeric timestamp, or a property (or even a full node) with a special name (inspired by some JSON encoding schemes) e.g.

service {
    self-destruct-on { $date "2020-12-24T09:50:17.066Z" }
}

Time is a very complex domain to try to model, for cultural and historical reasons, and it is differently implemented on various target platforms. Attempting to include this in the spec seems like a very large undertaking - and potentially a large source of churn and instability in an area of a system that substantially benefits from consistency and predictability: configuration.

[ericsampson]

* RF3339

@nitz for clarity, RFC3339 mandates a 'T' separator (case insensitive). The space option is supposed to be only for rendering to the user.

I also support RFC3339 as the format for KDL (datetime, date-only. time-only if people feel it's necessary).

[zkat]

FYI, I think the decision is going to be "no official date/time literals". Instead, please use the KDL Schema Language to specify the intended types for particular strings. I believe this is sufficient, without potentially starting a cascade of requests for other literals to what should be a very very small language. By having it in the Schema, I also would like to think that "blesses" RFC3339 as the "official" datetime format.

[mnmr]

I predict that KDL will get very little traction (as a data exchange format) without a universal definition of dates that people can use out of the box. Everyone currently using JSON will have zero motivation to use something else for their next project, let alone change what they currently use, if all they get are the same problems with a new syntax.

(Google's) ProtoBuf team originally made the same mistake, and only in later versions added "well known types" for data types that people just can't do without (such as dates and durations).

[zkat]

Can you explain why official datetime type annotations and schema types aren't enough?