Proposal: Add MODIFIED and pickup and drop-off types to GTFS-RT; experimentally deprecate SKIPPED

gtfs-realtime/proto/gtfs-realtime.proto

@@ -228,7 +228,22 @@ message TripUpdate {
 
       // The stop is skipped, i.e., the vehicle will not stop at this stop.
       // Arrival and departure are optional.
-      SKIPPED = 1;
+      // NOTE: This field is experimentally deprecated and users should consider using the
+      // experimental `MODIFIED` enum instead, which is intended to replace `SKIPPED` in favor of
+      // enabling more real-life scenarios to be represented, such as a vehicle that's running
+      // late being "drop-off only" to try and catch up back to schedule. In the future, it may be 
+      // decided to completely remove `SKIPPED`, such as by using `reserved` instead, should
+      // `MODIFIED` be officially adopted as the replacement. If `MODIFIED` is later deprecated,
+      // `SKIPPED` should be un-deprecated in order to re-signal that it's the primary mechanism
+      // for communicating that a vehicle will not serve a particular stop.
+      // In this interim period, users may continue to use this value for compatability.
+      // However, as per migration-modified.md, feed producers may choose to fully migrate
+      // to use the more detailed `pickup_type` and `drop_off_type`, with proper
+      // notification to feed consumers. To represent the same scenario, users
+      // should use `MODIFIED` along with pickup_type=NO_PICKUP and
+      // drop_off_type=NO_DROP_OFF instead for when a vehicle will not serve
+      // a regularly scheduled stop. 
+      SKIPPED = 1 [deprecated=true];
 
       // No StopTimeEvents are given for this stop.
       // The main intention for this value is to give time predictions only for
@@ -245,6 +260,14 @@ message TripUpdate {
       // NOTE: This field is still experimental, and subject to change. It may be
       // formally adopted in the future.
       UNSCHEDULED = 3;
+
+      // A schedule-based vehicle's StopTimeProperties differs from the static schedule in a way that impacts
+      // the rider experience, such as a vehicle not picking up passengers because a vehicle is "drop-off only"
+      // to catch up back to schedule when it's running late. StopTimeProperties must included to specify how
+      // the relationship has been modified.
+      // NOTE: This field is still experimental, and subject to change. It may be
+      // formally adopted in the future.
+      MODIFIED = 4; 
     }
     optional ScheduleRelationship schedule_relationship = 5
         [default = SCHEDULED];
@@ -267,6 +290,58 @@ 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;
 
+      // Supports real-time changes to pickup_type when it differs from what's specified in (CSV) GTFS
+      // in stop_times.txt. See definition of stop_times.pickup_type in (CSV) GTFS. 
+      // If pickup_type is specified, StopTimeUpdate.schedule_relationship must be MODIFIED for schedule-based service
+      // unless pickup_type=NO_PICKUP and drop_off_type=NO_DROP_OFF. Then, as per migration-modified.md,
+      // StopTimeUpdate.schedule_relationship may be SKIPPED in an interim period for compatability reasons. 
+      // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future.
+      optional PickupType pickup_type = 2;
+
+      // Supports real-time changes to drop_off_type when it differs from what's specified in (CSV) GTFS
+      // in stop_times.txt. See definition of stop_times.drop_off_type in (CSV) GTFS.
+      // If drop_off_type is specified, StopTimeUpdate.schedule_relationship must be MODIFIED for scheduled-based service
+      // unless drop_off_type=NO_DROP_OFF and pickup_type=NO_PICKUP. Then, as per migration-modified.md,
+      // StopTimeUpdate.schedule_relationship may be SKIPPED in an interim period for compatability reasons. 
+      // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future.
+      optional DropOffType drop_off_type = 3;
+
+      // Indicates the pickup method for an updated stop time when it differs from what's specified in (CSV) GTFS
+      // in stop_times.txt. By default, if pickup_type is neither specified in real-time or in (CSV) GTFS, it is
+      // considered REGULAR_PICKUP.
+      // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future.
+      enum PickupType {
+        // See definition of stop_times.pickup_type=0 in (CSV) GTFS.
+        REGULAR_PICKUP = 0;
+
+        // See definition of stop_times.pickup_type=1 in (CSV) GTFS.
+        NO_PICKUP = 1;
+
+        // See definition of stop_times.pickup_type=2 in (CSV) GTFS.
+        MUST_PHONE_AGENCY_PICKUP = 2;
+
+        // See definition of stop_times.pickup_type=3 in (CSV) GTFS.
+        MUST_ASK_DRIVER_PICKUP = 3;
+      }
+
+      // Indicates the drop off method for an updated stop time when it differs from what's specified in (CSV) GTFS
+      // in stop_times.txt. By default, if drop_off_type is neither specified in real-time or in (CSV) GTFS, it is
+      // considered REGULAR_DROP_OFF.
+      // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future.
+      enum DropOffType {
+        // See definition of stop_times.drop_off_type=0 in (CSV) GTFS.
+        REGULAR_DROP_OFF = 0;
+
+        // See definition of stop_times.drop_off_type=1 in (CSV) GTFS.
+        NO_DROP_OFF = 1;
+
+        // See definition of stop_times.drop_off_type=2 in (CSV) GTFS.
+        MUST_PHONE_AGENCY_DROP_OFF = 2;
+
+        // See definition of stop_times.drop_off_type=3 in (CSV) GTFS.
+        MUST_ASK_DRIVER_DROP_OFF = 3;
+      }
+
       // 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.

gtfs-realtime/spec/en/examples/migration-modified.md

@@ -0,0 +1,41 @@
+## Migration Guide - Transition from SKIPPED to MODIFIED
+
+The GTFS-realtime `StopTimeUpdate.schedule_relationship` of `SKIPPED` indicates that a vehicle will not be serving a particular stop that was originally scheduled as a part of `stop_times.txt` in GTFS-static.
+
+The GTFS-static `pickup_type` and `drop_off_type` fields within `stop_times.txt` allow an agency to specify details on what a rider needs to do in order to board/alight at a given stop (e.g. a rider must explicitly request a drop-off at a stop, otherwise the driver will skip the stop).
+
+This migration guide defines how existing producers who use the `SKIPPED` enumeration for indicating that vehicle will not stop at a given stop or as a best approximation of partial service at a stop can provide a more nuanced picture of the level of service through `pickup_type` and `drop_off_type` via `StopTimeProperties`. The goal is to minimize disruption to producers and consumers during the transition. 
+
+See the [Add pickup and drop-off types to GTFS-RT proposal on GitHub](https://github.com/google/transit/pull/265).
+
+### Initially providing SKIPPED and pickup_type / drop_off_type in same feed
+
+#### Producers
+
+If you are a producer who uses the `SKIPPED` enumeration for indicating that vehicle will not stop at a given stop or as a best approximation of partial service at a stop, it is recommended that you continue to produce `SKIPPED` entities for those stop time updates but also add `pickup_type` and `drop_off_type` entities for the same `StopTimeUpdate`, such as a `NO_PICKUP` and `NO_DROP_OFF` for a stop that's will not be made.
+
+Here's an example of indicating to consumers that a vehicle will be "drop-off only": 
+
+~~~
+entity {
+  id: "ei0"
+  trip_update {
+    ...
+    stop_time_update {
+      ...
+      schedule_relationship: SKIPPED
+
+      stop_time_properties {
+        pickup_type: NO_PICKUP
+        drop_off_type: MUST_ASK_DRIVER_DROP_OFF
+      }
+    }
+  }
+}
+~~~
+It is suggested that you notify existing consumers (e.g., via a developer mailing list) that the use of `SKIPPED` is being deprecated in favor of more nuanced information using `MODIFIED` by a set deadline and that consumers should start consuming the `MODIFIED` enumeration as well as `pickup_type` and `drop_off_type`. You should also provide a link to this migration guide. After the deadline passes, you can stop using `SKIPPED` entities for scenarios where `pickup_type` or `drop_off_type` are included and start using `MODIFIED` instead.
+
+#### Consumers 
+`pickup_type` and `drop_off_type` set in `StopTimeProperties` takes precedence over `schedule_relationship=SKIPPED`, meaning that real-time arrival information should still be used to inform passengers rather being ignored, perhaps with additional instructions or notification on how to board/alight, similar to what may happen with those fields being specified in `stop_times.txt`.
+
+In the future, instead of `SKIPPED`, as per above, you should expect `MODIFIED` instead, with `pickup_type=NO_PICKUP` and `drop_off_type=NO_DROP_OFF` in scenarios where a vehicle will entirely skip a scheduled stop.