From 6a4e18605c48635af3f1c7236be0b25839740984 Mon Sep 17 00:00:00 2001 From: omar-kabbani <78552622+omar-kabbani@users.noreply.github.com> Date: Thu, 4 Aug 2022 15:10:35 -0400 Subject: [PATCH] Squashed commit of the following: commit 9d5ebf1277f83178ba041de208f200d2d00cf5e7 Author: Guillaume Campagna Date: Tue Jul 26 17:09:35 2022 -0400 Add trip-to-trip transfers with in-seat option (#303) * Add trip-to-trip transfers with in-seat option * Fix stop_id are **Conditionally Required** and formatting * Add clarification about potential conflict * Fix typo Co-authored-by: Leonard Ehrenfried Co-authored-by: Nicholas Paun Co-authored-by: Leonard Ehrenfried commit a1327095811f6c388f5ea48272805a73e4ae4c5c Author: McKenzie Maidl <40008048+mckenzie-maidl-ibigroup@users.noreply.github.com> Date: Tue Jul 26 13:58:04 2022 -0700 addition of cause_detail and effect_detail to the spec (#332) commit 8993a244f3e90ebac5654d669adbfdf69a70be2d Author: Zsombor Welker Date: Mon Jul 25 14:49:40 2022 +0200 Add WheelchairAccessible documentation (#340) --- gtfs-realtime/proto/gtfs-realtime.proto | 33 +++++++++++++++++++-- gtfs-realtime/spec/en/reference.md | 22 ++++++++++++-- gtfs/spec/en/reference.md | 38 +++++++++++++++++++++---- 3 files changed, 83 insertions(+), 10 deletions(-) diff --git a/gtfs-realtime/proto/gtfs-realtime.proto b/gtfs-realtime/proto/gtfs-realtime.proto index 7672a94b..8ee20f0e 100644 --- a/gtfs-realtime/proto/gtfs-realtime.proto +++ b/gtfs-realtime/proto/gtfs-realtime.proto @@ -583,7 +583,7 @@ message Alert { // Entities whose users we should notify of this alert. repeated EntitySelector informed_entity = 5; - // Cause of this alert. + // Cause of this alert. If cause_detail is included, then Cause must also be included. enum Cause { UNKNOWN_CAUSE = 1; OTHER_CAUSE = 2; // Not machine-representable. @@ -600,7 +600,7 @@ message Alert { } optional Cause cause = 6 [default = UNKNOWN_CAUSE]; - // What is the effect of this problem on the affected entity. + // What is the effect of this problem on the affected entity. If effect_detail is included, then Effect must also be included. enum Effect { NO_SERVICE = 1; REDUCED_SERVICE = 2; @@ -656,6 +656,15 @@ message Alert { // 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; // The extensions namespace allows 3rd-party developers to extend the // GTFS Realtime Specification in order to add and evaluate new features @@ -843,6 +852,26 @@ message VehicleDescriptor { // The license plate of the vehicle. optional string license_plate = 3; + enum WheelchairAccessible { + // The trip doesn't have information about wheelchair accessibility. + // This is the **default** behavior. If the static GTFS contains a + // _wheelchair_accessible_ value, it won't be overwritten. + NO_VALUE = 0; + + // The trip has no accessibility value present. + // This value will overwrite the value from the GTFS. + UNKNOWN = 1; + + // The trip is wheelchair accessible. + // This value will overwrite the value from the GTFS. + WHEELCHAIR_ACCESSIBLE = 2; + + // The trip is **not** wheelchair accessible. + // This value will overwrite the value from the GTFS. + WHEELCHAIR_INACCESSIBLE = 3; + } + optional WheelchairAccessible wheelchair_accessible = 4 [default = NO_VALUE]; + // 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. diff --git a/gtfs-realtime/spec/en/reference.md b/gtfs-realtime/spec/en/reference.md index f5a92de5..a50ee6e9 100644 --- a/gtfs-realtime/spec/en/reference.md +++ b/gtfs-realtime/spec/en/reference.md @@ -46,6 +46,7 @@ Fields labeled as **experimental** are subject to change and not yet formally ad * [TripDescriptor](#message-tripdescriptor) * [ScheduleRelationship](#enum-schedulerelationship-1) * [VehicleDescriptor](#message-vehicledescriptor) + * [WheelchairAccessible](#enum-wheelchairaccessible) * [StopTimeUpdate](#message-stoptimeupdate) * [StopTimeEvent](#message-stoptimeevent) * [ScheduleRelationship](#enum-schedulerelationship) @@ -55,6 +56,7 @@ Fields labeled as **experimental** are subject to change and not yet formally ad * [TripDescriptor](#message-tripdescriptor) * [ScheduleRelationship](#enum-schedulerelationship-1) * [VehicleDescriptor](#message-vehicledescriptor) + * [WheelchairAccessible](#enum-wheelchairaccessible) * [Position](#message-position) * [VehicleStopStatus](#enum-vehiclestopstatus) * [CongestionLevel](#enum-congestionlevel) @@ -328,8 +330,10 @@ An alert, indicating some sort of incident in the public transit network. |------------------|------------|----------------|-------------------|-------------------| | **active_period** | [TimeRange](#message-timerange) | Optional | Many | Time when the alert should be shown to the user. If missing, the alert will be shown as long as it appears in the feed. If multiple ranges are given, the alert will be shown during all of them. | | **informed_entity** | [EntitySelector](#message-entityselector) | Required | Many | Entities whose users we should notify of this alert. At least one informed_entity must be provided. | -| **cause** | [Cause](#enum-cause) | Optional | One | -| **effect** | [Effect](#enum-effect) | Optional | One | +| **cause** | [Cause](#enum-cause) | Conditionally Required | One | If cause_detail is included, then Cause must also be included. +| **cause_detail** | [TranslatedString](#message-translatedstring) | Optional | One | 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.

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. +| **effect** | [Effect](#enum-effect) | Conditionally Required | One | If effect_detail is included, then Effect must also be included. +| **effect_detail** | [TranslatedString](#message-translatedstring) | Optional | One | 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.

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | **url** | [TranslatedString](#message-translatedstring) | Optional | One | The URL which provides additional information about the alert. | | **header_text** | [TranslatedString](#message-translatedstring) | Required | One | Header for the alert. This plain-text string will be highlighted, for example in boldface. | | **description_text** | [TranslatedString](#message-translatedstring) | Required | One | Description for the alert. This plain-text string will be formatted as the body of the alert (or shown on an explicit "expand" request by the user). The information in the description should add to the information of the header. | @@ -474,6 +478,20 @@ Identification information for the vehicle performing the trip. | **id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | Internal system identification of the vehicle. Should be **unique** per vehicle, and is used for tracking the vehicle as it proceeds through the system. This id should not be made visible to the end-user; for that purpose use the **label** field | | **label** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | User visible label, i.e., something that must be shown to the passenger to help identify the correct vehicle. | | **license_plate** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | The license plate of the vehicle. | +| **wheelchair_accessible** | [WheelchairAccessible](#enum-wheelchairaccessible) | Optional | One | If provided, can overwrite the *wheelchair_accessible* value from the static GTFS. | + +## _enum_ WheelchairAccessible + +If a particuliar trip is accessible to wheelchair. When available, this value should overwrite the _wheelchair_accessible_ value from the static GTFS. + +#### Values + +| _**Value**_ | _**Comment**_ | +|-------------|---------------| +| **NO_VALUE** | The trip doesn't have information about wheelchair accessibility. This is the **default** behavior. If the static GTFS contains a _wheelchair_accessible_ value, it won't be overwritten. | +| **UNKNOWN** | The trip has no accessibility value present. This value will overwrite the value from the GTFS. | +| **WHEELCHAIR_ACCESSIBLE** | The trip is wheelchair accessible. This value will overwrite the value from the GTFS. | +| **WHEELCHAIR_INACCESSIBLE** | The trip is **not** wheelchair accessible. This value will overwrite the value from the GTFS. | ## _message_ EntitySelector diff --git a/gtfs/spec/en/reference.md b/gtfs/spec/en/reference.md index a0cc75a9..b3c39ec3 100644 --- a/gtfs/spec/en/reference.md +++ b/gtfs/spec/en/reference.md @@ -221,7 +221,7 @@ Primary key (`trip_id`) | `trip_headsign` | Text | Optional | Text that appears on signage identifying the trip's destination to riders. Should be used to distinguish between different patterns of service on the same route.

If the headsign changes during a trip, values for `trip_headsign` may be overridden by defining values in `stop_times.stop_headsign` for specific `stop_time`s along the trip. | | `trip_short_name` | Text | Optional | Public facing text used to identify the trip to riders, for instance, to identify train numbers for commuter rail trips. If riders do not commonly rely on trip names, `trip_short_name` should be empty. A `trip_short_name` value, if provided, should uniquely identify a trip within a service day; it should not be used for destination names or limited/express designations. | | `direction_id` | Enum | Optional | Indicates the direction of travel for a trip. This field should not be used in routing; it provides a way to separate trips by direction when publishing time tables. Valid options are:

`0` - Travel in one direction (e.g. outbound travel).
`1` - Travel in the opposite direction (e.g. inbound travel).
*Example: The `trip_headsign` and `direction_id` fields may be used together to assign a name to travel in each direction for a set of trips. A [trips.txt](#tripstxt) file could contain these records for use in time tables:*
`trip_id,...,trip_headsign,direction_id`
`1234,...,Airport,0`
`1505,...,Downtown,1` | -| `block_id` | ID | Optional | Identifies the block to which the trip belongs. A block consists of a single trip or many sequential trips made using the same vehicle, defined by shared service days and `block_id`. A `block_id` may have trips with different service days, making distinct blocks. See the [example below](#example-blocks-and-service-day) | +| `block_id` | ID | Optional | Identifies the block to which the trip belongs. A block consists of a single trip or many sequential trips made using the same vehicle, defined by shared service days and `block_id`. A `block_id` may have trips with different service days, making distinct blocks. See the [example below](#example-blocks-and-service-day). To provide in-seat transfers information, [transfers](#transferstxt) of `transfer_type` `4` should be provided instead. | | `shape_id` | Foreign ID referencing `shapes.shape_id` | **Conditionally Required** | Identifies a geospatial shape describing the vehicle travel path for a trip.

Conditionally Required:
- **Required** if the trip has a continuous pickup or drop-off behavior defined either in `routes.txt` or in `stop_times.txt`.
- Optional otherwise. | | `wheelchair_accessible` | Enum | Optional | Indicates wheelchair accessibility. Valid options are:

`0` or empty - No accessibility information for the trip.
`1` - Vehicle being used on this particular trip can accommodate at least one rider in a wheelchair.
`2` - No riders in wheelchairs can be accommodated on this trip. | | `bikes_allowed` | Enum | Optional | Indicates whether bikes are allowed. Valid options are:

`0` or empty - No bike information for the trip.
`1` - Vehicle being used on this particular trip can accommodate at least one bicycle.
`2` - No bicycles are allowed on this trip. | @@ -514,15 +514,41 @@ For a given ordered pair of arriving trip and departing trip, the transfer with | Field Name | Type | Presence | Description | | ------ | ------ | ------ | ------ | -| `from_stop_id` | Foreign ID referencing `stops.stop_id` | **Required** | Identifies a stop or station where a connection between routes begins. If this field refers to a station, the transfer rule applies to all its child stops. | -| `to_stop_id` | Foreign ID referencing `stops.stop_id` | **Required** | Identifies a stop or station where a connection between routes ends. If this field refers to a station, the transfer rule applies to all child stops. | +| `from_stop_id` | Foreign ID referencing `stops.stop_id` | **Conditionally Required** | Identifies a stop or station where a connection between routes begins. If this field refers to a station, the transfer rule applies to all its child stops. Refering to a station is forbiden for `transfer_types` 4 and 5. | +| `to_stop_id` | Foreign ID referencing `stops.stop_id` | **Conditionally Required** | Identifies a stop or station where a connection between routes ends. If this field refers to a station, the transfer rule applies to all child stops. Refering to a station is forbiden for `transfer_types` 4 and 5. | | `from_route_id` | Foreign ID referencing `routes.route_id` | Optional | Identifies a route where a connection begins.

If `from_route_id` is defined, the transfer will apply to the arriving trip on the route for the given `from_stop_id`.

If both `from_trip_id` and `from_route_id` are defined, the `trip_id` must belong to the `route_id`, and `from_trip_id` will take precedence. | | `to_route_id` | Foreign ID referencing `routes.route_id` | Optional | Identifies a route where a connection ends.

If `to_route_id` is defined, the transfer will apply to the departing trip on the route for the given `to_stop_id`.

If both `to_trip_id` and `to_route_id` are defined, the `trip_id` must belong to the `route_id`, and `to_trip_id` will take precedence. | -| `from_trip_id` | Foreign ID referencing `trips.trip_id` | Optional | Identifies a trip where a connection between routes begins.

If `from_trip_id` is defined, the transfer will apply to the arriving trip for the given `from_stop_id`.

If both `from_trip_id` and `from_route_id` are defined, the `trip_id` must belong to the `route_id`, and `from_trip_id` will take precedence. | -| `to_trip_id` | Foreign ID referencing `trips.trip_id` | Optional | Identifies a trip where a connection between routes ends.

If `to_trip_id` is defined, the transfer will apply to the departing trip for the given `to_stop_id`.

If both `to_trip_id` and `to_route_id` are defined, the `trip_id` must belong to the `route_id`, and `to_trip_id` will take precedence. | -| `transfer_type` | Enum | **Required** | Indicates the type of connection for the specified (`from_stop_id`, `to_stop_id`) pair. Valid options are:

`0` or empty - Recommended transfer point between routes.
`1` - Timed transfer point between two routes. The departing vehicle is expected to wait for the arriving one and leave sufficient time for a rider to transfer between routes.
`2` - Transfer requires a minimum amount of time between arrival and departure to ensure a connection. The time required to transfer is specified by `min_transfer_time`.
`3` - Transfers are not possible between routes at the location. | +| `from_trip_id` | Foreign ID referencing `trips.trip_id` | **Conditionally Required** | Identifies a trip where a connection between routes begins.

If `from_trip_id` is defined, the transfer will apply to the arriving trip for the given `from_stop_id`.

If both `from_trip_id` and `from_route_id` are defined, the `trip_id` must belong to the `route_id`, and `from_trip_id` will take precedence. REQUIRED if `transfer_type` is `4` or `5`. | +| `to_trip_id` | Foreign ID referencing `trips.trip_id` | **Conditionally Required** | Identifies a trip where a connection between routes ends.

If `to_trip_id` is defined, the transfer will apply to the departing trip for the given `to_stop_id`.

If both `to_trip_id` and `to_route_id` are defined, the `trip_id` must belong to the `route_id`, and `to_trip_id` will take precedence. REQUIRED if `transfer_type` is `4` or `5`. | +| `transfer_type` | Enum | **Required** | Indicates the type of connection for the specified (`from_stop_id`, `to_stop_id`) pair. Valid options are:

`0` or empty - Recommended transfer point between routes.
`1` - Timed transfer point between two routes. The departing vehicle is expected to wait for the arriving one and leave sufficient time for a rider to transfer between routes.
`2` - Transfer requires a minimum amount of time between arrival and departure to ensure a connection. The time required to transfer is specified by `min_transfer_time`.
`3` - Transfers are not possible between routes at the location.
`4` - Passengers can transfer from one trip to another by staying onboard the same vehicle (an "in-seat transfer"). More details about this type of transfer [below](#linked-trips).
`5` - In-seat transfers are not allowed between sequential trips. The passenger must alight from the vehicle and re-board. More details about this type of transfer [below](#linked-trips). | | `min_transfer_time` | Non-negative integer | Optional | Amount of time, in seconds, that must be available to permit a transfer between routes at the specified stops. The `min_transfer_time` should be sufficient to permit a typical rider to move between the two stops, including buffer time to allow for schedule variance on each route. | +#### Linked trips + +The following applies to `transfer_type=4` and `=5`, which are used to link trips together, with or without in-seats transfers. + +The trips linked together MUST be operated by the same vehicle. The vehicle MAY be coupled to, or uncoupled from, other vehicles. + +If both a linked trips transfer and a block_id are provided and they produce conflicting results, then the linked trips transfer shall be used. + +The last stop of `from_trip_id` SHOULD be geographically close to the first stop of `to_trip_id`, and the last arrival time of `from_trip_id` SHOULD be prior but close to the first departure time of `to_trip_id`. The last arrival time of `from_trip_id` MAY be later than the first departure time of `to_trip_id` in case the `to_trip_id` trip is occurring the subsequent service day. + +Trips MAY be linked 1-to-1 in the regular case, but MAY also be linked 1-to-n, n-to-1, or n-to-n to represent more complex trip continuations. For example, two train trips (trip A and trip B in the diagram below) can merge into a single train trip (trip C) after a vehicle coupling operation at a common station: + +- In a 1-to-n continuation, the `trips.service_id` for each `to_trip_id` MUST be identical. +- In an n-to-1 continuation, the `trips.service_id` for each `from_trip_id` MUST be identical. +- n-to-n continuations must respect both constraints. +- Trips may be linked together as part of multiple distinct continuations, provided that the `trip.service_id` MUST NOT overlap on any day of service. + +
+Trip A
+───────────────────\
+                    \    Trip C
+                     ─────────────
+Trip B              /
+───────────────────/
+
+ ### pathways.txt File: **Optional**