From 315c16d7561b4b8948c6f4426416cf1a12b11eb0 Mon Sep 17 00:00:00 2001 From: scmcca Date: Fri, 11 Feb 2022 09:30:58 -0500 Subject: [PATCH 1/8] Squashed commit of the following: MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit commit 2e6887ea16b689d8ebc70ad334ac8abb2f94a66e Author: scmcca Date: Wed Feb 2 12:42:10 2022 -0500 [Formatting fix] Add newlines before lists Improved syntax for different markdown parsers commit 00335731dc2893681d8b8611533bdfe7045f386b Author: Tristram Gräbener Date: Fri Jan 28 15:54:00 2022 +0100 Specify that the filename are case sensitive (#300) Closes #297 commit 23d877e5bc6a7f7d8721d32b792a0fc8ddd6c4c0 Author: scott christian mccallum Date: Tue Jan 18 19:09:46 2022 -0500 "Fields" and "Values" as non-header (#302) --- gtfs-realtime/spec/en/reference.md | 57 +++++++++++++++--------------- gtfs/spec/en/reference.md | 6 +++- 2 files changed, 34 insertions(+), 29 deletions(-) diff --git a/gtfs-realtime/spec/en/reference.md b/gtfs-realtime/spec/en/reference.md index 4a176e873..f5a92de5c 100644 --- a/gtfs-realtime/spec/en/reference.md +++ b/gtfs-realtime/spec/en/reference.md @@ -77,7 +77,7 @@ Fields labeled as **experimental** are subject to change and not yet formally ad The contents of a feed message. Each message in the stream is obtained as a response to an appropriate HTTP GET request. A realtime feed is always defined with relation to an existing GTFS feed. All the entity ids are resolved with respect to the GTFS feed. -#### Fields +**Fields** | _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ | |------------------|------------|----------------|-------------------|-------------------| @@ -88,7 +88,7 @@ The contents of a feed message. Each message in the stream is obtained as a resp Metadata about a feed, included in feed messages. -#### Fields +**Fields** | _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ | |------------------|------------|----------------|-------------------|-------------------| @@ -103,7 +103,7 @@ Determines whether the current fetch is incremental. * **FULL_DATASET**: this feed update will overwrite all preceding realtime information for the feed. Thus this update is expected to provide a full snapshot of all known realtime information. * **DIFFERENTIAL**: currently, this mode is **unsupported** and behavior is **unspecified** for feeds that use this mode. There are discussions on the [GTFS Realtime mailing list](http://groups.google.com/group/gtfs-realtime) around fully specifying the behavior of DIFFERENTIAL mode and the documentation will be updated when those discussions are finalized. -#### Values +**Values** | _**Value**_ | |-------------| @@ -114,7 +114,7 @@ Determines whether the current fetch is incremental. A definition (or update) of an entity in the transit feed. If the entity is not being deleted, exactly one of 'trip_update', 'vehicle', 'alert' and 'shape' fields should be populated. -#### Fields +**Fields** | _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ | |------------------|------------|----------------|-------------------|-------------------| @@ -145,7 +145,7 @@ If a vehicle is serving multiple trips within the same block (for more informati Note that the update can describe a trip that has already completed.To this end, it is enough to provide an update for the last stop of the trip. If the time of arrival at the last stop is in the past, the client will conclude that the whole trip is in the past (it is possible, although inconsequential, to also provide updates for preceding stops). This option is most relevant for a trip that has completed ahead of schedule, but according to the schedule, the trip is still proceeding at the current time. Removing the updates for this trip could make the client assume that the trip is still proceeding. Note that the feed provider is allowed, but not required, to purge past updates - this is one case where this would be practically useful. -#### Fields +**Fields** | _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ | |------------------|------------|----------------|-------------------|-------------------| @@ -165,7 +165,7 @@ Timing information for a single predicted event (either arrival or departure). T Uncertainty applies equally to both time and delay. The uncertainty roughly specifies the expected error in true delay (but note, we don't yet define its precise statistical meaning). It's possible for the uncertainty to be 0, for example for trains that are driven under computer timing control. -#### Fields +**Fields** | _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ | |------------------|------------|----------------|-------------------|-------------------| @@ -180,7 +180,7 @@ Realtime update for arrival and/or departure events for a given stop on a trip. Updates can be supplied for both past and future events. The producer is allowed, although not required, to drop past events. The update is linked to a specific stop either through stop_sequence or stop_id, so one of these fields must necessarily be set. If the same stop_id is visited more than once in a trip, then stop_sequence should be provided in all StopTimeUpdates for that stop_id on that trip. -#### Fields +**Fields** | _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ | |------------------|------------|----------------|-------------------|-------------------| @@ -196,7 +196,7 @@ The update is linked to a specific stop either through stop_sequence or stop_id, The relation between this StopTime and the static schedule. -#### Values +**Values** | _**Value**_ | _**Comment**_ | |-------------|---------------| @@ -211,7 +211,7 @@ 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 +**Fields** | _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ | |------------------|------------|----------------|-------------------|-------------------| @@ -223,7 +223,7 @@ Defines updated properties of the trip **Caution:** this message is still **experimental**, and subject to change. It may be formally adopted in the future.
. -#### Fields +**Fields** | _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ | |------------------|------------|----------------|-------------------|-------------------| @@ -236,7 +236,7 @@ Defines updated properties of the trip Realtime positioning information for a given vehicle. -#### Fields +**Fields** | _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ | |------------------|------------|----------------|-------------------|-------------------| @@ -255,7 +255,7 @@ Realtime positioning information for a given vehicle. ## _enum_ VehicleStopStatus -#### Values +**Values** | _**Value**_ | _**Comment**_ | |-------------|---------------| @@ -267,7 +267,7 @@ Realtime positioning information for a given vehicle. Congestion level that is affecting this vehicle. -#### Values +**Values** | _**Value**_ | |-------------| @@ -287,7 +287,7 @@ For describing passenger occupancy levels on a linear scale, see `occupancy_perc **Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. -#### _Values_ +***Values*** | _**Value**_ | _**Comment**_ | |-------------|---------------| @@ -308,7 +308,7 @@ Carriage specific details, used for vehicles composed of several carriages. **Caution:** this message is still **experimental**, and subject to change. It may be formally adopted in the future. -#### Fields +**Fields** | _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ | |------------------|------------|----------------|-------------------|-------------------| @@ -322,7 +322,7 @@ Carriage specific details, used for vehicles composed of several carriages. An alert, indicating some sort of incident in the public transit network. -#### Fields +**Fields** | _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ | |------------------|------------|----------------|-------------------|-------------------| @@ -344,7 +344,7 @@ An alert, indicating some sort of incident in the public transit network. Cause of this alert. -#### Values +**Values** | _**Value**_ | |-------------| @@ -365,7 +365,7 @@ Cause of this alert. The effect of this problem on the affected entity. -#### Values +**Values** | _**Value**_ | |-------------| @@ -387,7 +387,8 @@ The severity of the alert. **Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. -#### Values +**Values** + | _**Value**_ | |-------------| | **UNKNOWN_SEVERITY** | @@ -399,7 +400,7 @@ The severity of the alert. A time interval. The interval is considered active at time `t` if `t` is greater than or equal to the start time and less than the end time. -#### Fields +**Fields** | _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ | |------------------|------------|----------------|-------------------|-------------------| @@ -410,7 +411,7 @@ A time interval. The interval is considered active at time `t` if `t` is greater A geographic position of a vehicle. -#### Fields +**Fields** | _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ | |------------------|------------|----------------|-------------------|-------------------| @@ -437,7 +438,7 @@ Note that if the trip_id is not known, then station sequence ids in TripUpdate a TripDescriptor.route_id cannot be used within an Alert EntitySelector to specify a route-wide alert that affects all trips for a route - use EntitySelector.route_id instead. -#### Fields +**Fields** | _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ | |------------------|------------|----------------|-------------------|-------------------| @@ -452,7 +453,7 @@ TripDescriptor.route_id cannot be used within an Alert EntitySelector to specify The relation between this trip and the static schedule. If a trip is done in accordance with temporary schedule, not reflected in GTFS, then it shouldn't be marked as SCHEDULED, but marked as ADDED. -#### Values +**Values** | _**Value**_ | _**Comment**_ | |-------------|---------------| @@ -466,7 +467,7 @@ The relation between this trip and the static schedule. If a trip is done in acc Identification information for the vehicle performing the trip. -#### Fields +**Fields** | _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ | |------------------|------------|----------------|-------------------|-------------------| @@ -480,7 +481,7 @@ A selector for an entity in a GTFS feed. The values of the fields should corresp At least one specifier must be given - all fields in an EntitySelector cannot be empty. -#### Fields +**Fields** | _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ | |------------------|------------|----------------|-------------------|-------------------| @@ -495,7 +496,7 @@ At least one specifier must be given - all fields in an EntitySelector cannot be An internationalized message containing per-language versions of a snippet of text or a URL. One of the strings from a message will be picked up. The resolution proceeds as follows: If the UI language matches the language code of a translation, the first matching translation is picked. If a default UI language (e.g., English) matches the language code of a translation, the first matching translation is picked. If some translation has an unspecified language code, that translation is picked. -#### Fields +**Fields** | _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ | |------------------|------------|----------------|-------------------|-------------------| @@ -516,7 +517,7 @@ An internationalized message containing per-language versions of an image. One o **Caution:** this message is still **experimental**, and subject to change. It may be formally adopted in the future. -#### Fields +**Fields** | _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ | |------------------|------------|----------------|-------------------|-------------------| @@ -538,7 +539,7 @@ Describes the physical path that a vehicle takes when the shape is not part of t **Caution:** this message is still **experimental**, and subject to change. It may be formally adopted in the future.
. -#### Fields +**Fields** | _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ | |------------------|------------|----------------|-------------------|-------------------| diff --git a/gtfs/spec/en/reference.md b/gtfs/spec/en/reference.md index 71fa7b351..7f8ff23aa 100644 --- a/gtfs/spec/en/reference.md +++ b/gtfs/spec/en/reference.md @@ -45,6 +45,7 @@ This section defines terms that are used throughout this document. ### Presence Presence conditions applicable to fields and files: + * **Required** - The field or file must be included in the dataset and contain a valid value for each record. * **Optional** - The field or file may be omitted from the dataset. * **Conditionally Required** - The field or file must be included under conditions outlined in the field or file description. @@ -70,6 +71,7 @@ Presence conditions applicable to fields and files: ### Field Signs Signs applicable to Float or Integer field types: + * **Non-negative** - Greater than or equal to 0. * **Non-zero** - Not equal to 0. * **Positive** - Greater than 0. @@ -111,7 +113,7 @@ The following requirements apply to the format and contents of the dataset files * All files must be saved as comma-delimited text. * The first line of each file must contain field names. Each subsection of the [Field Definitions](#field-definitions) section corresponds to one of the files in a GTFS dataset and lists the field names that may be used in that file. -* All field names are case-sensitive. +* All file and field names are case-sensitive. * Field values must not contain tabs, carriage returns or new lines. * Field values that contain quotation marks or commas must be enclosed within quotation marks. In addition, each quotation mark in the field value must be preceded with a quotation mark. This is consistent with the manner in which Microsoft Excel outputs comma-delimited (CSV) files. For more information on the CSV file format, see [http://tools.ietf.org/html/rfc4180](http://tools.ietf.org/html/rfc4180). The following example demonstrates how a field value would appear in a comma-delimited file: @@ -363,6 +365,7 @@ Primary key (`from_stop_id`, `to_stop_id`, `from_trip_id`, `to_trip_id`, `from_r When calculating an itinerary, GTFS-consuming applications interpolate transfers based on allowable time and stop proximity. [Transfers.txt](#transferstxt) specifies additional rules and overrides for selected transfers. Fields `from_trip_id`, `to_trip_id`, `from_route_id` and `to_route_id` allow higher orders of specificity for transfer rules. Along with `from_stop_id` and `to_stop_id`, the ranking of specificity is as follows: + 1. Both `trip_id`s defined: `from_trip_id` and `to_trip_id`. 2. One `trip_id` and `route_id` set defined: (`from_trip_id` and `to_route_id`) or (`from_route_id` and `to_trip_id`). 3. One `trip_id` defined: `from_trip_id` or `to_trip_id`. @@ -394,6 +397,7 @@ Files [pathways.txt](#pathwaystxt) and [levels.txt](levelstxt) use a graph repre To navigate from the station entrance/exit (a node represented as a location with `location_type=2`) to a platform (a node represented as a location with `location_type=0` or empty), the rider will move through walkways, fare gates, stairs, and other edges represented as pathways. Generic nodes (nodes represented with `location_type=3`) can be used to connect pathways throughout a station. Pathways must be defined exhaustively in a station. If any pathways are defined, it is assumed that all pathways throughout the station are represented. Therefore, the following guidelines apply: + - No dangling locations: If any location within a station has a pathway, then all locations within that station should have pathways, except for platforms that have boarding areas (`location_type=4`, see guideline below). - No pathways for a platform with boarding areas: A platform (`location_type=0` or empty) that has boarding areas (`location_type=4`) is treated as a parent object, not a point. In such cases, the platform must not have pathways assigned. All pathways should be assigned for each of the platform's boarding areas. - No locked platforms: Each platform (`location_type=0` or empty) or boarding area (`location_type=4`) must be connected to at least one entrance/exit (`location_type=2`) via some chain of pathways. Stations not allowing a pathway to the outside of the station from a given platform are rare. 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 2/8] 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 7672a94ba..8ee20f0e1 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 f5a92de5c..a50ee6e94 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 a0cc75a9a..b3c39ec39 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** From c23503189e8f70c3a30bccea1806845057691d57 Mon Sep 17 00:00:00 2001 From: Emma Blue <90632321+emmambd@users.noreply.github.com> Date: Thu, 11 May 2023 09:19:25 -0400 Subject: [PATCH 3/8] Update README.md (#63) --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index ed3e2f7b5..0b39729f1 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,5 @@ +MobilityData's internal fork of the Official GTFS Specification repository. This fork is used to draft pull requests before sharing them on the official repo. [Go to the official repo to ask questions and open issues](https://github.com/google/transit). + The repository contains specification to manipulate General Transit Feed Specification (GTFS) and GTFS Realtime: * [GTFS](/gtfs/README.md) From 670bb424b4abaf7e882575aaa87cd59296971d97 Mon Sep 17 00:00:00 2001 From: Emma Jae Blue Date: Wed, 17 May 2023 12:51:21 -0400 Subject: [PATCH 4/8] issue templates --- .github/ISSUE_TEMPLATE/config.yml | 4 ++ .github/ISSUE_TEMPLATE/extension_proposal.yml | 37 +++++++++++++++++++ .github/ISSUE_TEMPLATE/question.yml | 21 +++++++++++ .github/ISSUE_TEMPLATE/spec_improvement.yml | 37 +++++++++++++++++++ 4 files changed, 99 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/extension_proposal.yml create mode 100644 .github/ISSUE_TEMPLATE/question.yml create mode 100644 .github/ISSUE_TEMPLATE/spec_improvement.yml diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 000000000..15773535b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,4 @@ +contact_links: + - name: Slack channel + url: https://share.mobilitydata.org/slack + about: Join the gtfs channel to discuss with other community members, and receive updates. \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/extension_proposal.yml b/.github/ISSUE_TEMPLATE/extension_proposal.yml new file mode 100644 index 000000000..4350f59d6 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/extension_proposal.yml @@ -0,0 +1,37 @@ +name: Extension proposal +description: Propose a major change to the spec. Examples of extension proposal include [GTFS-Fares v2](https://gtfs.org/extensions/fares-v2/) or [GTFS-TripModifications](https://github.com/google/transit/issues/369). +labels: ['extension-proposal'] + +body: + - type: markdown + attributes: + value: > + #### Before submitting a new extension proposal, please make sure there isn't an already [existing extension proposal](https://gtfs.org/extensions/). + - type: textarea + attributes: + label: Describe the problem + description: > + Describe what you are trying to achieve, and how the spec is making it difficult. + validations: + required: true + - type: textarea + attributes: + label: Use cases + description: > + Share examples of the scenarios you want the proposal to address, e.g GTFS-Fares v2 makes it possible to display the cost of a monthly pass. + validations: + required: true + - type: textarea + attributes: + label: Proposed solution + description: > + A clear description of what you want to happen. + validations: + required: true + - type: textarea + attributes: + label: Additional information + description: > + Additional information that can help the community better understand your need. + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/question.yml b/.github/ISSUE_TEMPLATE/question.yml new file mode 100644 index 000000000..af28b569d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/question.yml @@ -0,0 +1,21 @@ +name: Question +description: Ask a question or raise a problem without a proposed solution. +labels: ['question'] + +body: + - type: markdown + attributes: + value: > + #### Before submitting a question, please make sure there isn't an already [existing issue for it](https://github.com/google/transit/issues?q=+is%3Aissue+label%3Aquestion+). + - type: textarea + attributes: + label: Introduce yourself + description: > + If you are new to the specification, please introduce yourself (name and organization/link to your GTFS feed)! + validations: + required: false + - type: textarea + attributes: + label: Ask a question + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/spec_improvement.yml b/.github/ISSUE_TEMPLATE/spec_improvement.yml new file mode 100644 index 000000000..989b78343 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/spec_improvement.yml @@ -0,0 +1,37 @@ +name: Spec improvement +description: Propose an update to the existing spec, such as clarifying descriptions or adding new fields. +labels: ['improvement'] + +body: + - type: markdown + attributes: + value: > + #### Before submitting a spec improvement, please make sure there isn't an already [existing issue](https://github.com/google/transit/issues?q=+is%3Aissue+label%3Aimprovement). + - type: textarea + attributes: + label: Describe the problem + description: > + Describe what you are trying to achieve, and how the spec is making it difficult. Describe any other means you currently use to get the job done or to have the information you need. + validations: + required: true + - type: textarea + attributes: + label: Use cases + description: > + Share examples of scenarios you want the improvement to address. [Here's a great example of communicating a complex use case](https://github.com/google/transit/pull/352#issuecomment-1284756181). + validations: + required: true + - type: textarea + attributes: + label: Proposed solution + description: > + A clear description of what you want to happen that includes the GTFS files and fields affected. + validations: + required: true + - type: textarea + attributes: + label: Additional information + description: > + Additional information that can help the community better understand your need. + validations: + required: false From 6aba4751cbca9e67c74028e3f0abb31f53c7ca70 Mon Sep 17 00:00:00 2001 From: Emma Blue <90632321+emmambd@users.noreply.github.com> Date: Thu, 14 Dec 2023 16:05:48 -0500 Subject: [PATCH 5/8] update use cases section --- .github/ISSUE_TEMPLATE/extension_proposal.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/ISSUE_TEMPLATE/extension_proposal.yml b/.github/ISSUE_TEMPLATE/extension_proposal.yml index 4350f59d6..c4f41b52a 100644 --- a/.github/ISSUE_TEMPLATE/extension_proposal.yml +++ b/.github/ISSUE_TEMPLATE/extension_proposal.yml @@ -18,7 +18,7 @@ body: attributes: label: Use cases description: > - Share examples of the scenarios you want the proposal to address, e.g GTFS-Fares v2 makes it possible to display the cost of a monthly pass. + Share examples of the scenarios you want the proposal to address, e.g GTFS-Fares v2 makes it possible to display the cost of a monthly pass. Show visuals of how it will appear to riders where relevant. validations: required: true - type: textarea From 7dba1d50e485a8bc72b9f306245606e7f9a48aa8 Mon Sep 17 00:00:00 2001 From: Emma Blue <90632321+emmambd@users.noreply.github.com> Date: Thu, 14 Dec 2023 16:11:05 -0500 Subject: [PATCH 6/8] update contact links --- .github/ISSUE_TEMPLATE/config.yml | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 15773535b..b9d7f9b9a 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1,4 +1,13 @@ contact_links: - - name: Slack channel + - name: GTFS.org + - url: https://gtfs.org/ + - about: The official reference for GTFS documentation. + - name: GTFS Changes Google Group + - url: https://groups.google.com/g/gtfs-changes + - about: Follow this group to get announcement on votes on the GTFS Schedule specification. + - name: GTFS Realtime Google Group + - url: https://groups.google.com/g/gtfs-realtime + - about: This group is the forum for discussing the GTFS Realtime specification, asking questions, and proposing changes. + - name: GTFS Slack Channel url: https://share.mobilitydata.org/slack - about: Join the gtfs channel to discuss with other community members, and receive updates. \ No newline at end of file + about: Join the gtfs channel to discuss with other community members, and receive updates. From d6fd0119ab0dd844789fce9d654d20498d6de500 Mon Sep 17 00:00:00 2001 From: Emma Blue <90632321+emmambd@users.noreply.github.com> Date: Thu, 14 Dec 2023 16:24:10 -0500 Subject: [PATCH 7/8] rename --- .../{extension_proposal.yml => spec_change.yml} | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) rename .github/ISSUE_TEMPLATE/{extension_proposal.yml => spec_change.yml} (62%) diff --git a/.github/ISSUE_TEMPLATE/extension_proposal.yml b/.github/ISSUE_TEMPLATE/spec_change.yml similarity index 62% rename from .github/ISSUE_TEMPLATE/extension_proposal.yml rename to .github/ISSUE_TEMPLATE/spec_change.yml index c4f41b52a..81a643684 100644 --- a/.github/ISSUE_TEMPLATE/extension_proposal.yml +++ b/.github/ISSUE_TEMPLATE/spec_change.yml @@ -1,24 +1,24 @@ -name: Extension proposal -description: Propose a major change to the spec. Examples of extension proposal include [GTFS-Fares v2](https://gtfs.org/extensions/fares-v2/) or [GTFS-TripModifications](https://github.com/google/transit/issues/369). -labels: ['extension-proposal'] +name: Specification change +description: Propose a change to the specification. +labels: ['spec-change'] body: - type: markdown attributes: value: > - #### Before submitting a new extension proposal, please make sure there isn't an already [existing extension proposal](https://gtfs.org/extensions/). + #### Before submitting a new change, please make sure the same one isn't already [proposed in an issue](https://github.com/google/transit/issues). - type: textarea attributes: label: Describe the problem description: > - Describe what you are trying to achieve, and how the spec is making it difficult. + Describe what you are trying to achieve. validations: required: true - type: textarea attributes: label: Use cases description: > - Share examples of the scenarios you want the proposal to address, e.g GTFS-Fares v2 makes it possible to display the cost of a monthly pass. Show visuals of how it will appear to riders where relevant. + Share examples of the scenarios you want the proposal to address, e.g GTFS-Fares v2 makes it possible to display the cost of a monthly pass. Show visuals of how it will appear to riders where relevant. [Here's a great example of communicating a complex use case](https://github.com/google/transit/pull/352#issuecomment-1284756181). validations: required: true - type: textarea From 3c7c0be31702313cffb350cad9cdec445f0d855c Mon Sep 17 00:00:00 2001 From: Emma Blue <90632321+emmambd@users.noreply.github.com> Date: Thu, 14 Dec 2023 16:24:25 -0500 Subject: [PATCH 8/8] Delete .github/ISSUE_TEMPLATE/spec_improvement.yml --- .github/ISSUE_TEMPLATE/spec_improvement.yml | 37 --------------------- 1 file changed, 37 deletions(-) delete mode 100644 .github/ISSUE_TEMPLATE/spec_improvement.yml diff --git a/.github/ISSUE_TEMPLATE/spec_improvement.yml b/.github/ISSUE_TEMPLATE/spec_improvement.yml deleted file mode 100644 index 989b78343..000000000 --- a/.github/ISSUE_TEMPLATE/spec_improvement.yml +++ /dev/null @@ -1,37 +0,0 @@ -name: Spec improvement -description: Propose an update to the existing spec, such as clarifying descriptions or adding new fields. -labels: ['improvement'] - -body: - - type: markdown - attributes: - value: > - #### Before submitting a spec improvement, please make sure there isn't an already [existing issue](https://github.com/google/transit/issues?q=+is%3Aissue+label%3Aimprovement). - - type: textarea - attributes: - label: Describe the problem - description: > - Describe what you are trying to achieve, and how the spec is making it difficult. Describe any other means you currently use to get the job done or to have the information you need. - validations: - required: true - - type: textarea - attributes: - label: Use cases - description: > - Share examples of scenarios you want the improvement to address. [Here's a great example of communicating a complex use case](https://github.com/google/transit/pull/352#issuecomment-1284756181). - validations: - required: true - - type: textarea - attributes: - label: Proposed solution - description: > - A clear description of what you want to happen that includes the GTFS files and fields affected. - validations: - required: true - - type: textarea - attributes: - label: Additional information - description: > - Additional information that can help the community better understand your need. - validations: - required: false