GTFS Trip-Modifications (#403)

* Add Trip-Modification, make shape non-experimental

Fix typo

Add images

Update image width

Add newlines

Add newlines

Update images

Italic for image description

Update SLO

travel_time_to_stop is optional

Proto : all feild optional

Add references to GTFS-Static

* Create a page for TripModifications entities for consistency with TU and VP

* Clarify providing TUs for modified trips and ReplacementStop time interpolation

Less strong requirement to interpolate

* Fix first_stop_reference.png not having the right image + optimize image size.

* Fix optional/require for Stop message

* Clarify behaviour and linkage to TripUpdates

* Apply Modification clarification proposed changes

Co-authored-by: Paul Swartz <[email protected]>

* Use ModifiedTripSelector instead of concatenation of IDs

Update langage

Update namign

* Add details on behavior when  is provided

* Remove modifications_id

* Fix after comments from @bdferris-v2

* Add note about producer needed the two versions of trip updates

* Fix bad relationship mentionned, + force no other entity when using ModifiedTripSelector

* Changes after Jan 10 call

* Add experimental notices

* Remove mention of stop pattern

* Use stop selector instead of stop sequence only

* Update to end_stop_selector

* Update proto with start/end stop selector

* Add selected trips

* Update reference with SelectedTrips

* Update trip modif doc

* Add last_modified_time

* Add missing start_times in pb

* Fix typos, fix description of selected trips

* Fix typos

Co-authored-by: Nicholas Paun <[email protected]>

* Update reference for clarity

* Clarify and remove duplicated information

* Consistancy

* Revert correctly shape experimental

* Editorial, formatting clarifications

* Apply suggestions from @sam-hickey-ibigroup

Co-authored-by: Sam Hickey <[email protected]>

* Update documentation images with new fields, add source files

* Clarifies behavior of propagated_modification_delay when no stop_time is cancelled

* Remove extra word

* Sync .proto and reference files

---------

Co-authored-by: Nicholas Paun <[email protected]>
Co-authored-by: Paul Swartz <[email protected]>
Co-authored-by: Nicholas Paun <[email protected]>
Co-authored-by: Joshua Fabian <[email protected]>
Co-authored-by: Sam Hickey <[email protected]>

gtfs-realtime/proto/gtfs-realtime.proto

@@ -106,6 +106,8 @@ message FeedEntity {
 
   // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future.
   optional Shape shape = 6;
+  optional Stop stop = 7;
+  optional TripModifications trip_modifications = 8;
 
   // The extensions namespace allows 3rd-party developers to extend the
   // GTFS Realtime Specification in order to add and evaluate new features and
@@ -840,6 +842,15 @@ message TripDescriptor {
   }
   optional ScheduleRelationship schedule_relationship = 4;
 
+  message ModifiedTripSelector {
+    // The 'id' from the FeedEntity in which the contained TripModifications object affects this trip.
+    optional string modifications_id = 1;
+
+    // The trip_id from the GTFS feed that is modified by the modifications_id
+    optional string affected_trip_id = 2;
+  }
+  optional ModifiedTripSelector modified_trip = 7;
+
   // The extensions namespace allows 3rd-party developers to extend the
   // GTFS Realtime Specification in order to add and evaluate new features and
   // modifications to the spec.
@@ -1033,3 +1044,148 @@ message Shape {
   // The following extension IDs are reserved for private use by any organization.
   extensions 9000 to 9999;
 }
+
+// Describes a stop which is served by trips. All fields are as described in the GTFS-Static specification.
+// NOTE: This message is still experimental, and subject to change. It may be formally adopted in the future.
+message Stop {
+  enum WheelchairBoarding {
+    UNKNOWN = 0;
+    AVAILABLE = 1;
+    NOT_AVAILABLE = 2;
+   }
+
+  optional string stop_id = 1;
+  optional TranslatedString stop_code = 2;
+  optional TranslatedString stop_name = 3;
+  optional TranslatedString tts_stop_name = 4;
+  optional TranslatedString stop_desc = 5;
+  optional float stop_lat = 6;
+  optional float stop_lon = 7;
+  optional string zone_id = 8;
+  optional TranslatedString stop_url = 9;
+  optional string parent_station = 11;
+  optional string stop_timezone = 12;
+  optional WheelchairBoarding wheelchair_boarding = 13 [default = UNKNOWN];
+  optional string level_id = 14;
+  optional TranslatedString platform_code = 15;
+
+  // The extensions namespace allows 3rd-party developers to extend the
+  // GTFS Realtime Specification in order to add and evaluate new features and
+  // modifications to the spec.
+  extensions 1000 to 1999;
+
+  // The following extension IDs are reserved for private use by any organization.
+  extensions 9000 to 9999;
+}
+
+// NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future.
+message TripModifications {
+  // A `Modification` message replaces a span of n stop times from each affected trip starting at `start_stop_selector`.
+  message Modification {
+    // The stop selector of the first stop_time of the original trip that is to be affected by this modification.
+    // Used in conjuction with `end_stop_selector`. 
+    // `start_stop_selector` is required and is used to define the reference stop used with `travel_time_to_stop`.
+    optional StopSelector start_stop_selector = 1;
+
+    // The stop selector of the last stop of the original trip that is to be affected by this modification. 
+    // The selection is inclusive, so if only one stop_time is replaced by that modification, `start_stop_selector` and `end_stop_selector` must be equivalent.
+    // If no stop_time is replaced, `end_stop_selector` must not be provided. It's otherwise required.
+    optional StopSelector end_stop_selector = 2;
+
+    // The number of seconds of delay to add to all departure and arrival times following the end of this modification. 
+    // If multiple modifications apply to the same trip, the delays accumulate as the trip advances. 
+    optional int32 propagated_modification_delay = 3 [default = 0];
+
+    // A list of replacement stops, replacing those of the original trip. 
+    // The length of the new stop times may be less, the same, or greater than the number of replaced stop times. 
+    repeated ReplacementStop replacement_stops = 4;
+
+    // An `id` value from the `FeedEntity` message that contains the `Alert` describing this Modification for user-facing communication.
+    optional string service_alert_id = 5;
+
+    // This timestamp identifies the moment when the modification has last been changed.
+    // In POSIX time (i.e., number of seconds since January 1st 1970 00:00:00 UTC).
+    optional uint64 last_modified_time = 6;
+
+    // The extensions namespace allows 3rd-party developers to extend the
+    // GTFS Realtime Specification in order to add and evaluate new features and
+    // modifications to the spec.
+    extensions 1000 to 1999;
+
+    // The following extension IDs are reserved for private use by any organization.
+    extensions 9000 to 9999;
+  }
+
+  message SelectedTrips {
+    // A list of trips affected with this replacement that all have the same new `shape_id`.
+    repeated string trip_ids = 1;
+    // The ID of the new shape for the modified trips in this SelectedTrips.
+    // May refer to a new shape added using a GTFS-RT Shape message, or to an existing shape defined in the GTFS-Static feed’s shapes.txt.
+    optional string shape_id = 2;
+
+    // The extensions namespace allows 3rd-party developers to extend the
+    // GTFS Realtime Specification in order to add and evaluate new features and
+    // modifications to the spec.
+    extensions 1000 to 1999;
+
+    // The following extension IDs are reserved for private use by any organization.
+    extensions 9000 to 9999;
+}
+
+   // A list of selected trips affected by this TripModifications.
+  repeated SelectedTrips selected_trips = 1;
+
+  // A list of start times in the real-time trip descriptor for the trip_id defined in trip_ids. 
+  // Useful to target multiple departures of a trip_id in a frequency-based trip.
+  repeated string start_times = 2;
+
+  // Dates on which the modifications occurs, in the YYYYMMDD format. Producers SHOULD only transmit detours occurring within the next week.
+  // The dates provided should not be used as user-facing information, if a user-facing start and end date needs to be provided, they can be provided in the linked service alert with `service_alert_id`
+  repeated string service_dates = 3;
+
+  // A list of modifications to apply to the affected trips. 
+  repeated Modification modifications = 4; 
+
+  // The extensions namespace allows 3rd-party developers to extend the
+  // GTFS Realtime Specification in order to add and evaluate new features and
+  // modifications to the spec.
+  extensions 1000 to 1999;
+
+  // The following extension IDs are reserved for private use by any organization.
+  extensions 9000 to 9999;
+}
+
+// NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future.
+// Select a stop by stop sequence or by stop_id. At least one of the two values must be provided.
+message StopSelector { 
+  // Must be the same as in stop_times.txt in the corresponding GTFS feed.
+  optional uint32 stop_sequence = 1;
+  // Must be the same as in stops.txt in the corresponding GTFS feed.
+  optional string stop_id = 2;
+
+  // The extensions namespace allows 3rd-party developers to extend the
+  // GTFS Realtime Specification in order to add and evaluate new features and
+  // modifications to the spec.
+  extensions 1000 to 1999;
+
+  // The following extension IDs are reserved for private use by any organization.
+  extensions 9000 to 9999;
+}
+
+// NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future.
+message ReplacementStop {
+  // The difference in seconds between the arrival time at this stop and the arrival time at the reference stop. The reference stop is the stop prior to start_stop_selector. If the modification begins at the first stop of the trip, then the first stop of the trip is the reference stop.
+  // This value MUST be monotonically increasing and may only be a negative number if the first stop of the original trip is the reference stop.
+  optional int32 travel_time_to_stop = 1;
+
+  // The replacement stop ID which will now be visited by the trip. May refer to a new stop added using a GTFS-RT Stop message, or to an existing stop defined in the GTFS-Static feed’s stops.txt. The stop MUST have location_type=0 (routable stops).
+  optional string stop_id = 2;
+
+  // The extensions namespace allows 3rd-party developers to extend the
+  // GTFS Realtime Specification in order to add and evaluate new features and
+  // modifications to the spec.
+  extensions 1000 to 1999;
+
+  // The following extension IDs are reserved for private use by any organization.
+  extensions 9000 to 9999;
+}

gtfs-realtime/spec/en/README.md

@@ -17,6 +17,7 @@ The specification currently supports the following types of information:
 *   **Trip updates** - delays, cancellations, changed routes
 *   **Service alerts** - stop moved, unforeseen events affecting a station, route or the entire network
 *   **Vehicle positions** - information about the vehicles including location and congestion level
+*   **Trip modifications** - information about detours affecting a set of trips
 
 A feed may, although not required to, combine entities of different types. Feeds are served via HTTP and updated frequently. The file itself is a regular binary file, so any type of webserver can host and serve the file (other transfer protocols might be used as well). Alternatively, web application servers could also be used which as a response to a valid HTTP GET request will return the feed. There are no constraints on how frequently nor on the exact method of how the feed should be updated or retrieved.
 

gtfs-realtime/spec/en/feed-entities.md

@@ -46,6 +46,18 @@ use data on current speed and odometer readings from the vehicle.
 
 [More about Vehicle Position updates...](vehicle-positions.md)
 
+## Trip Modifications
+
+#### "These trips are affected by a detour on certain days"
+
+Trip modifications are used to describe detours which affect a set of trips. 
+
+A trip modification can cancel certain stops, adjust the timing for trips, 
+provide a new shape that trips will take and provide the location of temporary
+stops along the way.
+
+[More about Trip Modifications...](trip-modifications.md)
+
 ## Historical remark on feed types
 
 Early versions of GTFS Realtime Specification required each feed to only contain

gtfs-realtime/spec/en/images/README.md

@@ -0,0 +1,5 @@
+# Documentation images
+
+## Excalidraw files
+
+Files with the `.excalidraw` extension can be opened and edited with https://excalidraw.com