Deprecate TripUpdate.schedule_relationship = ADDED, add TripUpdate.schedule_relationship = NEW / REPLACEMENT to specify new / replaced trips which do not run on a schedule from the GTFS static.

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

@@ -271,6 +271,28 @@ message TripUpdate {
       // (e.g., `VehiclePosition.stop_id`).
       // 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 updated timing point status of the vehicle at the stop. 
+      // If false, the vehicle will no longer wait at the stop; 
+      // if true, the vehicle will wait until the scheduled time at the stop.
+      optional bool timepoint = 5;
+
+      // Identifies the boarding booking rule at this stop time. 
+      // Refers to a `booking_rule_id` defined in the GTFS `booking_rules.txt`.
+      optional string pickup_booking_rule_id = 6;
+
+      // Identifies the alighting booking rule at this stop time. 
+      // Refers to a `booking_rule_id` defined in the GTFS `booking_rules.txt`.
+      optional string drop_off_booking_rule_id = 7;
 
       // The extensions namespace allows 3rd-party developers to extend the
       // GTFS Realtime Specification in order to add and evaluate new features
@@ -279,6 +301,20 @@ message TripUpdate {
 
       // 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
@@ -378,6 +414,18 @@ message TripUpdate {
     // be marked as schedule_relationship=SKIPPED.
     // 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;
+
+    // Specifies the block 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 block_id = 7;
 
     // The extensions namespace allows 3rd-party developers to extend the
     // GTFS Realtime Specification in order to add and evaluate new features
@@ -793,13 +841,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 +851,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.
@@ -1117,7 +1160,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.