From 464482aa5443910208f381aebf2ec082afb90cba Mon Sep 17 00:00:00 2001 From: Sean Barbeau Date: Tue, 28 Apr 2020 17:39:25 -0400 Subject: [PATCH 01/13] Add GTFS-RT platform changes * Add .proto changes for platform_id * Add documentation saying stop_id and stop_sequence pairings should match static GTFS * Add platform_id documentation in Markdown files --- gtfs-realtime/proto/gtfs-realtime.proto | 10 +++++++++- gtfs-realtime/spec/en/reference.md | 15 +++++++++++++-- 2 files changed, 22 insertions(+), 3 deletions(-) diff --git a/gtfs-realtime/proto/gtfs-realtime.proto b/gtfs-realtime/proto/gtfs-realtime.proto index bd7d02ab4..3c2396671 100644 --- a/gtfs-realtime/proto/gtfs-realtime.proto +++ b/gtfs-realtime/proto/gtfs-realtime.proto @@ -240,7 +240,15 @@ message TripUpdate { UNSCHEDULED = 3; } optional ScheduleRelationship schedule_relationship = 5 - [default = SCHEDULED]; + [default = SCHEDULED]; + + // Provides the updated values for the stop time. + message StopTimeProperties { + // Supports real-time platform changes. Refers to a stop_id defined in the GTFS stops.txt. This stop_id must + // belong to the same station as the stop originally defined in GTFS stop_times.txt. + optional string platform_id = 1; + } + optional StopTimeProperties stop_time_properties = 6; // The extensions namespace allows 3rd-party developers to extend the // GTFS Realtime Specification in order to add and evaluate new features diff --git a/gtfs-realtime/spec/en/reference.md b/gtfs-realtime/spec/en/reference.md index 8f34d290c..07697f409 100644 --- a/gtfs-realtime/spec/en/reference.md +++ b/gtfs-realtime/spec/en/reference.md @@ -49,6 +49,7 @@ Fields labeled as **experimental** are subject to change and not yet formally ad * [StopTimeUpdate](#message-stoptimeupdate) * [StopTimeEvent](#message-stoptimeevent) * [ScheduleRelationship](#enum-schedulerelationship) + * [StopTimeProperties](#message-stoptimeproperties) * [VehiclePosition](#message-vehicleposition) * [TripDescriptor](#message-tripdescriptor) * [ScheduleRelationship](#enum-schedulerelationship-1) @@ -177,8 +178,8 @@ The update is linked to a specific stop either through stop_sequence or stop_id, | _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ | |------------------|------------|----------------|-------------------|-------------------| -| **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. | -| **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. | +| **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. The pairing of stop_sequence and stop_id must match the corresponding values in GTFS stop_times.txt for this trip. | +| **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. The pairing of stop_sequence and stop_id must match the corresponding values in GTFS stop_times.txt for this trip. | | **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. | | **schedule_relationship** | [ScheduleRelationship](#enum-schedulerelationship) | Optional | One | The default relationship is SCHEDULED. | @@ -196,6 +197,16 @@ The relation between this StopTime and the static schedule. | **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.
. +## _message_ StopTimeProperties + +Realtime update for certain properties defined within GTFS stop_times.txt. + +#### Fields + +| _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ | +|------------------|------------|----------------|-------------------|-------------------| +| **platform_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | Supports real-time platform changes at stations. Refers to a stop_id defined in the GTFS stops.txt. This stop_id must belong to the same station as the stop originally defined in GTFS stop_times.txt for the `stop_sequence` defined in the StopTimeUpdate. If this field is populated, StopTimeUpdate `stop_sequence` must be populated and StopTimeUpdate `stop_id` should not be populated. | + ## _message_ VehiclePosition Realtime positioning information for a given vehicle. From f2cf12db061c3d17a3980a3b4dea57d1139214cc Mon Sep 17 00:00:00 2001 From: Sean Barbeau Date: Wed, 29 Apr 2020 16:48:25 -0400 Subject: [PATCH 02/13] Add explicit reference to valid location_type --- gtfs-realtime/spec/en/reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gtfs-realtime/spec/en/reference.md b/gtfs-realtime/spec/en/reference.md index 07697f409..a8ba43ceb 100644 --- a/gtfs-realtime/spec/en/reference.md +++ b/gtfs-realtime/spec/en/reference.md @@ -205,7 +205,7 @@ Realtime update for certain properties defined within GTFS stop_times.txt. | _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ | |------------------|------------|----------------|-------------------|-------------------| -| **platform_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | Supports real-time platform changes at stations. Refers to a stop_id defined in the GTFS stops.txt. This stop_id must belong to the same station as the stop originally defined in GTFS stop_times.txt for the `stop_sequence` defined in the StopTimeUpdate. If this field is populated, StopTimeUpdate `stop_sequence` must be populated and StopTimeUpdate `stop_id` should not be populated. | +| **platform_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | Supports real-time platform changes at stations. Refers to a stop_id defined in the GTFS stops.txt which must have the `location_type` of `0` or blank. This stop_id must belong to the same station as the stop originally defined in GTFS stop_times.txt for the `stop_sequence` defined in the StopTimeUpdate. If this field is populated, StopTimeUpdate `stop_sequence` must be populated and StopTimeUpdate `stop_id` should not be populated. | ## _message_ VehiclePosition From c4af1f428b9ee1ba0e641914d05ad924349da5cb Mon Sep 17 00:00:00 2001 From: Sean Barbeau Date: Wed, 29 Apr 2020 17:07:08 -0400 Subject: [PATCH 03/13] Add stop_time_properties to StopTimeUpdate in markdown file --- gtfs-realtime/spec/en/reference.md | 1 + 1 file changed, 1 insertion(+) diff --git a/gtfs-realtime/spec/en/reference.md b/gtfs-realtime/spec/en/reference.md index a8ba43ceb..a82d99021 100644 --- a/gtfs-realtime/spec/en/reference.md +++ b/gtfs-realtime/spec/en/reference.md @@ -183,6 +183,7 @@ The update is linked to a specific stop either through stop_sequence or 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. | | **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 | ## _enum_ ScheduleRelationship From 949cf2862d5ce1a4ac4a4b4a8067af0c222e0a01 Mon Sep 17 00:00:00 2001 From: Sean Barbeau Date: Wed, 20 May 2020 12:51:41 -0400 Subject: [PATCH 04/13] Remove requirement that stop_id/_sequence pairing must match static --- gtfs-realtime/spec/en/reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gtfs-realtime/spec/en/reference.md b/gtfs-realtime/spec/en/reference.md index a82d99021..c4d4175c6 100644 --- a/gtfs-realtime/spec/en/reference.md +++ b/gtfs-realtime/spec/en/reference.md @@ -179,7 +179,7 @@ The update is linked to a specific stop either through stop_sequence or stop_id, | _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ | |------------------|------------|----------------|-------------------|-------------------| | **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. The pairing of stop_sequence and stop_id must match the corresponding values in GTFS stop_times.txt for this trip. | -| **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. The pairing of stop_sequence and stop_id must match the corresponding values in GTFS stop_times.txt for this trip. | +| **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. | | **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. | | **schedule_relationship** | [ScheduleRelationship](#enum-schedulerelationship) | Optional | One | The default relationship is SCHEDULED. | From 0042bcad24fecb092eb324d8e0924ce92f094edb Mon Sep 17 00:00:00 2001 From: Sean Barbeau Date: Wed, 20 May 2020 12:52:47 -0400 Subject: [PATCH 05/13] Remove auto-format change --- 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 3c2396671..916416f0c 100644 --- a/gtfs-realtime/proto/gtfs-realtime.proto +++ b/gtfs-realtime/proto/gtfs-realtime.proto @@ -240,7 +240,7 @@ message TripUpdate { UNSCHEDULED = 3; } optional ScheduleRelationship schedule_relationship = 5 - [default = SCHEDULED]; + [default = SCHEDULED]; // Provides the updated values for the stop time. message StopTimeProperties { From ac11924da38a1d6ae4e79f9fcc80727450141d76 Mon Sep 17 00:00:00 2001 From: Sean Barbeau Date: Wed, 20 May 2020 12:54:55 -0400 Subject: [PATCH 06/13] Remove requirement that stop_id/_sequence pairing must match static --- gtfs-realtime/spec/en/reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gtfs-realtime/spec/en/reference.md b/gtfs-realtime/spec/en/reference.md index c4d4175c6..180331fac 100644 --- a/gtfs-realtime/spec/en/reference.md +++ b/gtfs-realtime/spec/en/reference.md @@ -178,7 +178,7 @@ The update is linked to a specific stop either through stop_sequence or stop_id, | _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ | |------------------|------------|----------------|-------------------|-------------------| -| **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. The pairing of stop_sequence and stop_id must match the corresponding values in GTFS stop_times.txt for this trip. | +| **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. | | **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. | | **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. | From 597cc5b8dc0c2b2cadd3a6bb4ec51e2e0e989951 Mon Sep 17 00:00:00 2001 From: Sean Barbeau Date: Fri, 29 May 2020 16:43:40 -0400 Subject: [PATCH 07/13] Add experimental labels for message/fields --- gtfs-realtime/proto/gtfs-realtime.proto | 3 +++ gtfs-realtime/spec/en/reference.md | 8 +++++--- 2 files changed, 8 insertions(+), 3 deletions(-) diff --git a/gtfs-realtime/proto/gtfs-realtime.proto b/gtfs-realtime/proto/gtfs-realtime.proto index 916416f0c..da597701e 100644 --- a/gtfs-realtime/proto/gtfs-realtime.proto +++ b/gtfs-realtime/proto/gtfs-realtime.proto @@ -243,11 +243,14 @@ message TripUpdate { [default = SCHEDULED]; // Provides the updated values for the stop time. + // NOTE: This message is still experimental, and subject to change. It may be formally adopted in the future. message StopTimeProperties { // Supports real-time platform changes. Refers to a stop_id defined in the GTFS stops.txt. This stop_id must // belong to the same station as the stop originally defined in GTFS stop_times.txt. + // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future. optional string platform_id = 1; } + // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future. optional StopTimeProperties stop_time_properties = 6; // The extensions namespace allows 3rd-party developers to extend the diff --git a/gtfs-realtime/spec/en/reference.md b/gtfs-realtime/spec/en/reference.md index 180331fac..21c367f20 100644 --- a/gtfs-realtime/spec/en/reference.md +++ b/gtfs-realtime/spec/en/reference.md @@ -183,7 +183,7 @@ The update is linked to a specific stop either through stop_sequence or 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. | | **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 | +| **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.
. | ## _enum_ ScheduleRelationship @@ -200,13 +200,15 @@ The relation between this StopTime and the static schedule. ## _message_ StopTimeProperties -Realtime update for certain properties defined within GTFS stop_times.txt. +Realtime update for certain properties defined within GTFS stop_times.txt. + +**Caution:** this message is still **experimental**, and subject to change. It may be formally adopted in the future.
. #### Fields | _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ | |------------------|------------|----------------|-------------------|-------------------| -| **platform_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | Supports real-time platform changes at stations. Refers to a stop_id defined in the GTFS stops.txt which must have the `location_type` of `0` or blank. This stop_id must belong to the same station as the stop originally defined in GTFS stop_times.txt for the `stop_sequence` defined in the StopTimeUpdate. If this field is populated, StopTimeUpdate `stop_sequence` must be populated and StopTimeUpdate `stop_id` should not be populated. | +| **platform_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | Supports real-time platform changes at stations. Refers to a stop_id defined in the GTFS stops.txt which must have the `location_type` of `0` or blank. This stop_id must belong to the same station as the stop originally defined in GTFS stop_times.txt for the `stop_sequence` defined in the StopTimeUpdate. If this field is populated, StopTimeUpdate `stop_sequence` must be populated and StopTimeUpdate `stop_id` should not be populated.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.
. | ## _message_ VehiclePosition From 349582cbea690ff8ecef9fe8f88ebb361d4f19c3 Mon Sep 17 00:00:00 2001 From: Sean Barbeau Date: Mon, 10 Aug 2020 09:49:27 -0400 Subject: [PATCH 08/13] chore: Add extension fields to StopTimeProperties --- gtfs-realtime/proto/gtfs-realtime.proto | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/gtfs-realtime/proto/gtfs-realtime.proto b/gtfs-realtime/proto/gtfs-realtime.proto index da597701e..062e74c9b 100644 --- a/gtfs-realtime/proto/gtfs-realtime.proto +++ b/gtfs-realtime/proto/gtfs-realtime.proto @@ -249,6 +249,14 @@ message TripUpdate { // belong to the same station as the stop originally defined in GTFS stop_times.txt. // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future. optional string platform_id = 1; + + // The extensions namespace allows 3rd-party developers to extend the + // GTFS Realtime Specification in order to add and evaluate new features + // and modifications to the spec. + extensions 1000 to 1999; + + // The following extension IDs are reserved for private use by any organization. + extensions 9000 to 9999; } // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future. optional StopTimeProperties stop_time_properties = 6; From b393071fc417c44b2a7c14391fb300069257dcb1 Mon Sep 17 00:00:00 2001 From: Sean Barbeau Date: Mon, 10 Aug 2020 11:26:58 -0400 Subject: [PATCH 09/13] chore: "change"->"assign", add note to VehiclePosition --- gtfs-realtime/proto/gtfs-realtime.proto | 2 +- gtfs-realtime/spec/en/reference.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/gtfs-realtime/proto/gtfs-realtime.proto b/gtfs-realtime/proto/gtfs-realtime.proto index 511d66408..658a0cf96 100644 --- a/gtfs-realtime/proto/gtfs-realtime.proto +++ b/gtfs-realtime/proto/gtfs-realtime.proto @@ -245,7 +245,7 @@ message TripUpdate { // Provides the updated values for the stop time. // NOTE: This message is still experimental, and subject to change. It may be formally adopted in the future. message StopTimeProperties { - // Supports real-time platform changes. Refers to a stop_id defined in the GTFS stops.txt. This stop_id must + // Supports real-time platform assignments. Refers to a stop_id defined in the GTFS stops.txt. This stop_id must // belong to the same station as the stop originally defined in GTFS stop_times.txt. // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future. optional string platform_id = 1; diff --git a/gtfs-realtime/spec/en/reference.md b/gtfs-realtime/spec/en/reference.md index c433b2a1f..bd35f28e4 100644 --- a/gtfs-realtime/spec/en/reference.md +++ b/gtfs-realtime/spec/en/reference.md @@ -211,7 +211,7 @@ Realtime update for certain properties defined within GTFS stop_times.txt. | _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ | |------------------|------------|----------------|-------------------|-------------------| -| **platform_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | Supports real-time platform changes at stations. Refers to a stop_id defined in the GTFS stops.txt which must have the `location_type` of `0` or blank. This stop_id must belong to the same station as the stop originally defined in GTFS stop_times.txt for the `stop_sequence` defined in the StopTimeUpdate. If this field is populated, StopTimeUpdate `stop_sequence` must be populated and StopTimeUpdate `stop_id` should not be populated.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.
. | +| **platform_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | Supports real-time platform assignments at stations. Refers to a stop_id defined in the GTFS stops.txt which must have the `location_type` of `0` or blank. This stop_id must belong to the same station as the stop originally defined in GTFS stop_times.txt for the `stop_sequence` defined in the StopTimeUpdate. If this field is populated, StopTimeUpdate `stop_sequence` must be populated and StopTimeUpdate `stop_id` should not be populated. Platform 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.
. | ## _message_ TripProperties @@ -239,7 +239,7 @@ Realtime positioning information for a given vehicle. | **vehicle** | [VehicleDescriptor](#message-vehicledescriptor) | Optional | One | Additional information on the vehicle that is serving this trip. Each entry should have a **unique** vehicle id. | | **position** | [Position](#message-position) | Optional | One | Current position of this vehicle. | | **current_stop_sequence** | [uint32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | The stop sequence index of the current stop. The meaning of current_stop_sequence (i.e., the stop that it refers to) is determined by current_status. If current_status is missing IN_TRANSIT_TO is assumed. | -| **stop_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | Identifies the current stop. The value must be the same as in stops.txt in the corresponding GTFS feed. | +| **stop_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | Identifies the current stop. The value must be the same as in stops.txt in the corresponding GTFS feed. If `StopTimeProperties.platform_id` is used to assign a platform, this field should also reflect the change in `stop_id`. | | **current_status** | [VehicleStopStatus](#enum-vehiclestopstatus) | Optional | One | The exact status of the vehicle with respect to the current stop. Ignored if current_stop_sequence is missing. | | **timestamp** | [uint64](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | Moment at which the vehicle's position was measured. In POSIX time (i.e., number of seconds since January 1st 1970 00:00:00 UTC). | | **congestion_level** | [CongestionLevel](#enum-congestionlevel) | Optional | One | From 5f003fa5741ddbe555f2097ac8077c99bbdfdf15 Mon Sep 17 00:00:00 2001 From: Sean Barbeau Date: Tue, 27 Oct 2020 16:22:53 -0400 Subject: [PATCH 10/13] Address community feedback * Name change of platform_id -> assigned_stop_id - The assigned stop may not be a platform within a station. * Add more subjective language to define when assigned_stop_id can be used (versus requiring changes to be only within a station) * Require that StopTimeUpdate.stop_sequence be used as the selector and that StopTimeUpdate.stop_id be empty * Add that you can assign a stop without providing real-time predictions by using StopTimeUpdate.schedule_relationship = NO_DATA * Don't block use of StopTimeUpdate.stop_id being populated with other values in case others want to have unofficial GTFS-realtime feeds that changes stop_id to represent a different stop (e.g., Bliksem Labs B.V.) --- gtfs-realtime/proto/gtfs-realtime.proto | 17 ++++++++++++++--- gtfs-realtime/spec/en/reference.md | 10 +++++----- 2 files changed, 19 insertions(+), 8 deletions(-) diff --git a/gtfs-realtime/proto/gtfs-realtime.proto b/gtfs-realtime/proto/gtfs-realtime.proto index 658a0cf96..3ff5503b9 100644 --- a/gtfs-realtime/proto/gtfs-realtime.proto +++ b/gtfs-realtime/proto/gtfs-realtime.proto @@ -245,10 +245,19 @@ message TripUpdate { // Provides the updated values for the stop time. // NOTE: This message is still experimental, and subject to change. It may be formally adopted in the future. message StopTimeProperties { - // Supports real-time platform assignments. Refers to a stop_id defined in the GTFS stops.txt. This stop_id must - // belong to the same station as the stop originally defined in GTFS stop_times.txt. + // 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. Platform assignments should be reflected in other GTFS-realtime fields as well + // (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 platform_id = 1; + optional string assigned_stop_id = 1; // The extensions namespace allows 3rd-party developers to extend the // GTFS Realtime Specification in order to add and evaluate new features @@ -258,6 +267,8 @@ message TripUpdate { // The following extension IDs are reserved for private use by any organization. extensions 9000 to 9999; } + + // Realtime updates for certain properties defined within GTFS stop_times.txt // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future. optional StopTimeProperties stop_time_properties = 6; diff --git a/gtfs-realtime/spec/en/reference.md b/gtfs-realtime/spec/en/reference.md index bd35f28e4..6ca7c71eb 100644 --- a/gtfs-realtime/spec/en/reference.md +++ b/gtfs-realtime/spec/en/reference.md @@ -181,8 +181,8 @@ The update is linked to a specific stop either through stop_sequence or stop_id, | _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ | |------------------|------------|----------------|-------------------|-------------------| -| **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. | -| **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. | +| **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, then `stop_id` must *not* be populated. | | **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. | | **schedule_relationship** | [ScheduleRelationship](#enum-schedulerelationship) | Optional | One | The default relationship is SCHEDULED. | @@ -205,13 +205,13 @@ The relation between this StopTime and the static schedule. Realtime update for certain properties defined within GTFS stop_times.txt. -**Caution:** this message is still **experimental**, and subject to change. It may be formally adopted in the future.
. +**Caution:** this message is still **experimental**, and subject to change. It may be formally adopted in the future.
#### Fields | _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ | |------------------|------------|----------------|-------------------|-------------------| -| **platform_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | Supports real-time platform assignments at stations. Refers to a stop_id defined in the GTFS stops.txt which must have the `location_type` of `0` or blank. This stop_id must belong to the same station as the stop originally defined in GTFS stop_times.txt for the `stop_sequence` defined in the StopTimeUpdate. If this field is populated, StopTimeUpdate `stop_sequence` must be populated and StopTimeUpdate `stop_id` should not be populated. Platform 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.
. | +| **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.
. | ## _message_ TripProperties @@ -239,7 +239,7 @@ Realtime positioning information for a given vehicle. | **vehicle** | [VehicleDescriptor](#message-vehicledescriptor) | Optional | One | Additional information on the vehicle that is serving this trip. Each entry should have a **unique** vehicle id. | | **position** | [Position](#message-position) | Optional | One | Current position of this vehicle. | | **current_stop_sequence** | [uint32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | The stop sequence index of the current stop. The meaning of current_stop_sequence (i.e., the stop that it refers to) is determined by current_status. If current_status is missing IN_TRANSIT_TO is assumed. | -| **stop_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | Identifies the current stop. The value must be the same as in stops.txt in the corresponding GTFS feed. If `StopTimeProperties.platform_id` is used to assign a platform, this field should also reflect the change in `stop_id`. | +| **stop_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | Identifies the current stop. The value must be the same as in stops.txt in the corresponding GTFS feed. If `StopTimeProperties.assigned_stop_id` is used to assign a `stop_id`, this field should also reflect the change in `stop_id`. | | **current_status** | [VehicleStopStatus](#enum-vehiclestopstatus) | Optional | One | The exact status of the vehicle with respect to the current stop. Ignored if current_stop_sequence is missing. | | **timestamp** | [uint64](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | Moment at which the vehicle's position was measured. In POSIX time (i.e., number of seconds since January 1st 1970 00:00:00 UTC). | | **congestion_level** | [CongestionLevel](#enum-congestionlevel) | Optional | One | From ce1d8b5a9db2027006bf946d5143258ffc77cd02 Mon Sep 17 00:00:00 2001 From: Sean Barbeau Date: Wed, 28 Oct 2020 16:30:17 -0400 Subject: [PATCH 11/13] Update use of stop_id with assigned_stop_id Avoid breaking current unofficial use of stop_id for platform assignment --- gtfs-realtime/spec/en/reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gtfs-realtime/spec/en/reference.md b/gtfs-realtime/spec/en/reference.md index 6ca7c71eb..f1ed3d2f9 100644 --- a/gtfs-realtime/spec/en/reference.md +++ b/gtfs-realtime/spec/en/reference.md @@ -182,7 +182,7 @@ The update is linked to a specific stop either through stop_sequence or stop_id, | _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ | |------------------|------------|----------------|-------------------|-------------------| | **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, then `stop_id` must *not* 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. | | **schedule_relationship** | [ScheduleRelationship](#enum-schedulerelationship) | Optional | One | The default relationship is SCHEDULED. | From 81e8804fdf88bd3b9512f9b33616ec45fa6f1340 Mon Sep 17 00:00:00 2001 From: Sean Barbeau Date: Wed, 4 Nov 2020 09:52:41 -0500 Subject: [PATCH 12/13] Fix .proto comment to match spec language This should have been updated with https://github.com/google/transit/pull/219/commits/ce1d8b5a9db2027006bf946d5143258ffc77cd02 --- gtfs-realtime/proto/gtfs-realtime.proto | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/gtfs-realtime/proto/gtfs-realtime.proto b/gtfs-realtime/proto/gtfs-realtime.proto index 3ff5503b9..e8884e30a 100644 --- a/gtfs-realtime/proto/gtfs-realtime.proto +++ b/gtfs-realtime/proto/gtfs-realtime.proto @@ -253,8 +253,9 @@ message TripUpdate { // 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. Platform assignments should be reflected in other GTFS-realtime fields as well + // If this field 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`. + // Platform assignments should be reflected in other GTFS-realtime fields as well // (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; From 43d960d92060c9053a489ef5508cc2aad051a78a Mon Sep 17 00:00:00 2001 From: Sean Barbeau Date: Wed, 4 Nov 2020 10:20:39 -0500 Subject: [PATCH 13/13] Further clarify in proto doc which stop_id field --- gtfs-realtime/proto/gtfs-realtime.proto | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/gtfs-realtime/proto/gtfs-realtime.proto b/gtfs-realtime/proto/gtfs-realtime.proto index e8884e30a..095436722 100644 --- a/gtfs-realtime/proto/gtfs-realtime.proto +++ b/gtfs-realtime/proto/gtfs-realtime.proto @@ -253,8 +253,8 @@ message TripUpdate { // 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, 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`. + // If this field is populated, it is preferred to omit `StopTimeUpdate.stop_id` and use only `StopTimeUpdate.stop_sequence`. If + // `StopTimeProperties.assigned_stop_id` and `StopTimeUpdate.stop_id` are populated, `StopTimeUpdate.stop_id` must match `assigned_stop_id`. // Platform assignments should be reflected in other GTFS-realtime fields as well // (e.g., `VehiclePosition.stop_id`). // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future.