Clarify implied timezone in stop_times.txt #378

tzujenchanmbd · 2023-05-17T18:10:48Z

The purpose of this PR is:

to clarify the usage of time zone for stop_times.arrival_time and stop_times.departure_time
to avoid producers providing time based on incorrect time zone
to prevent potential confusion that may arise after introduction of time-variable fares

Current definition on stop_times.arrival_time:

Arrival time at the stop (defined by stop_times.stop_id) for a specific trip (defined by stop_times.trip_id). If there are not separate times for arrival and departure at a stop, arrival_time and departure_time should be the same. For times occurring after midnight on the service day, enter the time as a value greater than 24:00:00 in HH:MM:SS local time for the day on which the trip schedule begins.

Problem (quoted from Elizabeth in #322):
The above definition, with use of the word "local" implies that stop_times.txt should use the time zone of the local stop. However, the stop.stop_timezone definition clearly states that if used, that stop_times should refer to agency.agency_timezone.

This problem caused Amtrak to provide incorrect data in 2022.

Proposed solution:
Clarify definition of time, stop_times.arrival_time, and stop_times.departure_time

Fixes issue#322 (see issue#322 for previous discussion)

Clarify implied timezone for time values at stop_times.arrival_time & stop_times.departure_time

Removed "local time" from Field Type: Time

google-cla · 2023-05-17T18:10:52Z

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

derhuerst · 2023-05-22T11:14:24Z

gtfs/spec/en/reference.md

@@ -76,7 +76,7 @@ Presence conditions applicable to fields and files:
 - **Float** - A floating point number.
 - **Integer** - An integer.
 - **Phone number** - A phone number.
- **Time** - Time in the HH:MM:SS format (H:MM:SS is also accepted). The time is measured from "noon minus 12h" of the service day (effectively midnight except for days on which daylight savings time changes occur). For times occurring after midnight, enter the time as a value greater than 24:00:00 in HH:MM:SS local time for the day on which the trip schedule begins. <br> *Example: `14:30:00` for 2:30PM or `25:35:00` for 1:35AM on the next day.*
+- **Time** - Time in the HH:MM:SS format (H:MM:SS is also accepted). The time is measured from "noon minus 12h" of the service day (effectively midnight except for days on which daylight savings time changes occur). For times occurring after midnight, enter the time as a value greater than 24:00:00 in HH:MM:SS for the day on which the trip schedule begins. <br> *Example: `14:30:00` for 2:30PM or `25:35:00` for 1:35AM on the next day.*


Because we're already changing this definition, I propose another related change:
I'd argue that the "for the day on which the trip schedule begins" part confuses more than it helps. I think we should either a) state (again here as before) that the time is relative to the service day, or b) don't add any alternative phrase as a GTFS "Time" is always relative to the service day.
Same below in the {arrival,departure}_time definitions.

@derhuerst what about the following definition?

Time - Time in the HH:MM:SS format (H:MM:SS is also accepted). The time is measured from "noon minus 12h" of the service day (effectively midnight except for days on which daylight savings time changes occur). For times occurring after midnight on the service day, enter the time as a value greater than 24:00:00 in HH:MM:SS. [remove "for the day on which the trip schedule begins"]

Sounds good.

github-actions · 2023-06-15T00:17:39Z

This pull request has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

leonardehrenfried · 2023-06-15T05:57:50Z

I think this is a good change and would welcome further discussion and an eventual merge.

comment from derhuerst - google#378 (comment)

tzujenchanmbd · 2023-07-24T15:10:05Z

It looks like the proposal does not raise other concerns. I’m opening a vote on this PR. This vote is for modifying description in Timefield type, stop_times.arrival_time, and stop_times.departure_time, as outlined in the first comment.

Please vote with a +1 (for) or -1 (against) in the comments. Voting ends on 2023-07-31 at 23:59:59 UTC.

npaun · 2023-07-24T19:01:11Z

+1 Transit

leonardehrenfried · 2023-07-25T07:36:51Z

+1 OpenTripPlanner

skinkie · 2023-07-25T07:43:00Z

I would want to make it even more explicit by adding ", not the stop.timezone".

Add "not stops.stop_timezone" for both departure_time and arrival_time

tzujenchanmbd · 2023-07-25T18:02:22Z

@skinkie thanks for the suggestion!
Added ", not stops.stop_timezone" for both arrival_time and departure_time. - 9d4e426

e-lo · 2023-07-25T18:46:06Z

+1

doconnoronca · 2023-07-26T01:10:28Z

+1 TransSee

westontrillium · 2023-07-26T16:01:36Z

+1 Trillium

albanpeignier · 2023-07-27T08:48:16Z

+1 enRoute

tzujenchanmbd · 2023-08-01T16:06:04Z

The vote passed on 2023-07-31 at 23:59:59 UTC.

6 votes in favour and no votes against.

The votes came from:
Transit (@npaun)
OpenTripPlanner (@leonardehrenfried)
Elizabeth Sall (@e-lo)
TransSee (@doconnoronca)
Trillium (@westontrillium)
enRoute (@albanpeignier)

Thanks to everyone who contributed and voted! (Special thanks to @e-lo for bringing up the issue in 2022!)
We are in the process of updating the GTFS Schedule Reference page on gtfs.org.

* arri/dept time updates Clarify implied timezone for time values at stop_times.arrival_time & stop_times.departure_time * Removed "local time" Removed "local time" from Field Type: Time * Remove "for the day on which the trip schedule begins" comment from derhuerst - google#378 (comment) * Add "not stops.stop_timezone" Add "not stops.stop_timezone" for both departure_time and arrival_time

tzujenchanmbd added 2 commits May 17, 2023 11:21

arri/dept time updates

b643235

Clarify implied timezone for time values at stop_times.arrival_time & stop_times.departure_time

Removed "local time"

2a74dc0

Removed "local time" from Field Type: Time

emmambd linked an issue May 17, 2023 that may be closed by this pull request

Clarify implied timezone for time values in stop_times.txt #322

Closed

derhuerst reviewed May 22, 2023

View reviewed changes

npaun mentioned this pull request May 31, 2023

Add variable fares by time or day #357

Merged

github-actions bot added the stale label Jun 15, 2023

github-actions bot removed the stale label Jun 16, 2023

derhuerst mentioned this pull request Jun 19, 2023

ignore stop_timezone when calculating arrivals/departures public-transport/gtfs-via-postgres#38

Merged

tzujenchanmbd added the GTFS Schedule Issues and Pull Requests that focus on GTFS Schedule label Jun 28, 2023

Remove "for the day on which the trip schedule begins"

53de1aa

comment from derhuerst - google#378 (comment)

tzujenchanmbd added the Status: Voting Pull Requests where the advocate has called for a vote as described in the changes.md label Jul 24, 2023

Add "not stops.stop_timezone"

9d4e426

Add "not stops.stop_timezone" for both departure_time and arrival_time

isabelle-dr mentioned this pull request Jul 27, 2023

Update revision history #390

Merged

4 tasks

tzujenchanmbd removed the Status: Voting Pull Requests where the advocate has called for a vote as described in the changes.md label Aug 1, 2023

tzujenchanmbd merged commit 8c57342 into google:master Aug 1, 2023
2 checks passed

emmambd mentioned this pull request Aug 1, 2023

Fast Travel Between Far Stops not using stops.stop_timezone MobilityData/gtfs-validator#1110

Open

isabelle-dr added the Change: Clarification Revisions of the current specification to improve understanding. label Feb 19, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Clarify implied timezone in stop_times.txt #378

Clarify implied timezone in stop_times.txt #378

tzujenchanmbd commented May 17, 2023 •

edited

google-cla bot commented May 17, 2023

derhuerst May 22, 2023 •

edited

tzujenchanmbd Jul 3, 2023

derhuerst Jul 12, 2023

github-actions bot commented Jun 15, 2023

leonardehrenfried commented Jun 15, 2023

tzujenchanmbd commented Jul 24, 2023 •

edited

npaun commented Jul 24, 2023

leonardehrenfried commented Jul 25, 2023

skinkie commented Jul 25, 2023

tzujenchanmbd commented Jul 25, 2023

e-lo commented Jul 25, 2023

doconnoronca commented Jul 26, 2023

westontrillium commented Jul 26, 2023

albanpeignier commented Jul 27, 2023

tzujenchanmbd commented Aug 1, 2023

Clarify implied timezone in stop_times.txt #378

Clarify implied timezone in stop_times.txt #378

Conversation

tzujenchanmbd commented May 17, 2023 • edited

google-cla bot commented May 17, 2023

derhuerst May 22, 2023 • edited

Choose a reason for hiding this comment

tzujenchanmbd Jul 3, 2023

Choose a reason for hiding this comment

derhuerst Jul 12, 2023

Choose a reason for hiding this comment

github-actions bot commented Jun 15, 2023

leonardehrenfried commented Jun 15, 2023

tzujenchanmbd commented Jul 24, 2023 • edited

npaun commented Jul 24, 2023

leonardehrenfried commented Jul 25, 2023

skinkie commented Jul 25, 2023

tzujenchanmbd commented Jul 25, 2023

e-lo commented Jul 25, 2023

doconnoronca commented Jul 26, 2023

westontrillium commented Jul 26, 2023

albanpeignier commented Jul 27, 2023

tzujenchanmbd commented Aug 1, 2023

tzujenchanmbd commented May 17, 2023 •

edited

derhuerst May 22, 2023 •

edited

tzujenchanmbd commented Jul 24, 2023 •

edited