Issue#39 - Change timezone definition

[burnalting]

Change the timezone definition in LocationComplexType to be that of the timezone of the Location, rather than the possible timezones for that Location.

[at055612]

Addresses #39

[burnalting]

This change is to just change the comment and hence the element's usage, not the element(s) within LocationComplextType.

The thrust of this change is to allow one to easily establish the local time of the event (or rather of the device recording the event). The idea behind this is to allow one to determine if the event occurred during business hours, so happy to run with any outcome that meets this requirement.

I know we could technically use Lat/Long which is also part of LocationComplexType and perform some lookup, but it we were to store the current UTC offset of when the event occurred, we automatically know the event's relative time.

[at055612]

@burnalting please can you add a CHANGELOG entry and also check the docs to see if anything needs updating/adding for this change.

[stroomdev66]

For me the problem lies in the ability to lookup an offset. It would be awkward to use reference data as it isn't designed to be able to get offsets in real time, i.e. the reference data would have to be effective at the millisecond that the offset was to change and pre-exist before affected events arrive. It would also have to cover several locations in most cases.

Most systems can tell you the current time from the system clock but often have no clue what the offset is, or if they do they only know the offset at the source (event recording) location and not at the client etc.

Having locale descriptors as part of the location allows you to properly ascertain what offset including DST is relevant in that location.

[burnalting]

This change is providing the DST. The change is to make the TimeZone element the DST as per the comment

Timezone for location in ISO8601 Time zone designator format for the location at the time of the event. The format may be 'Z' for no offset from UTC, '+hh:mm', '+hhmm' or '+hh' for a positive offset from UTC in hours and minutes or just hours or '-hh:mm' or '-hhmm' or '-hh' for a negative offset from UTC in hours and minutes or just hours. Note that 'Z' can be represented as a positive zero offset from UTC i.e. '+00:00'

The current comment is basically saying that the TimeZone element is the location's Timezone pair (e.g. for Bristol UK, it would be +00:00/+01:00.

My change is on the basis that no-one has already used the TimeZone element in it's original intent.

[at055612]

If we go with @burnalting's change, which I think is ok, then the wording probably ought to make it clear that the offset applies at the event time and incorporates any active DST. Thus to determine the local time you would just apply the offset to the UTC event time. I am not sure we want to add a thing to say whether DST has been applied or not. If they give us an offset then it should be the offset they are currently operating under, which for uk would be Z or +01:00 depend on when the event happened.

For cases where the event generator doesn't know the local time/offset but does know where it was generated then maybe we need a some other element to hold the time zone name. There is no current ISO for this so the IANA timezone database would seem a suitable alternative. https://en.wikipedia.org/wiki/List_of_tz_database_time_zones https://www.iana.org/time-zones This would give us Europe/London, which is more useful than the +00:00/+01:00 that we have at the moment but would not give us anything about DST. Some enrichment logic would have combine this with the UTC event time and the tz database to come up with a local offset.

[burnalting]

@at055612 Have updated CHANGELOG

[burnalting]

Don't forget, there is a separate change to add State (or Provence/Shire), City and Town #40 so we already have geolocation that could be used for downstream processing.

@at055612 Does the annotation need to be more explicit? It does state it is the designator for the location at the time of the event. I could provide an example a'la So for example, an event occuring in Sydney, Australia at 2019-01-28T11:58:33.123Z would have a Timezone of +11:00 which indicates the localtime of the event is 2019-01-28T22:58:33.123 +11:00

[at055612]

For clarity I would change it to: (sentence added to the end, plus typo in occuring and localtime)

Timezone for location in ISO8601 Time zone designator format for the location at the time of the event. The format may be 'Z' for no offset from UTC, '+hh:mm', '+hhmm' or '+hh' for a positive offset from UTC in hours and minutes or just hours or '-hh:mm' or '-hhmm' or '-hh' for a negative offset from UTC in hours and minutes or just hours. Note that 'Z' can be represented as a positive zero offset from UTC i.e. '+00:00'. So for example, an event occurring in Sydney, Australia at 2019-01-28T11:58:33.123Z would have a Timezone of +11:00 which indicates the local time of the event is 2019-01-28T22:58:33.123 +11:00. The timezone includes any daylight saving adjustments active at the time of the event, e.g. an event happening in London, UK during the summer daylight saving period would be '+01:00', rather than 'Z' for winter.

Also if this is likely to be parsed we probably ought to stick a regex pattern on this to ensure a known format. It also makes it clear what is required/valid.
Z|[+-](?:2[0-3]|[01][0-9])(?::?[0-5][0-9])?

Thus to avoid a breaking change we could add what burn wants as a new element, like so

<xs:choice minOccurs="0" maxOccurs="1">
  <xs:element name="TimeZone" type="xs:string" minOccurs="1" maxOccurs="1">
    <xs:annotation>
      <xs:documentation>Timezone pair for location in RFC3339 time-numoffset format separated by a slash '/' character. The first offset is for the location's standard timezone and the second for the daylight savings timezone. For example, Bristol, UK would be +00:00/+01:00.</xs:documentation>
    </xs:annotation>
  </xs:element>
  <xs:element name="TimeZoneName" type="xs:string" minOccurs="1" maxOccurs="1">
    <xs:annotation>
      <xs:documentation>The timezone name as defined by the Timezone Database (https://www.iana.org/time-zones), e.g. 'Europe/London' or 'Australia/NSW'.</xs:documentation>
    </xs:annotation>
  </xs:element>
</xs:choice>
<xs:element name="EffectiveTimeZone" type="evt:TimeZoneOffsetSimpleType" minOccurs="0" maxOccurs="1">
  <xs:annotation>
    <xs:documentation>Timezone for location in ISO8601 Time zone designator format for the location at the time of the event. The format may be 'Z' for no offset from UTC, '+hh:mm', '+hhmm' or '+hh' for a positive offset from UTC in hours and minutes or just hours or '-hh:mm' or '-hhmm' or '-hh' for a negative offset from UTC in hours and minutes or just hours. Note that 'Z' can be represented as a positive zero offset from UTC i.e. '+00:00'. So for example, an event occurring in Sydney, Australia at 2019-01-28T11:58:33.123Z would have a Timezone of +11:00 which indicates the local time of the event is 2019-01-28T22:58:33.123 +11:00. The timezone includes any daylight saving adjustments active at the time of the event, e.g. an event happening in London, UK during the summer daylight saving period would be '+01:00', rather than 'Z' for winter.</xs:documentation>
  </xs:annotation>
</xs:element>
            ...

<xs:simpleType name="TimeZoneOffsetSimpleType">
  <xs:annotation>
    <xs:documentation>An ISO 8601 time zone designator, e.g. 'Z', '+01:00', '-1000', '+03', etc.</xs:documentation>
  </xs:annotation>
  <xs:restriction base="xs:string">
    <xs:pattern value="Z|[+-](?:2[0-3]|[01][0-9])(?::?[0-5][0-9])?"/>
  </xs:restriction>
</xs:simpleType>

[stroomdev10]

Lets go with this please

[at055612]

Made the change to @burnalting's branch so the PR is up to date.