Skip to content

TripModifications final #21

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
gcamp wants to merge 1 commit into
base: master
Choose a base branch
from
+6 −21
Draft

TripModifications final #21

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 1 addition & 5 deletions gtfs-realtime/proto/gtfs-realtime.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -108,8 +108,6 @@ message FeedEntity {
optional TripUpdate trip_update = 3;
optional VehiclePosition vehicle = 4;
optional Alert alert = 5;

// NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future.
optional Shape shape = 6;
optional Stop stop = 7;
optional TripModifications trip_modifications = 8;
Expand Down Expand Up @@ -1144,7 +1142,6 @@ message Stop {
extensions 9000 to 9999;
}

// NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future.
message TripModifications {
// A `Modification` message replaces a span of n stop times from each affected trip starting at `start_stop_selector`.
message Modification {
Expand All @@ -1167,6 +1164,7 @@ message TripModifications {
repeated ReplacementStop replacement_stops = 4;

// An `id` value from the `FeedEntity` message that contains the `Alert` describing this Modification for user-facing communication.
// NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future.
optional string service_alert_id = 5;

// This timestamp identifies the moment when the modification has last been changed.
Expand Down Expand Up @@ -1222,7 +1220,6 @@ message TripModifications {
extensions 9000 to 9999;
}

// NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future.
// Select a stop by stop sequence or by stop_id. At least one of the two values must be provided.
message StopSelector {
// Must be the same as in stop_times.txt in the corresponding GTFS feed.
Expand All @@ -1239,7 +1236,6 @@ message StopSelector {
extensions 9000 to 9999;
}

// NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future.
message ReplacementStop {
// The difference in seconds between the arrival time at this stop and the arrival time at the reference stop. The reference stop is the stop prior to start_stop_selector. If the modification begins at the first stop of the trip, then the first stop of the trip is the reference stop.
// This value MUST be monotonically increasing and may only be a negative number if the first stop of the original trip is the reference stop.
Expand Down
19 changes: 5 additions & 14 deletions gtfs-realtime/spec/en/reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -135,9 +135,9 @@ A definition (or update) of an entity in the transit feed. If the entity is not
| **trip_update** | [TripUpdate](#message-tripupdate) | Conditionally required | One | Data about the realtime departure delays of a trip. At least one of the fields trip_update, vehicle, alert, or shape must be provided - all these fields cannot be empty. |
| **vehicle** | [VehiclePosition](#message-vehicleposition) | Conditionally required | One | Data about the realtime position of a vehicle. At least one of the fields trip_update, vehicle, alert, or shape must be provided - all these fields cannot be empty. |
| **alert** | [Alert](#message-alert) | Conditionally required | One | Data about the realtime alert. At least one of the fields trip_update, vehicle, alert, or shape must be provided - all these fields cannot be empty. |
| **shape** | [Shape](#message-shape) | Conditionally required | One | Data about the realtime added shapes, such as for a detour. At least one of the fields trip_update, vehicle, alert, or shape must be provided - all these fields cannot be empty. <br><br>**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. |
| **stop** | [Stop](#message-stop) | Conditionally required | One | A new stop added to the feed dynamically. <br><br>**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. |
| **trip_modifications** | [TripModifications)(#message-tripmodifications) | Conditionally required | One | List of trips affected by a particular modifications, such as a detour. <br><br>**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. |
| **shape** | [Shape](#message-shape) | Conditionally required | One | Data about the realtime added shapes, such as for a detour. At least one of the fields trip_update, vehicle, alert, or shape must be provided - all these fields cannot be empty. |
| **stop** | [Stop](#message-stop) | Conditionally required | One | A new stop added to the feed dynamically. |
| **trip_modifications** | [TripModifications](#message-tripmodifications) | Conditionally required | One | List of trips affected by a particular modifications, such as a detour. |


## _message_ TripUpdate
Expand Down Expand Up @@ -655,8 +655,6 @@ Represents a new Stop added to the feed dynamically. All fields are as described
## _message_ TripModifications

A `TripModifications` message identifies a list of similar trips which are all affected by particular modifications, such as a detour.

<br><br>**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.

[More about Trip Modifications...](trip-modifications.md)

Expand All @@ -673,8 +671,6 @@ A `TripModifications` message identifies a list of similar trips which are all a

A `Modification` message describes changes to each affected trip starting at `start_stop_selector`.

<br><br>**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.

![](images/trip_modification.png)
_An example showing the effect of a modification on a particular trip. This modification may also be applied to several other trips._

Expand All @@ -690,15 +686,14 @@ _Propagated detour delays affect all stops following the end of a modification.
| **end_stop_selector** | [StopSelector](#message-stopselector) | Conditionally required | One | The stop selector of the last stop of the original trip that is to be affected by this modification. The selection is inclusive, so if only one stop_time is replaced by that modification, `start_stop_selector` and `end_stop_selector` must be equivalent. If no stop_time is replaced, `end_stop_selector` must not be provided. It's otherwise required. |
| **propagated_modification_delay** | [int32](https://protobuf.dev/programming-guides/proto2/#scalar) | Optional | One | The number of seconds of delay to add to all departure and arrival times subsequent to the last stop inserted by a modification. If a modification affects only the shape (i.e. neither `end_stop_selector` nor `replacement_stops` are provided), then the delay propagation begins at the subsequent stop after `start_stop_selector`. Can be a positive or negative number. If multiple modifications apply to the same trip, the delays accumulate as the trip advances. <br/><br/>If the value is not supplied, consumers MAY interpolate or infer the `propagated_modification_delay` based on other data. |
| **replacement_stops** | [ReplacementStop](#message-replacementstop) | Optional | Many | A list of replacement stops, replacing those of the original trip. The length of the new stop times may be less, the same, or greater than the number of replaced stop times. |
| **service_alert_id** | [string](https://protobuf.dev/programming-guides/proto2/#scalar) | Optional | One | An `id` value from the `FeedEntity` message that contains the `Alert` describing this Modification for user-facing communication. |
| **service_alert_id** | [string](https://protobuf.dev/programming-guides/proto2/#scalar) | Optional | One | An `id` value from the `FeedEntity` message that contains the `Alert` describing this Modification for user-facing communication.<br><br>**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.
|
| **last_modified_time** | [uint64](https://protobuf.dev/programming-guides/proto2/#scalar) | Optional | One | This timestamp identifies the moment when the modification has last been changed. In POSIX time (i.e., number of seconds since January 1st 1970 00:00:00 UTC). |

## _message_ StopSelector

Selector for a stop. Either by `stop_id` or `stop_sequence`. At least one of the two values must be provided.

<br><br>**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.

**Fields**

| _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ |
Expand All @@ -710,8 +705,6 @@ Selector for a stop. Either by `stop_id` or `stop_sequence`. At least one of the

List of selected trips with an associated shape.

<br><br>**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.

**Fields**

| _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ |
Expand All @@ -723,8 +716,6 @@ List of selected trips with an associated shape.

Each `ReplacementStop` message defines a stop that will now be visited by the trip, and optionally specifies the estimated travel time to the stop.

<br><br>**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.

![](images/first_stop_reference.png)
_If a modification affects the first stop of the trip, that stop also serves as the reference stop of the modification._

Expand Down
2 changes: 0 additions & 2 deletions gtfs-realtime/spec/en/trip-modifications.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,6 @@

A `TripModifications` message identifies a list of similar `trip_ids` from the (CSV) GTFS which are all affected by particular modifications, such as a detour.

<br><br>**Caution:** this entity is still **experimental**, and subject to change. It may be formally adopted in the future.

## SLO: Service-level objective

The frequency of data updates is expected to be approximately hourly (~24 times/day). Ingestion time may depend on the total number of affected trips. Consumers are expected to ingest a single TripModification within 5 minutes, and a feed with hundreds of detours within 20 minutes.
Expand Down