Specify the behaviour of TripUpdate.schedule_relationship = ADDED, and un-deprecate REPLACEMENT

gtfs-realtime/best-practices/best-practices.md

@@ -71,10 +71,6 @@ If separate `VehiclePosition` and `TripUpdate` feeds are provided, [TripDescript
 
 For example, a `VehiclePosition` entity has `vehicle_id:A` and `trip_id:4`, then the corresponding `TripUpdate` entity should also have `vehicle_id:A` and `trip_id:4`.
 
-| Field Name | Recommendation |
-| --- | --- |
-| `schedule_relationship` | The behavior of `ADDED` trips are unspecified and the use of this enumeration is not recommended. |
-
 ### VehicleDescriptor
 
 If separate `VehiclePosition` and `TripUpdate` feeds are provided, [TripDescriptor](#TripDescriptor) and [VehicleDescriptor](#VehicleDescriptor) ID values pairing should match between the two feeds.

gtfs-realtime/proto/gtfs-realtime.proto

@@ -190,6 +190,11 @@ message TripUpdate {
     // To specify a completely certain prediction, set its uncertainty to 0.
     optional int32 uncertainty = 3;
 
+    // Scheduled time for an added or replacement trip.
+    // In Unix time (i.e., number of seconds since January 1st 1970 00:00:00
+    // UTC).
+    optional int64 scheduled_time = 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.
@@ -272,13 +277,36 @@ message TripUpdate {
       // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future.
       optional string assigned_stop_id = 1;
 
+      // The updated headsign of the vehicle at the stop.
+      optional string stop_headsign = 2;
+
+      // The updated pickup of the vehicle at the stop.
+      optional DropOffPickupType pickup_type = 3;
+
+      // The updated drop off of the vehicle at the stop.
+      optional DropOffPickupType drop_off_type = 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;
+
+      enum DropOffPickupType {
+        // Regularly scheduled pickup/dropoff.
+        REGULAR = 0;
+
+        // No pickup/dropoff available
+        NONE = 1;
+
+        // Must phone agency to arrange pickup/dropoff.
+        PHONE_AGENCY = 2;
+
+        // Must coordinate with driver to arrange pickup/dropoff.
+        COORDINATE_WITH_DRIVER = 3;
+      }
     }
 
     // Realtime updates for certain properties defined within GTFS stop_times.txt
@@ -379,6 +407,14 @@ message TripUpdate {
     // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future. 
     optional string shape_id = 4;
 
+    // Specifies the headsign for this trip when it differs from the original.
+    // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future.
+    optional string trip_headsign = 5;
+
+    // Specifies the name for this trip when it differs from the original.
+    // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future.
+    optional string trip_short_name = 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.
@@ -793,13 +829,7 @@ message TripDescriptor {
     // enough to the scheduled trip to be associated with it.
     SCHEDULED = 0;
 
-    // An extra trip that was added in addition to a running schedule, for
-    // example, to replace a broken vehicle or to respond to sudden passenger
-    // load.
-    // NOTE: Currently, behavior is unspecified for feeds that use this mode. There are discussions on the GTFS GitHub
-    // [(1)](https://github.com/google/transit/issues/106) [(2)](https://github.com/google/transit/pull/221)
-    // [(3)](https://github.com/google/transit/pull/219) around fully specifying or deprecating ADDED trips and the
-    // documentation will be updated when those discussions are finalized.
+    // An extra trip unrelated to any existing trips, for example, to respond to sudden passenger load.
     ADDED = 1;
 
     // A trip that is running with no schedule associated to it (GTFS frequencies.txt exact_times=0).
@@ -809,17 +839,18 @@ message TripDescriptor {
     // A trip that existed in the schedule but was removed.
     CANCELED = 3;
 
-    // Should not be used - for backwards-compatibility only.
-    REPLACEMENT = 5 [deprecated = true];
+    // A trip that replaces an existing trip in the schedule.
+    REPLACEMENT = 5;
 
     // An extra trip that was added in addition to a running schedule, for example, to replace a broken vehicle or to
     // respond to sudden passenger load. Used with TripUpdate.TripProperties.trip_id, TripUpdate.TripProperties.start_date,
     // and TripUpdate.TripProperties.start_time to copy an existing trip from static GTFS but start at a different service
     // date and/or time. Duplicating a trip is allowed if the service related to the original trip in (CSV) GTFS
     // (in calendar.txt or calendar_dates.txt) is operating within the next 30 days. The trip to be duplicated is
     // identified via TripUpdate.TripDescriptor.trip_id. This enumeration does not modify the existing trip referenced by
-    // TripUpdate.TripDescriptor.trip_id - if a producer wants to cancel the original trip, it must publish a separate
-    // TripUpdate with the value of CANCELED or DELETED. Trips defined in GTFS frequencies.txt with exact_times that is
+    // TripUpdate.TripDescriptor.trip_id - if a producer wants to replace the original trip, a value of `REPLACEMENT` should be used instead.
+    //
+    // Trips defined in GTFS frequencies.txt with exact_times that is
     // empty or equal to 0 cannot be duplicated. The VehiclePosition.TripDescriptor.trip_id for the new trip must contain
     // the matching value from TripUpdate.TripProperties.trip_id and VehiclePosition.TripDescriptor.ScheduleRelationship
     // must also be set to DUPLICATED.
@@ -864,8 +895,8 @@ message TripDescriptor {
     extensions 9000 to 9999;
   }
 
-  // Linkage to any modifications done to this trip (shape changes, removal or addition of stops). 
-  // If this field is provided, the `trip_id`, `route_id`, `direction_id`, `start_time`, `start_date` fields of the `TripDescriptor` MUST be left empty, to avoid confusion by consumers that aren't looking for the `ModifiedTripSelector` value. 
+  // Linkage to any modifications done to this trip (shape changes, removal or addition of stops).
+  // If this field is provided, the `trip_id`, `route_id`, `direction_id`, `start_time`, `start_date` fields of the `TripDescriptor` MUST be left empty, to avoid confusion by consumers that aren't looking for the `ModifiedTripSelector` value.
   optional ModifiedTripSelector modified_trip = 7;
 
   // The extensions namespace allows 3rd-party developers to extend the
@@ -1134,7 +1165,7 @@ message TripModifications {
   }
 
   message SelectedTrips {
-    // A list of trips affected with this replacement that all have the same new `shape_id`.
+    // A list of trips affected with this replacement that all have the same new `shape_id`. A `TripUpdate` with `schedule_relationship=REPLACEMENT` must not already exist for the trip.
     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.