Subject: [Tzdist] Comments on timezone-service-11 sections 1 thru 4

From: Paul Eggert <[email-masked]>
Date: Wed, 20 Aug 2014 16:00:24 -0700

Here are some comments on sections 1 through 4 of 
draft-douglass-timezone-service-11.  I understand that you're planning 
to change the spelling of "timezone" to "time zone"; this change sounds 
reasonable, but to help keep the spelling issue separate these comments 
use the current spelling "timezone".

A.  The draft uses the word "timezone" in a technical sense that 
disagrees with its ordinary use, and this should be explained.  In 
ordinary usage "timezone" means something like Central European Time or 
East Africa Time, a usage that's not what's in the draft.  I suggest 
starting Section 1.2's glossary with this definition:

    Timezone:  A description of the historical and predicted timekeeping 
practices of a collection of clocks that are intended to agree;

and appending something like the following paragraph to the glossary:

    Note that the term "timezone" does not have the common meaning of a 
region of the world at a specific UTC offset, possibly modified by 
daylight saving time.  For example, the Central European Time zone may 
correspond to several timezones "Europe/Berlin", "Europe/Paris", etc., 
because subregions have kept time differently in the past.

B.  Section 1.2's definition of "Timezone Data" should mention other 
information that may be part of that data.  I suggest appending the 
following text: ", and which may include other information such as time 
zone abbreviations".

C.  Section 3.2's discussion of timezone aliases would seem to prohibit 
context-dependent aliases.  I don't see why they should be prohibited. 
To make the issue clearer I suggest appending the following paragraph to 
Section 3.2:

    The set of aliases may vary depending on the client and on whether 
timezone data is truncated (see Section 3.4).  For example, a client 
located in Michigan may see "US/Eastern" as an alias for 
"America/Detroit" whereas a client in New Jersey may see it as an alias 
for "America/New_York", and all three names may be aliases if timezones 
are truncated to post-2013 data.

D.  Section 3.3's discussion of localized names does not clearly 
distinguish them from the common practice of using abbreviations like 
"EST" for Eastern Standard Time.  To help clarify this I suggest 
appending something like the following paragraph:

    A localized name is a name for a timezone, and is distinct from 
abbreviations commonly used for UTC offsets within a timezone.  For 
example, the timezone "America/New_York" may have the localized name 
"Nueva York" in a Spanish locale, as distinct from the abbreviations 
"EST" and "EDT" which may or may not have their own localizations.

E.  Section 3.4 talks about truncation as if it applied only to past 
data, but it also applies to the future.  For example, the tz database 
currently truncates the data for "Asia/Tehran" after 2037, because 
Iran's actual rules are based on the Persian calendar and cannot be 
expressed compactly in tz format (or in VTIMEZONE format, I presume). 
Worse, some rules are based on astronomical calendars and therefore 
cannot be predicted into the indefinite future.  Because the server 
cannot represent all the future data, it must truncate.  I'm not sure 
how to fix all this, but here's a draft of a replacement for Section 3.4 
that may suggest one way to go:

    Timezones and daylight saving times rules have been in use for over 
a century, and in some timezones it is not practical to represent rules 
into the indefinite future.  Timezone data can thus contain a large 
amount of historical or predicted information that may not be relevant 
for a particular server's intended clients.  Calendaring and scheduling 
clients are likely most concerned with timezone data that covers a 
period near the present, as users typically only create new events for 
the present and near future. To avoid having to send unnecessary data, 
servers are allowed to truncate timezone data at some appropriate date 
in the past or the future or both, and provide accurate offsets and 
rules only for times within the non-truncated interval.  To simplify the 
set of data a server needs to support, truncation always occurs at the 
start of a year, i.e., the year's first midnight for the timezone's 
local time.

    When truncating a "VTIMEZONE" component that crosses a truncation 
boundary, the server MUST adjust it so that appears to be at the start 
or at the end of the published interval, and its response MUST advertise 
the truncation dates used.

F.  Section 4.1.3's definition of "substantive" change is too strict. 
For example, the tz database's 2014f release changed Australian time 
zone abbreviations and for some applications this change could 
reasonablyb be considered "substantive".  I suggest loosening the 
definition by using the following wording instead:

    Any change that affects the calculated UTC offsets for a timezone is 
a "substantive" change.  Other changes, such as changes to descriptions, 
may be treated as "substantive" changes.

G.  Sorry, I don't understand the last sentence of section 4.1.6.  Is 
the string "invalid-action" a placeholder for a number that will be used 
in a later draft?

H.  I suggest removing the last paragraph of section 4.2.3 for two 
reasons.  First, there is a provision for handling deleted timezones, 
namely, retrieve the database without using "changedsince".  Second, it 
is not bad practice to delete timezones.  For example, tzdata's release 
2014f deleted the zone Asia/Harbin (replacing it with a 
backward-compatibility alias) as its data turned out to have been 
largely imaginary.

---

From: Lester Caine <[email-masked]>
Date: Thu, 21 Aug 2014 00:37:08 +0100

> the string "invalid-action" a placeholder for a number that will be used

I get that one ... Just as actions produce different formats of data
message, errors are returned either as response codes or as a JSON error
package - section 7.4 There are other error strings against each action,
but obviously an unsupported action needs it's error documented here?

Some actions return iCalendar packages and others return JSON packages.

Just seems a mess?

-- 
Lester Caine - G8HFL
-----------------------------
Contact - http://lsces.co.uk/wiki/?page=contact
L.S.Caine Electronic Services - http://lsces.co.uk
EnquirySolve - http://enquirysolve.com/
Model Engineers Digital Workshop - http://medw.co.uk
Rainbow Digital Media - http://rainbowdigitalmedia.co.uk

---

From: Ken Murchison <[email-masked]>
Date: Wed, 20 Aug 2014 20:58:35 -0400

> Some actions return iCalendar packages and others return JSON packages.

I disagree.  All response bodies in this protocol are JSON with the 
exception of the response to a get action, which can be whatever 
supported format the client requests (defaulting to iCalendar).  As with 
any other HTTP-based protocol, success and errors are signaled using 
HTTP response codes.  In the case of errors, this protocol provides more 
detailed info on the error in a structured JSON response body.  Seems 
pretty simple and straightforward to me.

-- 
Kenneth Murchison
Principal Systems Software Engineer
Carnegie Mellon University

---

From: Lester Caine <[email-masked]>
Date: Thu, 21 Aug 2014 09:44:16 +0100

> pretty simple and straightforward to me.

It's not so obvious when one is coming to this cold ;)

So actually what we are missing is the JSON definition for a get return,
which could then follow the format of the other returns with a dtstamp
for consistency? I think I've identified what I was  missing below ...

Again still on a learning curve here ... why is there no provision to
return at least 'expand' as an icalendar format list? I can see how the
capabilities can be expanded, but it seems to me if there is an option
to return XML or iCalendar in addition to a base of JSON then all
functions should provision that rather than having to add those details
outside the core specification?

CalDAV and iCalendar are data consumers, and just need a subset of data,
in the right format, appropriate to there applications. Building a
mirror server is not particularly bothered by the format of how the data
is transferred, but for scalability and speed of propagating changes the
function I am looking to create for the base tz data as an 'update'
function that will only pass those timeoneid's which have changes and if
those changes will affect already archived data. Even current day
scheduling needs the ability to identify and report short notice changes
to DST activity which there have been several examples of already in the
past few months. The 'changedsince' action buried in expand SHOULD also
be an integral part of 'get' for server updates?

In the case of a 'light' consumer where the local diary has recorded a
meeting for next week, if the user accesses that data and uses a new
lookup on the tzdist, the dtstamp may flag that there has been a change
but identifying if that change has affected the current lookup would be
difficult locally. In this case I am not sure if the 'changedsince' is
sufficient, but I think it can be used with the right workflow. Kicking
out the '304 HTTP' at least identifies there is no need to do anything
and the server just needs a fast way of calculating that.

---

From: Ken Murchison <[email-masked]>
Date: Thu, 21 Aug 2014 08:05:37 -0400

> for consistency? I think I've identified what I was  missing below ...

A client can certainly request format=application/calendar+json if it 
wants a JSON response.  In either case, the server will return an ETag 
which the client can use in a conditional request to see if the timezone 
data has changed.

> outside the core specification?

Interesting idea.  This would have to be iCalendar using just RDATEs and 
not RRULEs, since the point of expand is for the server to expand 
recurrences, not the client.  I don't know if this is any better than 
the existing JSON response.

> be an integral part of 'get' for server updates?

Updating a secondary server is covered in section 4.1.3 
<http://tools.ietf.org/html/draft-douglass-timezone-service-11#section-4.1.3> 
of the draft.  The secondary requests the list of timezones that have 
changedsince its last update and then fetches them with get actions.

> and the server just needs a fast way of calculating that.

In this case, if the client had a done previous expansion around the 
given date, it could use the ETag from that response and do a 
conditional expand request with the same parameters, which will either 
result in a 304 (nothing changed) or a 200 with the updated set of 
occurrences.