Skip to content

Commit

Permalink
[Monthly update] October 2024 (#545)
Browse files Browse the repository at this point in the history 
* Update schedule reference

* Update Realtime Reference

* Update Feed Entities - Trip Modifications

* Update Proto page

* Update Proto file

* Update Realtime revision history

* ES translation

* Revert "Update Realtime revision history"

This reverts commit 5a9c59e.

* Update RT revision history

* Fix table formatting on RT Reference for ES & EN

* FR translation

* Small change in RT revision history for ES

* Minor FR language fixes
  • Loading branch information
@Sergiodero
Sergiodero authored Oct 29, 2024
1 parent 005c8ce commit 5bf394f
Show file tree
Hide file tree
Showing 18 changed files with 281 additions and 116 deletions.
4 changes: 4 additions & 0 deletions docs/en/documentation/realtime/change-history/revision-history.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,10 @@

### Revision History

#### October 2024

* Clarification and small changes for Trip Modifications. See [discussion](https://github.com/google/transit/pull/497).

#### March 2024

* Adopted Trip-Modifications. See [discussion](https://github.com/google/transit/pull/403).
Expand Down
2 changes: 1 addition & 1 deletion docs/en/documentation/realtime/feed-entities/trip-modifications.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ The scheduled stop times of each replacement trip are created from those of the

* A TripUpdate SHOULD be provided using a `ModifiedTripSelector` inside the TripUpdate's `TripDescriptor`.
* When the TripUpdate refers to the replacement trip, the consumer should behave as if the static GTFS would have been modified with the TripModifications (e.g. `arrival_time`, `departure_time`, `stop_sequence`, `stop_id` on replacement stops).
* When providing a `ModifiedTripSelector`, the other fields of the `TripDescriptor` MUST be left empty, to avoid confusion by consumers that aren't looking for the `ModifiedTripSelector` value.
* When providing a `ModifiedTripSelector`, the `trip_id`, `route_id`, `direction_id`, `start_time`, `start_date` fields of the `TripDescriptor` MUST be left empty, to avoid confusion by consumers that aren't looking for the `ModifiedTripSelector` value.
* TripUpdate feeds providing updates with `ModifiedTripSelector` SHOULD also include a TripUpdate targeting clients that don't support TripModifications. In other words, there should be two TripUpdates: one for clients with modified trips (with `TripModifications`) and one for clients with the originial unmodified GTFS (without `TripModifications`).
* Providing a TripUpdate with a `ModifiedTripSelector` is the only way to create predictions at replacement stops.
* If no such TripUpdate is found, TripUpdates for the original `trip_id` will apply to the modified trip.
Expand Down
51 changes: 34 additions & 17 deletions docs/en/documentation/realtime/gtfs-realtime.proto
View file
Original file line number Diff line number Diff line change
Expand Up @@ -220,7 +220,7 @@ message TripUpdate {
// In order to provide departure_occupancy_status without either arrival or
// departure StopTimeEvents, ScheduleRelationship should be set to NO_DATA.
optional VehiclePosition.OccupancyStatus departure_occupancy_status = 7;

// The relation between the StopTimeEvents and the static schedule.
enum ScheduleRelationship {
// The vehicle is proceeding in accordance with its static schedule of
Expand Down Expand Up @@ -252,7 +252,7 @@ message TripUpdate {
UNSCHEDULED = 3;
}
optional ScheduleRelationship schedule_relationship = 5
[default = SCHEDULED];
[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.
Expand Down Expand Up @@ -641,29 +641,29 @@ message Alert {

// Severity of this alert.
enum SeverityLevel {
UNKNOWN_SEVERITY = 1;
INFO = 2;
WARNING = 3;
SEVERE = 4;
UNKNOWN_SEVERITY = 1;
INFO = 2;
WARNING = 3;
SEVERE = 4;
}

optional SeverityLevel severity_level = 14 [default = UNKNOWN_SEVERITY];

// TranslatedImage to be displayed along the alert text. Used to explain visually the alert effect of a detour, station closure, etc. The image must enhance the understanding of the alert. Any essential information communicated within the image must also be contained in the alert text.
// The following types of images are discouraged : image containing mainly text, marketing or branded images that add no additional information.
// NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future.
optional TranslatedImage image = 15;
optional TranslatedImage image = 15;

// Text describing the appearance of the linked image in the `image` field (e.g., in case the image can't be displayed
// or the user can't see the image for accessibility reasons). See the HTML spec for alt image text - https://html.spec.whatwg.org/#alt.
// NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future.
optional TranslatedString image_alternative_text = 16;


// Description of the cause of the alert that allows for agency-specific language; more specific than the Cause. If cause_detail is included, then Cause must also be included.
// NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future.
optional TranslatedString cause_detail = 17;

// Description of the effect of the alert that allows for agency-specific language; more specific than the Effect. If effect_detail is included, then Effect must also be included.
// NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future.
optional TranslatedString effect_detail = 18;
Expand Down Expand Up @@ -810,7 +810,7 @@ message TripDescriptor {
CANCELED = 3;

// Should not be used - for backwards-compatibility only.
REPLACEMENT = 5 [deprecated=true];
REPLACEMENT = 5 [deprecated = true];

// An extra trip that was added in addition to a running schedule, for example, to replace a broken vehicle or to
// respond to sudden passenger load. Used with TripUpdate.TripProperties.trip_id, TripUpdate.TripProperties.start_date,
Expand Down Expand Up @@ -848,7 +848,24 @@ message TripDescriptor {

// The trip_id from the GTFS feed that is modified by the modifications_id
optional string affected_trip_id = 2;

// The initially scheduled start time of this trip instance, applied to the frequency based modified trip. Same definition as start_time in TripDescriptor.
optional string start_time = 3;

// The start date of this trip instance in YYYYMMDD format, applied to the modified trip. Same definition as start_date in TripDescriptor.
optional string start_date = 4;

// 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;
}

// Linkage to any modifications done to this trip (shape changes, removal or addition of stops).
// If this field is provided, the `trip_id`, `route_id`, `direction_id`, `start_time`, `start_date` fields of the `TripDescriptor` MUST be left empty, to avoid confusion by consumers that aren't looking for the `ModifiedTripSelector` value.
optional ModifiedTripSelector modified_trip = 7;

// The extensions namespace allows 3rd-party developers to extend the
Expand Down Expand Up @@ -1028,7 +1045,7 @@ message Shape {
// See https://developers.google.com/protocol-buffers/docs/proto#specifying_field_rules
// NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future.
optional string shape_id = 1;

// Encoded polyline representation of the shape. This polyline must contain at least two points.
// For more information about encoded polylines, see https://developers.google.com/maps/documentation/utilities/polylinealgorithm
// This field is required as per reference.md, but needs to be specified here optional because "Required is Forever"
Expand All @@ -1052,7 +1069,7 @@ message Stop {
UNKNOWN = 0;
AVAILABLE = 1;
NOT_AVAILABLE = 2;
}
}

optional string stop_id = 1;
optional TranslatedString stop_code = 2;
Expand Down Expand Up @@ -1130,9 +1147,9 @@ message TripModifications {

// The following extension IDs are reserved for private use by any organization.
extensions 9000 to 9999;
}
}

// A list of selected trips affected by this TripModifications.
// A list of selected trips affected by this TripModifications.
repeated SelectedTrips selected_trips = 1;

// A list of start times in the real-time trip descriptor for the trip_id defined in trip_ids.
Expand All @@ -1144,7 +1161,7 @@ message TripModifications {
repeated string service_dates = 3;

// A list of modifications to apply to the affected trips.
repeated Modification modifications = 4;
repeated Modification modifications = 4;

// The extensions namespace allows 3rd-party developers to extend the
// GTFS Realtime Specification in order to add and evaluate new features and
Expand All @@ -1157,7 +1174,7 @@ message TripModifications {

// 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 {
message StopSelector {
// Must be the same as in stop_times.txt in the corresponding GTFS feed.
optional uint32 stop_sequence = 1;
// Must be the same as in stops.txt in the corresponding GTFS feed.
Expand Down
51 changes: 34 additions & 17 deletions docs/en/documentation/realtime/proto.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -224,7 +224,7 @@ message TripUpdate {
// In order to provide departure_occupancy_status without either arrival or
// departure StopTimeEvents, ScheduleRelationship should be set to NO_DATA.
optional VehiclePosition.OccupancyStatus departure_occupancy_status = 7;
// The relation between the StopTimeEvents and the static schedule.
enum ScheduleRelationship {
// The vehicle is proceeding in accordance with its static schedule of
Expand Down Expand Up @@ -256,7 +256,7 @@ message TripUpdate {
UNSCHEDULED = 3;
}
optional ScheduleRelationship schedule_relationship = 5
[default = SCHEDULED];
[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.
Expand Down Expand Up @@ -645,29 +645,29 @@ message Alert {
// Severity of this alert.
enum SeverityLevel {
UNKNOWN_SEVERITY = 1;
INFO = 2;
WARNING = 3;
SEVERE = 4;
UNKNOWN_SEVERITY = 1;
INFO = 2;
WARNING = 3;
SEVERE = 4;
}
optional SeverityLevel severity_level = 14 [default = UNKNOWN_SEVERITY];
// TranslatedImage to be displayed along the alert text. Used to explain visually the alert effect of a detour, station closure, etc. The image must enhance the understanding of the alert. Any essential information communicated within the image must also be contained in the alert text.
// The following types of images are discouraged : image containing mainly text, marketing or branded images that add no additional information.
// NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future.
optional TranslatedImage image = 15;
optional TranslatedImage image = 15;
// Text describing the appearance of the linked image in the `image` field (e.g., in case the image can't be displayed
// or the user can't see the image for accessibility reasons). See the HTML spec for alt image text - https://html.spec.whatwg.org/#alt.
// NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future.
optional TranslatedString image_alternative_text = 16;
// Description of the cause of the alert that allows for agency-specific language; more specific than the Cause. If cause_detail is included, then Cause must also be included.
// NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future.
optional TranslatedString cause_detail = 17;
// Description of the effect of the alert that allows for agency-specific language; more specific than the Effect. If effect_detail is included, then Effect must also be included.
// NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future.
optional TranslatedString effect_detail = 18;
Expand Down Expand Up @@ -814,7 +814,7 @@ message TripDescriptor {
CANCELED = 3;
// Should not be used - for backwards-compatibility only.
REPLACEMENT = 5 [deprecated=true];
REPLACEMENT = 5 [deprecated = true];
// An extra trip that was added in addition to a running schedule, for example, to replace a broken vehicle or to
// respond to sudden passenger load. Used with TripUpdate.TripProperties.trip_id, TripUpdate.TripProperties.start_date,
Expand Down Expand Up @@ -852,7 +852,24 @@ message TripDescriptor {
// The trip_id from the GTFS feed that is modified by the modifications_id
optional string affected_trip_id = 2;
// The initially scheduled start time of this trip instance, applied to the frequency based modified trip. Same definition as start_time in TripDescriptor.
optional string start_time = 3;
// The start date of this trip instance in YYYYMMDD format, applied to the modified trip. Same definition as start_date in TripDescriptor.
optional string start_date = 4;
// 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;
}
// Linkage to any modifications done to this trip (shape changes, removal or addition of stops).
// If this field is provided, the `trip_id`, `route_id`, `direction_id`, `start_time`, `start_date` fields of the `TripDescriptor` MUST be left empty, to avoid confusion by consumers that aren't looking for the `ModifiedTripSelector` value.
optional ModifiedTripSelector modified_trip = 7;
// The extensions namespace allows 3rd-party developers to extend the
Expand Down Expand Up @@ -1032,7 +1049,7 @@ message Shape {
// See https://developers.google.com/protocol-buffers/docs/proto#specifying_field_rules
// NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future.
optional string shape_id = 1;
// Encoded polyline representation of the shape. This polyline must contain at least two points.
// For more information about encoded polylines, see https://developers.google.com/maps/documentation/utilities/polylinealgorithm
// This field is required as per reference.md, but needs to be specified here optional because "Required is Forever"
Expand All @@ -1056,7 +1073,7 @@ message Stop {
UNKNOWN = 0;
AVAILABLE = 1;
NOT_AVAILABLE = 2;
}
}
optional string stop_id = 1;
optional TranslatedString stop_code = 2;
Expand Down Expand Up @@ -1134,9 +1151,9 @@ message TripModifications {
// The following extension IDs are reserved for private use by any organization.
extensions 9000 to 9999;
}
}
// A list of selected trips affected by this TripModifications.
// A list of selected trips affected by this TripModifications.
repeated SelectedTrips selected_trips = 1;
// A list of start times in the real-time trip descriptor for the trip_id defined in trip_ids.
Expand All @@ -1148,7 +1165,7 @@ message TripModifications {
repeated string service_dates = 3;
// A list of modifications to apply to the affected trips.
repeated Modification modifications = 4;
repeated Modification modifications = 4;
// The extensions namespace allows 3rd-party developers to extend the
// GTFS Realtime Specification in order to add and evaluate new features and
Expand All @@ -1161,7 +1178,7 @@ message TripModifications {
// 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 {
message StopSelector {
// Must be the same as in stop_times.txt in the corresponding GTFS feed.
optional uint32 stop_sequence = 1;
// Must be the same as in stops.txt in the corresponding GTFS feed.
Expand Down
Loading

0 comments on commit 5bf394f

Please sign in to comment.