From 2faa3df62f9204aefd8a7a378589a15ffca6295c Mon Sep 17 00:00:00 2001 From: Eric Ouyang Date: Mon, 22 Mar 2021 18:06:28 -0700 Subject: [PATCH 01/16] Add pick-up and drop-off types --- gtfs-realtime/proto/gtfs-realtime.proto | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/gtfs-realtime/proto/gtfs-realtime.proto b/gtfs-realtime/proto/gtfs-realtime.proto index d6ce28e29..5d6a6520a 100644 --- a/gtfs-realtime/proto/gtfs-realtime.proto +++ b/gtfs-realtime/proto/gtfs-realtime.proto @@ -260,6 +260,27 @@ 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; + // Indicates pickup method. + optional PickupType pickup_type = 2 [default = REGULAR_PICKUP]; + // Indicates drop off method. + optional DropOffType drop_off_type = 3 [default = REGULAR_DROP_OFF]; + + // Valid options for pickup_type: + enum PickupType { + REGULAR_PICKUP = 0; + NO_PICKUP = 1; + MUST_PHONE_AGENCY_PICKUP = 2; + MUST_ASK_DRIVER_PICKUP = 3; + } + + // Valid options for drop_off_type: + enum DropOffType { + REGULAR_DROP_OFF = 0; + NO_DROP_OFF = 1; + MUST_PHONE_AGENCY_DROP_OFF = 2; + 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. From b28420bffc5d06c67751b56173eabd70ab87900f Mon Sep 17 00:00:00 2001 From: Eric Ouyang Date: Tue, 23 Mar 2021 08:30:21 -0700 Subject: [PATCH 02/16] Update documentation --- gtfs-realtime/proto/gtfs-realtime.proto | 27 +++++++++++++++++---- gtfs-realtime/spec/en/reference.md | 32 +++++++++++++++++++++++++ 2 files changed, 55 insertions(+), 4 deletions(-) diff --git a/gtfs-realtime/proto/gtfs-realtime.proto b/gtfs-realtime/proto/gtfs-realtime.proto index 5d6a6520a..c58f0e901 100644 --- a/gtfs-realtime/proto/gtfs-realtime.proto +++ b/gtfs-realtime/proto/gtfs-realtime.proto @@ -260,24 +260,43 @@ 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; - // Indicates pickup method. + // See definition of stop_times.pickup_type in (CSV) GTFS. Default is REGULAR_PICKUP. + // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future. optional PickupType pickup_type = 2 [default = REGULAR_PICKUP]; - // Indicates drop off method. + + // See definition of stop_times.drop_off_type in (CSV) GTFS. Default is REGULAR_DROP_OFF. + // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future. optional DropOffType drop_off_type = 3 [default = REGULAR_DROP_OFF]; - // Valid options for pickup_type: + // Indicates the pickup method for an updated stop time. Default is 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; } - // Valid options for drop_off_type: + // Indicates the drop off method for an updated stop time. Default is 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; } diff --git a/gtfs-realtime/spec/en/reference.md b/gtfs-realtime/spec/en/reference.md index 19b136372..f9c2f2e7b 100644 --- a/gtfs-realtime/spec/en/reference.md +++ b/gtfs-realtime/spec/en/reference.md @@ -213,6 +213,38 @@ Realtime update for certain properties defined within GTFS stop_times.txt. | _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ | |------------------|------------|----------------|-------------------|-------------------| | **assigned_stop_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | Supports real-time stop assignments. Refers to a `stop_id` defined in the GTFS `stops.txt`.
The new `assigned_stop_id` should not result in a significantly different trip experience for the end user than the `stop_id` defined in GTFS `stop_times.txt`. In other words, the end user should not view this new `stop_id` as an "unusual change" if the new stop was presented within an app without any additional context. For example, this field is intended to be used for platform assignments by using a `stop_id` that belongs to the same station as the stop originally defined in GTFS `stop_times.txt`.
To assign a stop without providing any real-time arrival or departure predictions, populate this field and set `StopTimeUpdate.schedule_relationship = NO_DATA`.
If this field is populated, `StopTimeUpdate.stop_sequence` must be populated and `StopTimeUpdate.stop_id` should not be populated. Stop assignments should be reflected in other GTFS-realtime fields as well (e.g., `VehiclePosition.stop_id`).

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | +| **pickup_type** | [PickupType](#enum-pickuptype) | Optional | One | See definition of stop_times.pickup_type in (CSV) GTFS. Default is REGULAR_PICKUP.

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | +| **drop_off_type** | [DropOffType](#enum-dropofftype) | Optional | One | See definition of stop_times.drop_off_type in (CSV) GTFS. Default is REGULAR_DROP_OFF.

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | + +## _enum_ PickupType + +Indicates the pickup method for an updated stop time. Default is REGULAR_PICKUP. + +**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. + +#### Values + +| _**Value**_ | _**Comment**_ | +|-------------|---------------| +| **REGULAR_PICKUP** | See definition of stop_times.pickup_type=0 in (CSV) GTFS. | +| **NO_PICKUP** | See definition of stop_times.pickup_type=1 in (CSV) GTFS. | +| **MUST_PHONE_AGENCY_PICKUP** | See definition of stop_times.pickup_type=2 in (CSV) GTFS. | +| **MUST_ASK_DRIVER_PICKUP** | See definition of stop_times.pickup_type=3 in (CSV) GTFS. | + +## _enum_ DropOffType + +Indicates the drop off method for an updated stop time. Default is REGULAR_DROP_OFF. + +**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. + +#### Values + +| _**Value**_ | _**Comment**_ | +|-------------|---------------| +| **REGULAR_DROP_OFF** | See definition of stop_times.drop_off_type=0 in (CSV) GTFS. | +| **NO_DROP_OFF** | See definition of stop_times.drop_off_type=1 in (CSV) GTFS. | +| **MUST_PHONE_AGENCY_DROP_OFF** | See definition of stop_times.drop_off_type=2 in (CSV) GTFS. | +| **MUST_ASK_DRIVER_DROP_OFF** | See definition of stop_times.drop_off_type=3 in (CSV) GTFS. | ## _message_ TripProperties From 898c1a3edb98018466ec47b253372f558dffa4d9 Mon Sep 17 00:00:00 2001 From: Eric Ouyang Date: Fri, 26 Mar 2021 11:22:55 -0700 Subject: [PATCH 03/16] Document TripUpdates V3 --- gtfs-realtime/proto/gtfs-realtime.proto | 3 ++- gtfs-realtime/spec/en/reference.md | 6 ++++-- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/gtfs-realtime/proto/gtfs-realtime.proto b/gtfs-realtime/proto/gtfs-realtime.proto index c58f0e901..3a4bfb41f 100644 --- a/gtfs-realtime/proto/gtfs-realtime.proto +++ b/gtfs-realtime/proto/gtfs-realtime.proto @@ -54,7 +54,8 @@ message FeedMessage { // Metadata about a feed, included in feed messages. message FeedHeader { // Version of the feed specification. - // The current version is 2.0. Valid versions are "2.0", "1.0". + // The current version is 2.0. Valid versions are "3.0", "2.0", "1.0". + // NOTE: Version 3.0 is still experimental, and subject to change. It may be formally adopted in the future. required string gtfs_realtime_version = 1; // Determines whether the current fetch is incremental. Currently, diff --git a/gtfs-realtime/spec/en/reference.md b/gtfs-realtime/spec/en/reference.md index f9c2f2e7b..38556bb5a 100644 --- a/gtfs-realtime/spec/en/reference.md +++ b/gtfs-realtime/spec/en/reference.md @@ -1,6 +1,8 @@ A GTFS Realtime feed lets transit agencies provide consumers with realtime information about disruptions to their service (stations closed, lines not operating, important delays, etc.) location of their vehicles, and expected arrival times. -Version 2.0 of the feed specification is discussed and documented on this site. Valid versions are "2.0", "1.0". +Version 3.0 of the feed specification is discussed and documented on this site. The current version is 2.0. Valid versions are "3.0", "2.0", "1.0". + +Note: Version 3.0 is still experimental, and subject to change. It may be formally adopted in the future. ### Term Definitions @@ -92,7 +94,7 @@ Metadata about a feed, included in feed messages. | _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ | |------------------|------------|----------------|-------------------|-------------------| -| **gtfs_realtime_version** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Required | One | Version of the feed specification. The current version is 2.0. | +| **gtfs_realtime_version** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Required | One | Version of the feed specification. The current version is 2.0. Valid versions are "3.0", "2.0", "1.0".

**Caution:** Version 3.0 is still **experimental**, and subject to change. It may be formally adopted in the future. | | **incrementality** | [Incrementality](#enum-incrementality) | Required | One | | **timestamp** | [uint64](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Required | One | This timestamp identifies the moment when the content of this feed has been created (in server time). In POSIX time (i.e., number of seconds since January 1st 1970 00:00:00 UTC). To avoid time skew between systems producing and consuming realtime information it is strongly advised to derive timestamp from a time server. It is completely acceptable to use Stratum 3 or even lower strata servers since time differences up to a couple of seconds are tolerable. | From 9a57863683335ac35a9453c795120106b0cb6a4d Mon Sep 17 00:00:00 2001 From: Eric Ouyang Date: Tue, 24 Aug 2021 10:53:58 -0700 Subject: [PATCH 04/16] Revert "Document TripUpdates V3" This reverts commit 898c1a3edb98018466ec47b253372f558dffa4d9. --- gtfs-realtime/proto/gtfs-realtime.proto | 3 +-- gtfs-realtime/spec/en/reference.md | 6 ++---- 2 files changed, 3 insertions(+), 6 deletions(-) diff --git a/gtfs-realtime/proto/gtfs-realtime.proto b/gtfs-realtime/proto/gtfs-realtime.proto index 3a4bfb41f..c58f0e901 100644 --- a/gtfs-realtime/proto/gtfs-realtime.proto +++ b/gtfs-realtime/proto/gtfs-realtime.proto @@ -54,8 +54,7 @@ message FeedMessage { // Metadata about a feed, included in feed messages. message FeedHeader { // Version of the feed specification. - // The current version is 2.0. Valid versions are "3.0", "2.0", "1.0". - // NOTE: Version 3.0 is still experimental, and subject to change. It may be formally adopted in the future. + // The current version is 2.0. Valid versions are "2.0", "1.0". required string gtfs_realtime_version = 1; // Determines whether the current fetch is incremental. Currently, diff --git a/gtfs-realtime/spec/en/reference.md b/gtfs-realtime/spec/en/reference.md index 38556bb5a..f9c2f2e7b 100644 --- a/gtfs-realtime/spec/en/reference.md +++ b/gtfs-realtime/spec/en/reference.md @@ -1,8 +1,6 @@ A GTFS Realtime feed lets transit agencies provide consumers with realtime information about disruptions to their service (stations closed, lines not operating, important delays, etc.) location of their vehicles, and expected arrival times. -Version 3.0 of the feed specification is discussed and documented on this site. The current version is 2.0. Valid versions are "3.0", "2.0", "1.0". - -Note: Version 3.0 is still experimental, and subject to change. It may be formally adopted in the future. +Version 2.0 of the feed specification is discussed and documented on this site. Valid versions are "2.0", "1.0". ### Term Definitions @@ -94,7 +92,7 @@ Metadata about a feed, included in feed messages. | _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ | |------------------|------------|----------------|-------------------|-------------------| -| **gtfs_realtime_version** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Required | One | Version of the feed specification. The current version is 2.0. Valid versions are "3.0", "2.0", "1.0".

**Caution:** Version 3.0 is still **experimental**, and subject to change. It may be formally adopted in the future. | +| **gtfs_realtime_version** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Required | One | Version of the feed specification. The current version is 2.0. | | **incrementality** | [Incrementality](#enum-incrementality) | Required | One | | **timestamp** | [uint64](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Required | One | This timestamp identifies the moment when the content of this feed has been created (in server time). In POSIX time (i.e., number of seconds since January 1st 1970 00:00:00 UTC). To avoid time skew between systems producing and consuming realtime information it is strongly advised to derive timestamp from a time server. It is completely acceptable to use Stratum 3 or even lower strata servers since time differences up to a couple of seconds are tolerable. | From bf8bfa7488524da00dc3d32838d52f1574426c67 Mon Sep 17 00:00:00 2001 From: Eric Ouyang Date: Tue, 24 Aug 2021 20:50:16 -0700 Subject: [PATCH 05/16] Add migration approach --- gtfs-realtime/proto/gtfs-realtime.proto | 26 +++++++++--- .../spec/en/examples/migration-modified.md | 40 +++++++++++++++++++ gtfs-realtime/spec/en/reference.md | 10 +++-- gtfs-realtime/spec/en/trip-updates.md | 4 +- 4 files changed, 68 insertions(+), 12 deletions(-) create mode 100644 gtfs-realtime/spec/en/examples/migration-modified.md diff --git a/gtfs-realtime/proto/gtfs-realtime.proto b/gtfs-realtime/proto/gtfs-realtime.proto index c58f0e901..10cc6ad38 100644 --- a/gtfs-realtime/proto/gtfs-realtime.proto +++ b/gtfs-realtime/proto/gtfs-realtime.proto @@ -238,6 +238,12 @@ message TripUpdate { // NOTE: This field is still experimental, and subject to change. It may be // formally adopted in the future. UNSCHEDULED = 3; + + // The vehicle's relationship with the static schedule differs 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. + MODIFIED = 4; } optional ScheduleRelationship schedule_relationship = 5 [default = SCHEDULED]; @@ -260,15 +266,21 @@ 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; - // See definition of stop_times.pickup_type in (CSV) GTFS. Default is REGULAR_PICKUP. + // 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 should be MODIFIED. // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future. - optional PickupType pickup_type = 2 [default = REGULAR_PICKUP]; + optional PickupType pickup_type = 2; - // See definition of stop_times.drop_off_type in (CSV) GTFS. Default is REGULAR_DROP_OFF. + // 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 should be MODIFIED. // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future. - optional DropOffType drop_off_type = 3 [default = REGULAR_DROP_OFF]; + optional DropOffType drop_off_type = 3; - // Indicates the pickup method for an updated stop time. Default is REGULAR_PICKUP. + // 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. @@ -284,7 +296,9 @@ message TripUpdate { MUST_ASK_DRIVER_PICKUP = 3; } - // Indicates the drop off method for an updated stop time. Default is REGULAR_DROP_OFF. + // 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. diff --git a/gtfs-realtime/spec/en/examples/migration-modified.md b/gtfs-realtime/spec/en/examples/migration-modified.md new file mode 100644 index 000000000..73b7d1775 --- /dev/null +++ b/gtfs-realtime/spec/en/examples/migration-modified.md @@ -0,0 +1,40 @@ +## 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 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 as a best approximation of partial service at a stop, to avoid disruption to existing consumers, 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`. + +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` for partial service at a stop is being deprecated in favor of more nuanced information 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_typ` 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`. \ No newline at end of file diff --git a/gtfs-realtime/spec/en/reference.md b/gtfs-realtime/spec/en/reference.md index f9c2f2e7b..ccdbcd709 100644 --- a/gtfs-realtime/spec/en/reference.md +++ b/gtfs-realtime/spec/en/reference.md @@ -201,6 +201,7 @@ The relation between this StopTime and the static schedule. | **SKIPPED** | The stop is skipped, i.e., the vehicle will not stop at this stop. Arrival and departure are optional. When set `SKIPPED` is not propagated to subsequent stops in the same trip (i.e., the vehicle will stop at subsequent stops in the trip unless those stops also have a `stop_time_update` with `schedule_relationship: SKIPPED`). Delay from a previous stop in the trip *does* propagate over the `SKIPPED` stop. In other words, if a `stop_time_update` with an `arrival` or `departure` prediction is not set for a stop after the `SKIPPED` stop, the prediction upstream of the `SKIPPED` stop will be propagated to the stop after the `SKIPPED` stop and subsequent stops in the trip until a `stop_time_update` for a subsequent stop is provided. | | **NO_DATA** | No data is given for this stop. It indicates that there is no realtime information available. When set NO_DATA is propagated through subsequent stops so this is the recommended way of specifying from which stop you do not have realtime information. When NO_DATA is set neither arrival nor departure should be supplied. | | **UNSCHEDULED** | The vehicle is operating a frequency-based trip (GTFS frequencies.txt with exact_times = 0). This value should not be used for trips that are not defined in GTFS frequencies.txt, or trips in GTFS frequencies.txt with exact_times = 1. Trips containing `stop_time_updates` with `schedule_relationship: UNSCHEDULED` must also set the TripDescriptor `schedule_relationship: UNSCHEDULED`

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. +| **MODIFIED** | The vehicle's relationship with the static schedule differs 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.

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. ## _message_ StopTimeProperties @@ -213,12 +214,13 @@ Realtime update for certain properties defined within GTFS stop_times.txt. | _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ | |------------------|------------|----------------|-------------------|-------------------| | **assigned_stop_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | Supports real-time stop assignments. Refers to a `stop_id` defined in the GTFS `stops.txt`.
The new `assigned_stop_id` should not result in a significantly different trip experience for the end user than the `stop_id` defined in GTFS `stop_times.txt`. In other words, the end user should not view this new `stop_id` as an "unusual change" if the new stop was presented within an app without any additional context. For example, this field is intended to be used for platform assignments by using a `stop_id` that belongs to the same station as the stop originally defined in GTFS `stop_times.txt`.
To assign a stop without providing any real-time arrival or departure predictions, populate this field and set `StopTimeUpdate.schedule_relationship = NO_DATA`.
If this field is populated, `StopTimeUpdate.stop_sequence` must be populated and `StopTimeUpdate.stop_id` should not be populated. Stop assignments should be reflected in other GTFS-realtime fields as well (e.g., `VehiclePosition.stop_id`).

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | -| **pickup_type** | [PickupType](#enum-pickuptype) | Optional | One | See definition of stop_times.pickup_type in (CSV) GTFS. Default is REGULAR_PICKUP.

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | -| **drop_off_type** | [DropOffType](#enum-dropofftype) | Optional | One | See definition of stop_times.drop_off_type in (CSV) GTFS. Default is REGULAR_DROP_OFF.

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | +| **pickup_type** | [PickupType](#enum-pickuptype) | Optional | One | 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` should be `MODIFIED`.

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | +| **drop_off_type** | [DropOffType](#enum-dropofftype) | Optional | One | 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` should be `MODIFIED`. +

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | ## _enum_ PickupType -Indicates the pickup method for an updated stop time. Default is REGULAR_PICKUP. +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. **Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. @@ -233,7 +235,7 @@ Indicates the pickup method for an updated stop time. Default is REGULAR_PICKUP. ## _enum_ DropOffType -Indicates the drop off method for an updated stop time. Default is REGULAR_DROP_OFF. +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. **Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. diff --git a/gtfs-realtime/spec/en/trip-updates.md b/gtfs-realtime/spec/en/trip-updates.md index ec45bee66..8556e131f 100644 --- a/gtfs-realtime/spec/en/trip-updates.md +++ b/gtfs-realtime/spec/en/trip-updates.md @@ -23,11 +23,11 @@ Each [StopTimeUpdate](reference.md#StopTimeUpdate) is linked to a stop. Ordinari The update can provide a exact timing for **arrival** and/or **departure** at a stop in [StopTimeUpdates](reference.md#StopTimeUpdate) using [StopTimeEvent](reference.md#StopTimeEvent). This should contain either an absolute **time** or a **delay** (i.e. an offset from the scheduled time in seconds). Delay can only be used in case the trip update refers to a scheduled GTFS trip, as opposed to a frequency-based trip. In this case, time should be equal to scheduled time + delay. You may also specify **uncertainty** of the prediction along with [StopTimeEvent](reference.md#StopTimeEvent), which is discussed in more detail in section [Uncertainty](#uncertainty) further down the page. -For each [StopTimeUpdate](reference.md#StopTimeUpdate), the default schedule relationship is **scheduled**. (Note that this is different from the schedule relationship for the trip). You may change this to **skipped** if the stop will not be stopped at, or **no data** if you only have realtime data for some of the trip. +For each [StopTimeUpdate](reference.md#StopTimeUpdate), the default schedule relationship is **scheduled**. (Note that this is different from the schedule relationship for the trip). You may change this to **skipped** if the stop will not be stopped at, **modified** if stop time properties are different than what's specified in `stop_times.txt`, or **no data** if you only have realtime data for some of the trip. **Updates should be sorted by stop_sequence** (or stop_ids in the order they occur in the trip). -If one or more stops are missing along the trip the `delay` from the update (or, if only `time` is provided in the update, a delay computed by comparing the `time` against the GTFS schedule time) 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. Note that updates with a schedule relationship of `SKIPPED` will not stop delay propagation, but updates with schedule relationships of `SCHEDULED` (also the default value if schedule relationship is not provided) or `NO_DATA` will. +If one or more stops are missing along the trip the `delay` from the update (or, if only `time` is provided in the update, a delay computed by comparing the `time` against the GTFS schedule time) 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. Note that updates with a schedule relationship of `SKIPPED` or `MODIFIED` will not stop delay propagation, but updates with schedule relationships of `SCHEDULED` (also the default value if schedule relationship is not provided) or `NO_DATA` will. **Example 1** From 591ddd88ab14979372cb30dc9e882019903c38df Mon Sep 17 00:00:00 2001 From: ericouyang Date: Wed, 25 Aug 2021 07:56:21 -0700 Subject: [PATCH 06/16] Fix typo Co-authored-by: Paul Swartz --- gtfs-realtime/spec/en/examples/migration-modified.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gtfs-realtime/spec/en/examples/migration-modified.md b/gtfs-realtime/spec/en/examples/migration-modified.md index 73b7d1775..3ebdf92d1 100644 --- a/gtfs-realtime/spec/en/examples/migration-modified.md +++ b/gtfs-realtime/spec/en/examples/migration-modified.md @@ -34,7 +34,7 @@ entity { } ~~~ -It is suggested that you notify existing consumers (e.g., via a developer mailing list) that the use of `SKIPPED` for partial service at a stop is being deprecated in favor of more nuanced information 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_typ` are included and start using `MODIFIED` instead. +It is suggested that you notify existing consumers (e.g., via a developer mailing list) that the use of `SKIPPED` for partial service at a stop is being deprecated in favor of more nuanced information 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`. \ No newline at end of file From 16e412f7b7c8ec498e8a9e7f0fd7c8128bd9a9e9 Mon Sep 17 00:00:00 2001 From: Eric Ouyang Date: Wed, 25 Aug 2021 11:23:58 -0700 Subject: [PATCH 07/16] Update language to adhere to RFC 2119 --- gtfs-realtime/proto/gtfs-realtime.proto | 4 ++-- gtfs-realtime/spec/en/reference.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/gtfs-realtime/proto/gtfs-realtime.proto b/gtfs-realtime/proto/gtfs-realtime.proto index 10cc6ad38..f7a7476df 100644 --- a/gtfs-realtime/proto/gtfs-realtime.proto +++ b/gtfs-realtime/proto/gtfs-realtime.proto @@ -268,13 +268,13 @@ message TripUpdate { // 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 should be MODIFIED. + // If pickup_type is specified, StopTimeUpdate.schedule_relationship must be MODIFIED for schedule-based service. // 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 should be MODIFIED. + // If drop_off_type is specified, StopTimeUpdate.schedule_relationship must be MODIFIED for scheduled-based service. // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future. optional DropOffType drop_off_type = 3; diff --git a/gtfs-realtime/spec/en/reference.md b/gtfs-realtime/spec/en/reference.md index ccdbcd709..849fdbcd5 100644 --- a/gtfs-realtime/spec/en/reference.md +++ b/gtfs-realtime/spec/en/reference.md @@ -214,8 +214,8 @@ Realtime update for certain properties defined within GTFS stop_times.txt. | _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ | |------------------|------------|----------------|-------------------|-------------------| | **assigned_stop_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | Supports real-time stop assignments. Refers to a `stop_id` defined in the GTFS `stops.txt`.
The new `assigned_stop_id` should not result in a significantly different trip experience for the end user than the `stop_id` defined in GTFS `stop_times.txt`. In other words, the end user should not view this new `stop_id` as an "unusual change" if the new stop was presented within an app without any additional context. For example, this field is intended to be used for platform assignments by using a `stop_id` that belongs to the same station as the stop originally defined in GTFS `stop_times.txt`.
To assign a stop without providing any real-time arrival or departure predictions, populate this field and set `StopTimeUpdate.schedule_relationship = NO_DATA`.
If this field is populated, `StopTimeUpdate.stop_sequence` must be populated and `StopTimeUpdate.stop_id` should not be populated. Stop assignments should be reflected in other GTFS-realtime fields as well (e.g., `VehiclePosition.stop_id`).

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | -| **pickup_type** | [PickupType](#enum-pickuptype) | Optional | One | 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` should be `MODIFIED`.

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | -| **drop_off_type** | [DropOffType](#enum-dropofftype) | Optional | One | 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` should be `MODIFIED`. +| **pickup_type** | [PickupType](#enum-pickuptype) | Optional | One | 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.

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | +| **drop_off_type** | [DropOffType](#enum-dropofftype) | Optional | One | 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 schedule-based service.

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | ## _enum_ PickupType From c47559435fe729e8cae18bb44146f1b474112f1f Mon Sep 17 00:00:00 2001 From: Eric Ouyang Date: Wed, 25 Aug 2021 13:56:01 -0700 Subject: [PATCH 08/16] Address PR feedback --- gtfs-realtime/proto/gtfs-realtime.proto | 10 ++++++---- gtfs-realtime/spec/en/reference.md | 4 ++-- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/gtfs-realtime/proto/gtfs-realtime.proto b/gtfs-realtime/proto/gtfs-realtime.proto index f7a7476df..572a6df5b 100644 --- a/gtfs-realtime/proto/gtfs-realtime.proto +++ b/gtfs-realtime/proto/gtfs-realtime.proto @@ -239,10 +239,12 @@ message TripUpdate { // formally adopted in the future. UNSCHEDULED = 3; - // The vehicle's relationship with the static schedule differs 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. + // 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 diff --git a/gtfs-realtime/spec/en/reference.md b/gtfs-realtime/spec/en/reference.md index 849fdbcd5..c3d70f738 100644 --- a/gtfs-realtime/spec/en/reference.md +++ b/gtfs-realtime/spec/en/reference.md @@ -184,8 +184,8 @@ The update is linked to a specific stop either through stop_sequence or stop_id, |------------------|------------|----------------|-------------------|-------------------| | **stop_sequence** | [uint32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Conditionally required | One | Must be the same as in stop_times.txt in the corresponding GTFS feed. Either stop_sequence or stop_id must be provided within a StopTimeUpdate - both fields cannot be empty. stop_sequence is required for trips that visit the same stop_id more than once (e.g., a loop) to disambiguate which stop the prediction is for. If `StopTimeProperties.assigned_stop_id` is populated, then `stop_sequence` must be populated. | | **stop_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Conditionally required | One | Must be the same as in stops.txt in the corresponding GTFS feed. Either stop_sequence or stop_id must be provided within a StopTimeUpdate - both fields cannot be empty. If `StopTimeProperties.assigned_stop_id` is populated, it is preferred to omit `stop_id` and use only `stop_sequence`. If `StopTimeProperties.assigned_stop_id` and `stop_id` are populated, `stop_id` must match `assigned_stop_id`. | -| **arrival** | [StopTimeEvent](#message-stoptimeevent) | Conditionally required | One | If schedule_relationship is empty or SCHEDULED, either arrival or departure must be provided within a StopTimeUpdate - both fields cannot be empty. arrival and departure may both be empty when schedule_relationship is SKIPPED. If schedule_relationship is NO_DATA, arrival and departure must be empty. | -| **departure** | [StopTimeEvent](#message-stoptimeevent) | Conditionally required | One | If schedule_relationship is empty or SCHEDULED, either arrival or departure must be provided within a StopTimeUpdate - both fields cannot be empty. arrival and departure may both be empty when schedule_relationship is SKIPPED. If schedule_relationship is NO_DATA, arrival and departure must be empty. | +| **arrival** | [StopTimeEvent](#message-stoptimeevent) | Conditionally required | One | If schedule_relationship is empty or SCHEDULED, either arrival or departure must be provided within a StopTimeUpdate - both fields cannot be empty. arrival and departure may both be empty when schedule_relationship is SKIPPED or if only `StopTimeProperties` is being updated when schedule_relationship is MODIFIED but no real-time timing is available. If schedule_relationship is NO_DATA, arrival and departure must be empty. | +| **departure** | [StopTimeEvent](#message-stoptimeevent) | Conditionally required | One | If schedule_relationship is empty or SCHEDULED, either arrival or departure must be provided within a StopTimeUpdate - both fields cannot be empty. arrival and departure may both be empty when schedule_relationship is SKIPPED or if only `StopTimeProperties` is being updated when schedule_relationship is MODIFIED but no real-time timing is available. If schedule_relationship is NO_DATA, arrival and departure must be empty. | | **schedule_relationship** | [ScheduleRelationship](#enum-schedulerelationship) | Optional | One | The default relationship is SCHEDULED. | | **stop_time_properties** | [StopTimeProperties](#message-stoptimeproperties) | Optional | One | Realtime updates for certain properties defined within GTFS stop_times.txt

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | From 89993ccdc2eeee542abec78b9c29fdd032eac0f3 Mon Sep 17 00:00:00 2001 From: Eric Ouyang Date: Wed, 25 Aug 2021 16:22:24 -0700 Subject: [PATCH 09/16] Mark SKIPPED as deprecated --- gtfs-realtime/proto/gtfs-realtime.proto | 5 ++++- gtfs-realtime/spec/en/reference.md | 8 +++++--- 2 files changed, 9 insertions(+), 4 deletions(-) diff --git a/gtfs-realtime/proto/gtfs-realtime.proto b/gtfs-realtime/proto/gtfs-realtime.proto index 572a6df5b..7efdf9b47 100644 --- a/gtfs-realtime/proto/gtfs-realtime.proto +++ b/gtfs-realtime/proto/gtfs-realtime.proto @@ -222,7 +222,10 @@ 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 being deprecated. 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 data is given for this stop. The main intention for this value is to // give the predictions only for part of a trip, i.e., if the last update diff --git a/gtfs-realtime/spec/en/reference.md b/gtfs-realtime/spec/en/reference.md index c3d70f738..a35d99ced 100644 --- a/gtfs-realtime/spec/en/reference.md +++ b/gtfs-realtime/spec/en/reference.md @@ -184,8 +184,10 @@ The update is linked to a specific stop either through stop_sequence or stop_id, |------------------|------------|----------------|-------------------|-------------------| | **stop_sequence** | [uint32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Conditionally required | One | Must be the same as in stop_times.txt in the corresponding GTFS feed. Either stop_sequence or stop_id must be provided within a StopTimeUpdate - both fields cannot be empty. stop_sequence is required for trips that visit the same stop_id more than once (e.g., a loop) to disambiguate which stop the prediction is for. If `StopTimeProperties.assigned_stop_id` is populated, then `stop_sequence` must be populated. | | **stop_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Conditionally required | One | Must be the same as in stops.txt in the corresponding GTFS feed. Either stop_sequence or stop_id must be provided within a StopTimeUpdate - both fields cannot be empty. If `StopTimeProperties.assigned_stop_id` is populated, it is preferred to omit `stop_id` and use only `stop_sequence`. If `StopTimeProperties.assigned_stop_id` and `stop_id` are populated, `stop_id` must match `assigned_stop_id`. | -| **arrival** | [StopTimeEvent](#message-stoptimeevent) | Conditionally required | One | If schedule_relationship is empty or SCHEDULED, either arrival or departure must be provided within a StopTimeUpdate - both fields cannot be empty. arrival and departure may both be empty when schedule_relationship is SKIPPED or if only `StopTimeProperties` is being updated when schedule_relationship is MODIFIED but no real-time timing is available. If schedule_relationship is NO_DATA, arrival and departure must be empty. | -| **departure** | [StopTimeEvent](#message-stoptimeevent) | Conditionally required | One | If schedule_relationship is empty or SCHEDULED, either arrival or departure must be provided within a StopTimeUpdate - both fields cannot be empty. arrival and departure may both be empty when schedule_relationship is SKIPPED or if only `StopTimeProperties` is being updated when schedule_relationship is MODIFIED but no real-time timing is available. If schedule_relationship is NO_DATA, arrival and departure must be empty. | +| **arrival** | [StopTimeEvent](#message-stoptimeevent) | Conditionally required | One | If schedule_relationship is empty or SCHEDULED, either arrival or departure must be provided within a StopTimeUpdate - both fields cannot be empty. arrival and departure may both be empty when the vehicle will not be stopping +at all (previously SKIPPED (deprecated), now NO_PICKUP and NO_DROP_OFF) or if only `StopTimeProperties` is being updated when schedule_relationship is MODIFIED but no real-time timing is available. If schedule_relationship is NO_DATA, arrival and departure must be empty. | +| **departure** | [StopTimeEvent](#message-stoptimeevent) | Conditionally required | One | If schedule_relationship is empty or SCHEDULED, either arrival or departure must be provided within a StopTimeUpdate - both fields cannot be empty. arrival and departure may both be empty when the vehicle will not be stopping +at all (previously SKIPPED (deprecated), now NO_PICKUP and NO_DROP_OFF) or if only `StopTimeProperties` is being updated when schedule_relationship is MODIFIED but no real-time timing is available. If schedule_relationship is NO_DATA, arrival and departure must be empty. | | **schedule_relationship** | [ScheduleRelationship](#enum-schedulerelationship) | Optional | One | The default relationship is SCHEDULED. | | **stop_time_properties** | [StopTimeProperties](#message-stoptimeproperties) | Optional | One | Realtime updates for certain properties defined within GTFS stop_times.txt

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | @@ -198,7 +200,7 @@ The relation between this StopTime and the static schedule. | _**Value**_ | _**Comment**_ | |-------------|---------------| | **SCHEDULED** | The vehicle is proceeding in accordance with its static schedule of stops, although not necessarily according to the times of the schedule. This is the **default** behavior. At least one of arrival and departure must be provided. Frequency-based trips (GTFS frequencies.txt with exact_times = 0) should not have a SCHEDULED value and should use UNSCHEDULED instead. | -| **SKIPPED** | The stop is skipped, i.e., the vehicle will not stop at this stop. Arrival and departure are optional. When set `SKIPPED` is not propagated to subsequent stops in the same trip (i.e., the vehicle will stop at subsequent stops in the trip unless those stops also have a `stop_time_update` with `schedule_relationship: SKIPPED`). Delay from a previous stop in the trip *does* propagate over the `SKIPPED` stop. In other words, if a `stop_time_update` with an `arrival` or `departure` prediction is not set for a stop after the `SKIPPED` stop, the prediction upstream of the `SKIPPED` stop will be propagated to the stop after the `SKIPPED` stop and subsequent stops in the trip until a `stop_time_update` for a subsequent stop is provided. | +| **SKIPPED** | (Deprecated) The stop is skipped, i.e., the vehicle will not stop at this stop. Arrival and departure are optional. When set `SKIPPED` is not propagated to subsequent stops in the same trip (i.e., the vehicle will stop at subsequent stops in the trip unless those stops also have a `stop_time_update` with `schedule_relationship: SKIPPED`). Delay from a previous stop in the trip *does* propagate over the `SKIPPED` stop. In other words, if a `stop_time_update` with an `arrival` or `departure` prediction is not set for a stop after the `SKIPPED` stop, the prediction upstream of the `SKIPPED` stop will be propagated to the stop after the `SKIPPED` stop and subsequent stops in the trip until a `stop_time_update` for a subsequent stop is provided.

**Caution:** this field is being **deprecated**. 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 | | **NO_DATA** | No data is given for this stop. It indicates that there is no realtime information available. When set NO_DATA is propagated through subsequent stops so this is the recommended way of specifying from which stop you do not have realtime information. When NO_DATA is set neither arrival nor departure should be supplied. | | **UNSCHEDULED** | The vehicle is operating a frequency-based trip (GTFS frequencies.txt with exact_times = 0). This value should not be used for trips that are not defined in GTFS frequencies.txt, or trips in GTFS frequencies.txt with exact_times = 1. Trips containing `stop_time_updates` with `schedule_relationship: UNSCHEDULED` must also set the TripDescriptor `schedule_relationship: UNSCHEDULED`

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | **MODIFIED** | The vehicle's relationship with the static schedule differs 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.

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. From 19fc85f7c4407c2ca884cd2c0aa785c042b9829b Mon Sep 17 00:00:00 2001 From: Eric Ouyang Date: Wed, 25 Aug 2021 22:01:50 -0700 Subject: [PATCH 10/16] Update migration guide --- gtfs-realtime/spec/en/examples/migration-modified.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/gtfs-realtime/spec/en/examples/migration-modified.md b/gtfs-realtime/spec/en/examples/migration-modified.md index 3ebdf92d1..a2f1bfd6f 100644 --- a/gtfs-realtime/spec/en/examples/migration-modified.md +++ b/gtfs-realtime/spec/en/examples/migration-modified.md @@ -4,7 +4,7 @@ The GTFS-realtime `StopTimeUpdate.schedule_relationship` of `SKIPPED` indicates 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 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. +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). @@ -12,7 +12,7 @@ See the [Add pickup and drop-off types to GTFS-RT proposal on GitHub](https://gi #### Producers -If you are a producer who uses the `SKIPPED` enumeration as a best approximation of partial service at a stop, to avoid disruption to existing consumers, 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`. +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": @@ -33,8 +33,9 @@ entity { } } ~~~ - -It is suggested that you notify existing consumers (e.g., via a developer mailing list) that the use of `SKIPPED` for partial service at a stop is being deprecated in favor of more nuanced information 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. +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`. \ No newline at end of file +`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. \ No newline at end of file From 780be36b7a891ed36705be735ed281599b30f2a2 Mon Sep 17 00:00:00 2001 From: ericouyang Date: Tue, 28 Sep 2021 10:49:06 -0400 Subject: [PATCH 11/16] Editorial clarifications --- gtfs-realtime/proto/gtfs-realtime.proto | 26 ++++++++++++++++++++----- 1 file changed, 21 insertions(+), 5 deletions(-) diff --git a/gtfs-realtime/proto/gtfs-realtime.proto b/gtfs-realtime/proto/gtfs-realtime.proto index 509a2f494..baf420916 100644 --- a/gtfs-realtime/proto/gtfs-realtime.proto +++ b/gtfs-realtime/proto/gtfs-realtime.proto @@ -228,9 +228,21 @@ message TripUpdate { // The stop is skipped, i.e., the vehicle will not stop at this stop. // Arrival and departure are optional. - // NOTE: This field is being deprecated. 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 + // 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. @@ -280,13 +292,17 @@ message TripUpdate { // 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. + // 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. + // 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; From e9ef94b76b0b6798ff0d38f6c582e84067c35fd7 Mon Sep 17 00:00:00 2001 From: ericouyang Date: Tue, 28 Sep 2021 10:57:25 -0400 Subject: [PATCH 12/16] Reflect editorial changes into reference.md --- gtfs-realtime/spec/en/reference.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/gtfs-realtime/spec/en/reference.md b/gtfs-realtime/spec/en/reference.md index ed7c61ce5..803e5c98b 100644 --- a/gtfs-realtime/spec/en/reference.md +++ b/gtfs-realtime/spec/en/reference.md @@ -199,7 +199,7 @@ The relation between this StopTime and the static schedule. | _**Value**_ | _**Comment**_ | |-------------|---------------| | **SCHEDULED** | The vehicle is proceeding in accordance with its static schedule of stops, although not necessarily according to the times of the schedule. This is the **default** behavior. At least one of arrival and departure must be provided. Frequency-based trips (GTFS frequencies.txt with exact_times = 0) should not have a SCHEDULED value and should use UNSCHEDULED instead. | -| **SKIPPED** | (Deprecated) The stop is skipped, i.e., the vehicle will not stop at this stop. Arrival and departure are optional. When set `SKIPPED` is not propagated to subsequent stops in the same trip (i.e., the vehicle will stop at subsequent stops in the trip unless those stops also have a `stop_time_update` with `schedule_relationship: SKIPPED`). Delay from a previous stop in the trip *does* propagate over the `SKIPPED` stop. In other words, if a `stop_time_update` with an `arrival` or `departure` prediction is not set for a stop after the `SKIPPED` stop, the prediction upstream of the `SKIPPED` stop will be propagated to the stop after the `SKIPPED` stop and subsequent stops in the trip until a `stop_time_update` for a subsequent stop is provided.

**Caution:** this field is being **deprecated**. 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** | (Experimentally deprecated) The stop is skipped, i.e., the vehicle will not stop at this stop. Arrival and departure are optional. When set `SKIPPED` is not propagated to subsequent stops in the same trip (i.e., the vehicle will stop at subsequent stops in the trip unless those stops also have a `stop_time_update` with `schedule_relationship: SKIPPED`). Delay from a previous stop in the trip *does* propagate over the `SKIPPED` stop. In other words, if a `stop_time_update` with an `arrival` or `departure` prediction is not set for a stop after the `SKIPPED` stop, the prediction upstream of the `SKIPPED` stop will be propagated to the stop after the `SKIPPED` stop and subsequent stops in the trip until a `stop_time_update` for a subsequent stop is provided.

**Caution:** this field is being **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 this interim period, users may continue to use this value for compatability. 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. | | **NO_DATA** | No data is given for this stop. It indicates that there is no realtime timing information available. When set NO_DATA is propagated through subsequent stops so this is the recommended way of specifying from which stop you do not have realtime timing information. When NO_DATA is set neither arrival nor departure should be supplied. | | **UNSCHEDULED** | The vehicle is operating a frequency-based trip (GTFS frequencies.txt with exact_times = 0). This value should not be used for trips that are not defined in GTFS frequencies.txt, or trips in GTFS frequencies.txt with exact_times = 1. Trips containing `stop_time_updates` with `schedule_relationship: UNSCHEDULED` must also set the TripDescriptor `schedule_relationship: UNSCHEDULED`

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | **MODIFIED** | The vehicle's relationship with the static schedule differs 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.

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. @@ -215,9 +215,8 @@ Realtime update for certain properties defined within GTFS stop_times.txt. | _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ | |------------------|------------|----------------|-------------------|-------------------| | **assigned_stop_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | Supports real-time stop assignments. Refers to a `stop_id` defined in the GTFS `stops.txt`.
The new `assigned_stop_id` should not result in a significantly different trip experience for the end user than the `stop_id` defined in GTFS `stop_times.txt`. In other words, the end user should not view this new `stop_id` as an "unusual change" if the new stop was presented within an app without any additional context. For example, this field is intended to be used for platform assignments by using a `stop_id` that belongs to the same station as the stop originally defined in GTFS `stop_times.txt`.
To assign a stop without providing any real-time arrival or departure predictions, populate this field and set `StopTimeUpdate.schedule_relationship = NO_DATA`.
If this field is populated, `StopTimeUpdate.stop_sequence` must be populated and `StopTimeUpdate.stop_id` should not be populated. Stop assignments should be reflected in other GTFS-realtime fields as well (e.g., `VehiclePosition.stop_id`).

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | -| **pickup_type** | [PickupType](#enum-pickuptype) | Optional | One | 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.

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | -| **drop_off_type** | [DropOffType](#enum-dropofftype) | Optional | One | 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 schedule-based service. -

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | +| **pickup_type** | [PickupType](#enum-pickuptype) | Optional | One | 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.

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | +| **drop_off_type** | [DropOffType](#enum-dropofftype) | Optional | One | 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 schedule-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.

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | ## _enum_ PickupType From ab21cd6ec76e899fa53132dfbb01a3bc80fe29ae Mon Sep 17 00:00:00 2001 From: ericouyang Date: Thu, 7 Oct 2021 10:03:30 -0400 Subject: [PATCH 13/16] No longer mark SKIPPED as formally deprecated --- gtfs-realtime/proto/gtfs-realtime.proto | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gtfs-realtime/proto/gtfs-realtime.proto b/gtfs-realtime/proto/gtfs-realtime.proto index baf420916..53b50181d 100644 --- a/gtfs-realtime/proto/gtfs-realtime.proto +++ b/gtfs-realtime/proto/gtfs-realtime.proto @@ -243,7 +243,7 @@ message TripUpdate { // 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]; + SKIPPED = 1; // No StopTimeEvents are given for this stop. // The main intention for this value is to give time predictions only for From 81c94d75c14e291732682b874c2019f4185c7580 Mon Sep 17 00:00:00 2001 From: ericouyang Date: Thu, 7 Oct 2021 10:54:08 -0400 Subject: [PATCH 14/16] Update migration guide to support SCHEDULED --- .../spec/en/examples/migration-modified.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/gtfs-realtime/spec/en/examples/migration-modified.md b/gtfs-realtime/spec/en/examples/migration-modified.md index a2f1bfd6f..1f7909c6b 100644 --- a/gtfs-realtime/spec/en/examples/migration-modified.md +++ b/gtfs-realtime/spec/en/examples/migration-modified.md @@ -1,10 +1,10 @@ ## 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-realtime `StopTimeUpdate.schedule_relationship` of `SKIPPED`, which is now experimentally deprecated, was used to indicate 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. +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` instead. 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). @@ -12,7 +12,7 @@ See the [Add pickup and drop-off types to GTFS-RT proposal on GitHub](https://gi #### 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. +If you are a producer who uses the `SKIPPED` enumeration for indicating that a 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": @@ -33,9 +33,12 @@ entity { } } ~~~ + +When a stop is not fully skipped and you'd like to provide additional information through `pickup_type` and `drop_off_type`, you may also use `SCHEDULED` in the interim. + 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 this interim period, when `pickup_type` and `drop_off_type` are set in `StopTimeProperties`, it takes precedence over `schedule_relationship=SKIPPED` or `schedule_relationship=SCHEDULED`, meaning that the definitions of `SKIPPED` and `SCHEDULED` do not apply. Real-time arrival information should still be used to inform passengers rather being potentially ignored when `SKIPPED`. For example, a passenger-facing application could use this additional information to provide additional instructions or notification on how to board/alight, similar to what may happen with those fields being specified statically 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. \ No newline at end of file +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. From 4ffaf3a2e1709811709c6c914d7ac2470499caab Mon Sep 17 00:00:00 2001 From: ericouyang Date: Thu, 7 Oct 2021 11:04:43 -0400 Subject: [PATCH 15/16] Support SCHEDULED in migration period --- gtfs-realtime/proto/gtfs-realtime.proto | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/gtfs-realtime/proto/gtfs-realtime.proto b/gtfs-realtime/proto/gtfs-realtime.proto index 53b50181d..c65d03eab 100644 --- a/gtfs-realtime/proto/gtfs-realtime.proto +++ b/gtfs-realtime/proto/gtfs-realtime.proto @@ -295,6 +295,8 @@ message TripUpdate { // 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. + // For the same reason, when a stop is not fully skipped, StopTimeUpdate.schedule_relationship may be + // SCHEDULED in an interim period. // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future. optional PickupType pickup_type = 2; @@ -303,6 +305,8 @@ message TripUpdate { // 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. + // For the same reason, when a stop is not fully skipped, StopTimeUpdate.schedule_relationship may be + // SCHEDULED in an interim period. // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future. optional DropOffType drop_off_type = 3; From d28f43290f54f88650deafb36b3d791249bd8ad4 Mon Sep 17 00:00:00 2001 From: ericouyang Date: Thu, 7 Oct 2021 11:09:50 -0400 Subject: [PATCH 16/16] Update reference to match documentation in .proto --- gtfs-realtime/spec/en/reference.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/gtfs-realtime/spec/en/reference.md b/gtfs-realtime/spec/en/reference.md index 803e5c98b..5eda62528 100644 --- a/gtfs-realtime/spec/en/reference.md +++ b/gtfs-realtime/spec/en/reference.md @@ -215,8 +215,8 @@ Realtime update for certain properties defined within GTFS stop_times.txt. | _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ | |------------------|------------|----------------|-------------------|-------------------| | **assigned_stop_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | Supports real-time stop assignments. Refers to a `stop_id` defined in the GTFS `stops.txt`.
The new `assigned_stop_id` should not result in a significantly different trip experience for the end user than the `stop_id` defined in GTFS `stop_times.txt`. In other words, the end user should not view this new `stop_id` as an "unusual change" if the new stop was presented within an app without any additional context. For example, this field is intended to be used for platform assignments by using a `stop_id` that belongs to the same station as the stop originally defined in GTFS `stop_times.txt`.
To assign a stop without providing any real-time arrival or departure predictions, populate this field and set `StopTimeUpdate.schedule_relationship = NO_DATA`.
If this field is populated, `StopTimeUpdate.stop_sequence` must be populated and `StopTimeUpdate.stop_id` should not be populated. Stop assignments should be reflected in other GTFS-realtime fields as well (e.g., `VehiclePosition.stop_id`).

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | -| **pickup_type** | [PickupType](#enum-pickuptype) | Optional | One | 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.

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | -| **drop_off_type** | [DropOffType](#enum-dropofftype) | Optional | One | 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 schedule-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.

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | +| **pickup_type** | [PickupType](#enum-pickuptype) | Optional | One | 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. For the same reason, when a stop is not fully skipped, StopTimeUpdate.schedule_relationship may be SCHEDULED in an interim period.

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | +| **drop_off_type** | [DropOffType](#enum-dropofftype) | Optional | One | 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 schedule-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. For the same reason, when a stop is not fully skipped, StopTimeUpdate.schedule_relationship may be SCHEDULED in an interim period.

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | ## _enum_ PickupType