Subject: [Tzdist] Forming "expand" requests more like "get"

From: Tim Parenti <[email-masked]>
Date: Wed, 24 Sep 2014 10:31:36 -0400

I was taking a look at Ken Murchison's test server implementation at
https://cyrus-test.andrew.cmu.edu/timezone/ and noticed another peculiarity:

Consider the two requests:
action=get&tzid=America/New_York&truncate=20140101T000000Z,20380101T000000Z
action=expand&tzid=America/New_York&start=20140101T000000Z&end=20380101T000000Z

I wonder why these requests, which fundamentally seek the same data (albeit
in different formats), take such a different form?  Both the iCal and JSON
responses interpret and represent the source data in a way that is more
suitable to each format.  Since both actions "get" data, and both actions
"expand" the data, the distinction between the action verbs in this context
is lost on me.

For his internal testing, Ken adds the nonstandard:
action=expand&tzid=America/New_York&start=20140101T000000Z&end=20380101T000000Z&format=zdump
... which got me thinking.

I propose we use action=get for both iCal and JSON responses, specified by
either format=text/calendar or format=application/json.  Further, I propose
that we get rid of the truncate parameter and instead use explicit start
and end parameters for that purpose in 6.3 with the same behavior as
specified in 6.4.  This would require merging 6.3 and 6.4, as well as
modifying some of the associated examples.

I believe this is separate enough from Lester's action=next proposal in
http://www.ietf.org/mail-archive/web/tzdist/current/msg00597.html to
warrant its own thread.

--
Tim Parenti

---

From: Tobias Conradi <[email-masked]>
Date: Wed, 24 Sep 2014 18:42:26 +0200

On Wed, Sep 24, 2014 at 4:31 PM, Tim Parenti <[email-masked]> wrote:

> I propose we use action=get for both iCal and JSON responses
This is in opposition to

http://www.ietf.org/mail-archive/web/tzdist/current/msg00518.html

which proposed to remove "get" since all actions have the sole purpose
to get data.

-- 
Tobias Conradi
Rheinsberger Str. 18
10115 Berlin
Germany

http://tobiasconradi.com

---

From: Cyrus Daboo <[email-masked]>
Date: Wed, 24 Sep 2014 13:40:37 -0400

Hi Tim,

--On September 24, 2014 at 10:31:36 AM -0400 Tim Parenti 
<[email-masked]> wrote:

> either format=text/calendar or format=application/json.  Further, I
> propose that we get rid of the truncate parameter and instead use
> explicit start and end parameters for that purpose in 6.3 with the same
> behavior as specified in 6.4.  This would require merging 6.3 and 6.4, as
> well as modifying some of the associated examples.

"expand" is different from "get" in that any "rules" in the tz data are 
converted into fixed date-time values for the actual observance changes. 
Thus, an RRULE property in iCalendar would have to be converted into a set 
of RDATE properties. I am not sure the expanded list of observances makes 
sense in an iCalendar format (and I know my library currently does not have 
a provision for doing that), so I would want to at least make expanding 
into iCalendar format optional.

If we do make it optional, then it does make sense to separate the "get" 
and "expand" options, as the set of allowed response types will vary for 
each one (i.e., iCalendar OK for "get", tzdist specific JSON OK for 
"expand").

If we did merge "expand" into "get", then we would have to add an 
"expand=true" query parameter for "get" to allow clients to get either the 
rules-based data or the expanded data, and have to provide a more complex 
logic in the capabilities to expose what format= values are allowed based 
on the expand= value.

At the end of the day, I believe the current "expand" JSON format is much 
more succinct then iCalendar (or jCal, xCal) and is the better choice for 
clients that don't care about iCalendar itself (e.g., a thermostat using 
its own internal data format for weekday temperature transitions).

As for start/end vs truncate, there is a subtle difference in regards to 
whether the end point of the range is inclusive or exclusive. We discussed 
that before and came to the current state where the truncation end is 
inclusive and the expand end is exclusive. If we were to change that 
decision and ended up with both end points being the same "type" then it 
would make sense to drop truncate in favor of start/end.

-- 
Cyrus Daboo

---

From: Tim Parenti <[email-masked]>
Date: Wed, 24 Sep 2014 14:20:06 -0400

> logic in the capabilities to expose what format= values are allowed based

I think action=get[&expand=true] is far clearer than action=get vs
action=expand, especially for formats which may be able to serve both
expanded and unexpanded versions.  Do we expect this to be common?
Certainly any "non-expanded" set of rules can be expressed degenerately as
an "expanded" set of one-off rules describing each instance.

> its own internal data format for weekday temperature transitions).

While keeping in mind future extensibility, we're currently only dealing
with two data formats.  You mentioned the possibility of an expanded
iCalendar format, so I guess an equally relevant question would be: Do we
expect to have a non-expanded JSON format?  Transforming rulesets in the
opposite direction is not as generalizable.  What would such a format even
look like?  These answers might help inform the above.

> would make sense to drop truncate in favor of start/end.

I was not aware of this distinction.  I thought our discussion resulted in
a single decision which applied to all time ranges.  If that isn't the
case, as you say, I think it makes sense to consider tidying this up in
some way.  I do not support retaining this discrepancy as it currently
stands.

--
Tim Parenti