v90 - Draft proposal - Propagating delays across trips in same block

gtfs-realtime/spec/en/trip-updates.md

@@ -25,6 +25,10 @@ For each [StopTimeUpdate](reference.md#StopTimeUpdate), the default schedule rel
 
 If one or more stops are missing along the trip the update is propagated to all subsequent stops. This means that updating a stop time for a certain stop will change all subsequent stops in the absence of any other information.
 
+Delay values (including both a [`StopTimeEvent.delay`](reference.md#message-stoptimeevent) as well as delays calculated by applying a [`StopTimeEvent.time`](reference.md#message-stoptimeevent)) to the schedule in [GTFS `stop_times.txt`](/gtfs/spec/en/reference.md#stop_timestxt) greater than or equal to `0` (vehicles running late or on time) must be propagated across trips within the same block (defined by [GTFS trips.txt block_id](/gtfs/spec/en/reference.md#tripstxt)).  If there is a layover in between Trips A and B (e.g., a 5 minute difference between the Trip A final stop `arrival_time` and the Trip B first stop `departure_time`) and no real-time `delay` or `time` information is provided for the Trip B stops, consumers should subtract the layover time from any delay values from Trip A before propagating the delay to Trip B.  This means that consumers will, in the absence of real-time information for Trip B, assume that if the vehicle is running late it will skip it's scheduled layover time and depart on Trip B as soon as it reaches the stop to catch up to the schedule.  If the vehicle is running late on Trip A but plans to hold for the entire scheduled layover time before starting Trip B, producers must represent this by providing [StopTimeUpdates](reference.md#StopTimeUpdate) on Trip B while the vehicle is serving Trip A so riders waiting for Trip B can see that there will be an extended delay. 
+
+Delay values less than `0` (i.e., vehicles running early) must be propagated across trips in the same block if there is no layover between Trip A and Trip B. If there is difference between the Trip A final stop `arrival_time` and the Trip B first stop `departure_time`, then consumers must assume that the vehicle will hold after finishing Trip A and will start Trip B on time. Producers must indicate if a vehicles is departing early on Trip B by explicitly providing a [StopTimeEvent](reference.md#StopTimeEvent) for Trip B while Trip A is being served by the vehicle.
+
 **Example 1**
 
 For a trip with 20 stops, a [StopTimeUpdate](reference.md#StopTimeUpdate) with arrival delay and departure delay of 0 ([StopTimeEvents](reference.md#StopTimeEvent)) for stop_sequence of the current stop means that the trip is exactly on time.
@@ -44,6 +48,88 @@ This will be interpreted as:
 *   stop_sequences 8,9 have delay of 60 seconds.
 *   stop_sequences 10,..,20 have unknown delay.
 
+**Example 3**
+
+Trip A and Trip B belong to the same block (specified in [GTFS trips.txt](/gtfs/spec/en/reference.md#tripstxt) via `block_id`).
+
+Trip A has a single [StopTimeUpdates](reference.md#StopTimeUpdate):
+
+*   delay of 300 seconds
+
+Trip B has no [StopTimeUpdates](reference.md#StopTimeUpdate).
+
+Trip A final stop `arrival_time` and the Trip B first stop `departure_time` are the same.
+
+This will be interpreted as:
+
+* Trip B stop_sequence 1 has a delay of 300 seconds
+
+**Example 4**
+
+Trip A and Trip B belong to the same block (specified in [GTFS trips.txt](/gtfs/spec/en/reference.md#tripstxt) via `block_id`).
+
+Trip A has a single [StopTimeUpdates](reference.md#StopTimeUpdate):
+
+*   delay of 300 seconds
+
+Trip B has no [StopTimeUpdates](reference.md#StopTimeUpdate).
+
+Trip A final stop `arrival_time` and the Trip B first stop `departure_time` differ by 300 seconds.
+
+This will be interpreted as:
+
+* Trip B stop_sequence 1 has a delay of 0 seconds (trip is on time, as the layover time will be entirely skipped)
+
+**Example 5**
+
+Trip A and Trip B belong to the same block (specified in [GTFS trips.txt](/gtfs/spec/en/reference.md#tripstxt) via `block_id`).
+
+Trip A has a single [StopTimeUpdates](reference.md#StopTimeUpdate):
+
+*   delay of 300 seconds
+
+Trip B has no [StopTimeUpdates](reference.md#StopTimeUpdate).
+
+Trip A final stop `arrival_time` and the Trip B first stop `departure_time` differ by 200 seconds.
+
+This will be interpreted as:
+
+* Trip B stop_sequence 1 has a delay of 100 seconds (trip is still late, but the layover absorbed 200 seconds of the delay)
+
+**Example 6**
+
+Trip A and Trip B belong to the same block (specified in [GTFS trips.txt](/gtfs/spec/en/reference.md#tripstxt) via `block_id`).
+
+Trip A has a single [StopTimeUpdates](reference.md#StopTimeUpdate):
+
+*   delay of 300 seconds
+
+Trip B has no [StopTimeUpdates](reference.md#StopTimeUpdate).
+
+Trip A final stop `arrival_time` and the Trip B first stop `departure_time` differ by 400 seconds.
+
+This will be interpreted as:
+
+* Trip B stop_sequence 1 has a delay of 0 seconds (trip is on time, as the layover time will absorb the delay and the vehicle will still have 100 seconds of the scheduled layover time remaining)
+
+**Example 7**
+
+Trip A and Trip B belong to the same block (specified in [GTFS trips.txt](/gtfs/spec/en/reference.md#tripstxt) via `block_id`).
+
+Trip A has a single [StopTimeUpdates](reference.md#StopTimeUpdate):
+
+*   delay of 300 seconds
+
+Trip B has a single [StopTimeUpdates](reference.md#StopTimeUpdate):
+
+*   delay of 300 seconds
+
+Trip A final stop `arrival_time` and the Trip B first stop `departure_time` differ by 300 seconds.
+
+This will be interpreted as:
+
+* Trip B stop_sequence 1 has a delay of 300 seconds (layover time will not be skipped because the producer explicitly provided the delay for Trip B)
+
 ### Trip Descriptor
 
 The information provided by the trip descriptor depends on the schedule relationship of trip you are updating. There are a number of options for you to set: