Document timezone key

[vkrause]

No description provided.

[derhuerst]

Just because an endpoint returned e.g. a date+time with +02:00 offset, that does not mean that clients should always just display this value as-is. They should IMO have the possibility to compute the current local wall clock time for the endpoints main area of operation if they desire. Having the additional timezone information (note that this is different from timezone offset information), they can deliver more helpful UX, e.g. when travelling from one timezone to another, or during a DST switch.

This is why I think that, whenever it's possible to noninate a single timezone (identifier) for an endpoint, it should be put here.

[vkrause]

I agree, I was thinking too much about cross-timezone endpoints when writing that part.
Having looked a bit deeper into what we currently use this for there is actually an important part missing here: the timezone in which request times have to be specified in, which makes this required pretty much all the time.

Do we want to have that in two different properties (e.g. requestTimezone and resultTimezone), with the first one being mandatory for all protocols that don't allow specifying a timezone in the request (AFAIK that's all of them), while the latter is required for any endpoint that does not have any kind of timezone information in the results at all, and is recommended for any endpoint who only covers a single timezone?

I can't think of a case where both values would differ, but there are cases where results can be fully qualified (Navitia, OTP) and this the result timezone shouldn't be overridden.

We could also leave that to the client and fold both together in a single timezone property, which then would practically be mandatory for all endpoints.