From fec8338bf6fa1eb684188cccdd65fb0ec433455c Mon Sep 17 00:00:00 2001 From: Guillaume Campagna Date: Wed, 4 Feb 2026 14:17:38 -0500 Subject: [PATCH 1/5] Add carriage_positions.txt specification Defines optimal carriage positioning for transfers and platform exits. Enables trip planners to recommend which carriage to board for minimal walking time at destinations. Fields: - from_stop_id: boarding platform - to_stop_id: destination stop/facility - recommended_carriage: 1-indexed from front - carriage_count: total positions (can be logical) - front_car_position: left/right platform side - facility_type: elevator/escalator/stairs (optional) Placed after pathways.txt as it complements station navigation. --- gtfs/spec/en/reference.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/gtfs/spec/en/reference.md b/gtfs/spec/en/reference.md index b4569a54..c2ed7031 100644 --- a/gtfs/spec/en/reference.md +++ b/gtfs/spec/en/reference.md @@ -35,6 +35,7 @@ This document defines the format and structure of the files that comprise a GTFS - [frequencies.txt](#frequenciestxt) - [transfers.txt](#transferstxt) - [pathways.txt](#pathwaystxt) + - [carriage_positions.txt](#carriage_positionstxt) - [levels.txt](#levelstxt) - [location_groups.txt](#location_groupstxt) - [location_group_stops.txt](#location_group_stopstxt) @@ -139,6 +140,7 @@ This specification defines the following files: | [frequencies.txt](#frequenciestxt) | Optional | Headway (time between trips) for headway-based service or a compressed representation of fixed-schedule service. | | [transfers.txt](#transferstxt) | Optional | Rules for making connections at transfer points between routes. | | [pathways.txt](#pathwaystxt) | Optional | Pathways linking together locations within stations. | +| [carriage_positions.txt](#carriage_positionstxt) | Optional | Optimal carriage positioning for transfers and platform exits. | | [levels.txt](#levelstxt) | **Conditionally Required** | Levels within stations.

Conditionally Required:
- **Required** when describing pathways with elevators (`pathway_mode=5`).
- Optional otherwise. | | [location_groups.txt](#location_groupstxt) | Optional | A group of stops that together indicate locations where a rider may request pickup or drop off. | | [location_group_stops.txt](#location_group_stopstxt) | Optional | Rules to assign stops to location groups. | @@ -747,6 +749,27 @@ Pathways are intended to exhaustively define the internal access graph of a stat | `signposted_as` | Text | Optional | Public facing text from physical signage that is visible to riders.

May be used to provide text directions to riders, such as 'follow signs to '. The text in `singposted_as` should appear exactly how it is printed on the signs.

When the physical signage is multilingual, this field may be populated and translated following the example of `stops.stop_name` in the field definition of `feed_info.feed_lang`.| | `reversed_signposted_as` | Text | Optional | Same as `signposted_as`, but when the pathway is used from the `to_stop_id` to the `from_stop_id`.| +### carriage_positions.txt + +File: **Optional** + +Primary key (`from_stop_id`, `to_stop_id`, `facility_type`) + +Defines optimal carriage positioning for transfers and platform exit access. Enables trip planners to recommend which carriage passengers should board to minimize walking time at their destination. + +While [pathways.txt](#pathwaystxt) handles navigation within stations, it does not address where to stand on the platform before boarding. This file complements pathways by providing carriage-level boarding recommendations. + +Producers MAY use logical carriage divisions when exact carriage positions are unavailable. For example, `carriage_count=3` with `recommended_carriage=1` indicates "board near the front" regardless of actual vehicle length. + +| Field Name | Type | Presence | Description | +| ------ | ------ | ------ | ------ | +| `from_stop_id` | Foreign ID referencing `stops.stop_id` | **Required** | Identifies the platform where the passenger boards. Must reference a stop with `location_type=0`. | +| `to_stop_id` | Foreign ID referencing `stops.stop_id` | **Required** | Identifies the destination: a transfer platform, station entrance, or exit. Must reference a stop with `location_type=0` or `location_type=2`. | +| `recommended_carriage` | Non-negative integer | **Required** | The recommended carriage to board, 1-indexed from the front of the vehicle. May represent a logical position rather than exact carriage number. Must be less than or equal to `carriage_count`. | +| `carriage_count` | Non-negative integer | **Required** | Number of carriage positions in this configuration. May represent logical divisions (e.g., 3 for front/middle/back) rather than actual carriage count. | +| `front_car_position` | Enum | **Required** | Platform side where the front carriage (carriage 1) stops, from the perspective of a passenger facing the track. Valid options are:

`left` - Front carriage stops on the left side of the platform.
`right` - Front carriage stops on the right side of the platform. | +| `facility_type` | Enum | Optional | Type of facility at the destination. Valid options are:

`elevator` - Elevator access.
`escalator` - Escalator access.
`stairs` - Stair access.

May be empty if the destination is another platform or general exit. | + ### levels.txt File: **Conditionally Required** From 7331df24e4e02c6a3cf73c7c3589dc2f065ed2fb Mon Sep 17 00:00:00 2001 From: Guillaume Campagna Date: Thu, 5 Feb 2026 09:55:15 -0500 Subject: [PATCH 2/5] Clarify field descriptions for front_car_position and facility_type Address PR review feedback by specifying stop_id references. Co-Authored-By: Claude Opus 4.5 --- gtfs/spec/en/reference.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/gtfs/spec/en/reference.md b/gtfs/spec/en/reference.md index c2ed7031..daf6a9c3 100644 --- a/gtfs/spec/en/reference.md +++ b/gtfs/spec/en/reference.md @@ -767,8 +767,8 @@ Producers MAY use logical carriage divisions when exact carriage positions are u | `to_stop_id` | Foreign ID referencing `stops.stop_id` | **Required** | Identifies the destination: a transfer platform, station entrance, or exit. Must reference a stop with `location_type=0` or `location_type=2`. | | `recommended_carriage` | Non-negative integer | **Required** | The recommended carriage to board, 1-indexed from the front of the vehicle. May represent a logical position rather than exact carriage number. Must be less than or equal to `carriage_count`. | | `carriage_count` | Non-negative integer | **Required** | Number of carriage positions in this configuration. May represent logical divisions (e.g., 3 for front/middle/back) rather than actual carriage count. | -| `front_car_position` | Enum | **Required** | Platform side where the front carriage (carriage 1) stops, from the perspective of a passenger facing the track. Valid options are:

`left` - Front carriage stops on the left side of the platform.
`right` - Front carriage stops on the right side of the platform. | -| `facility_type` | Enum | Optional | Type of facility at the destination. Valid options are:

`elevator` - Elevator access.
`escalator` - Escalator access.
`stairs` - Stair access.

May be empty if the destination is another platform or general exit. | +| `front_car_position` | Enum | **Required** | Platform side where the front carriage (carriage 1) stops at `from_stop_id`, from the perspective of a passenger facing the track. Valid options are:

`left` - Front carriage stops on the left side of the platform.
`right` - Front carriage stops on the right side of the platform. | +| `facility_type` | Enum | Optional | Type of facility available close to the recommended carriage at with destination `to_stop_id`. Valid options are:

`elevator` - Elevator access.
`escalator` - Escalator access.
`stairs` - Stair access.

May be empty if the destination is another platform or general exit. | ### levels.txt From 300bc51d29bf29e7d0de31a0698cbfdfc2fce51f Mon Sep 17 00:00:00 2001 From: Guillaume Campagna Date: Thu, 5 Feb 2026 10:09:22 -0500 Subject: [PATCH 3/5] Update --- gtfs/spec/en/reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gtfs/spec/en/reference.md b/gtfs/spec/en/reference.md index daf6a9c3..f70595f7 100644 --- a/gtfs/spec/en/reference.md +++ b/gtfs/spec/en/reference.md @@ -768,7 +768,7 @@ Producers MAY use logical carriage divisions when exact carriage positions are u | `recommended_carriage` | Non-negative integer | **Required** | The recommended carriage to board, 1-indexed from the front of the vehicle. May represent a logical position rather than exact carriage number. Must be less than or equal to `carriage_count`. | | `carriage_count` | Non-negative integer | **Required** | Number of carriage positions in this configuration. May represent logical divisions (e.g., 3 for front/middle/back) rather than actual carriage count. | | `front_car_position` | Enum | **Required** | Platform side where the front carriage (carriage 1) stops at `from_stop_id`, from the perspective of a passenger facing the track. Valid options are:

`left` - Front carriage stops on the left side of the platform.
`right` - Front carriage stops on the right side of the platform. | -| `facility_type` | Enum | Optional | Type of facility available close to the recommended carriage at with destination `to_stop_id`. Valid options are:

`elevator` - Elevator access.
`escalator` - Escalator access.
`stairs` - Stair access.

May be empty if the destination is another platform or general exit. | +| `facility_type` | Enum | Optional | Type of facility available close to the recommended carriage with destination `to_stop_id`. Valid options are:

`elevator` - Elevator access.
`escalator` - Escalator access.
`stairs` - Stair access.

May be empty if the destination is another platform or general exit. | ### levels.txt From 115cf4f50c4ec0d4ffca03bb95ab2289870a239d Mon Sep 17 00:00:00 2001 From: Guillaume Campagna Date: Mon, 23 Feb 2026 13:23:38 -0500 Subject: [PATCH 4/5] Update after discussions --- gtfs/spec/en/reference.md | 28 +++++++++++++++++++++------- 1 file changed, 21 insertions(+), 7 deletions(-) diff --git a/gtfs/spec/en/reference.md b/gtfs/spec/en/reference.md index f70595f7..406421bf 100644 --- a/gtfs/spec/en/reference.md +++ b/gtfs/spec/en/reference.md @@ -35,6 +35,7 @@ This document defines the format and structure of the files that comprise a GTFS - [frequencies.txt](#frequenciestxt) - [transfers.txt](#transferstxt) - [pathways.txt](#pathwaystxt) + - [station_directions.txt](#station_directionstxt) - [carriage_positions.txt](#carriage_positionstxt) - [levels.txt](#levelstxt) - [location_groups.txt](#location_groupstxt) @@ -140,6 +141,7 @@ This specification defines the following files: | [frequencies.txt](#frequenciestxt) | Optional | Headway (time between trips) for headway-based service or a compressed representation of fixed-schedule service. | | [transfers.txt](#transferstxt) | Optional | Rules for making connections at transfer points between routes. | | [pathways.txt](#pathwaystxt) | Optional | Pathways linking together locations within stations. | +| [station_directions.txt](#station_directionstxt) | Optional | Platform direction of the front carriage at each stop. | | [carriage_positions.txt](#carriage_positionstxt) | Optional | Optimal carriage positioning for transfers and platform exits. | | [levels.txt](#levelstxt) | **Conditionally Required** | Levels within stations.

Conditionally Required:
- **Required** when describing pathways with elevators (`pathway_mode=5`).
- Optional otherwise. | | [location_groups.txt](#location_groupstxt) | Optional | A group of stops that together indicate locations where a rider may request pickup or drop off. | @@ -749,11 +751,24 @@ Pathways are intended to exhaustively define the internal access graph of a stat | `signposted_as` | Text | Optional | Public facing text from physical signage that is visible to riders.

May be used to provide text directions to riders, such as 'follow signs to '. The text in `singposted_as` should appear exactly how it is printed on the signs.

When the physical signage is multilingual, this field may be populated and translated following the example of `stops.stop_name` in the field definition of `feed_info.feed_lang`.| | `reversed_signposted_as` | Text | Optional | Same as `signposted_as`, but when the pathway is used from the `to_stop_id` to the `from_stop_id`.| +### station_directions.txt + +File: **Optional** + +Primary key (`stop_id`) + +Defines which side of the platform the front carriage stops at. This information is used alongside [carriage_positions.txt](#carriage_positionstxt) to determine boarding recommendations. When the departure and arrival stations have different front car directions, trip planners can mirror the recommended carriage accordingly. + +| Field Name | Type | Presence | Description | +| ------ | ------ | ------ | ------ | +| `stop_id` | Foreign ID referencing `stops.stop_id` | **Required** | Identifies the platform. Must reference a stop with `location_type=0`. | +| `front_car_position` | Enum | **Required** | Platform side where the front carriage (carriage 1) stops, from the perspective of a passenger facing the track. Valid options are:

`left` - Front carriage stops on the left side of the platform.
`right` - Front carriage stops on the right side of the platform. | + ### carriage_positions.txt File: **Optional** -Primary key (`from_stop_id`, `to_stop_id`, `facility_type`) +Primary key (`stop_id`, `to_stop_id`, `facility_type`) Defines optimal carriage positioning for transfers and platform exit access. Enables trip planners to recommend which carriage passengers should board to minimize walking time at their destination. @@ -763,12 +778,11 @@ Producers MAY use logical carriage divisions when exact carriage positions are u | Field Name | Type | Presence | Description | | ------ | ------ | ------ | ------ | -| `from_stop_id` | Foreign ID referencing `stops.stop_id` | **Required** | Identifies the platform where the passenger boards. Must reference a stop with `location_type=0`. | -| `to_stop_id` | Foreign ID referencing `stops.stop_id` | **Required** | Identifies the destination: a transfer platform, station entrance, or exit. Must reference a stop with `location_type=0` or `location_type=2`. | -| `recommended_carriage` | Non-negative integer | **Required** | The recommended carriage to board, 1-indexed from the front of the vehicle. May represent a logical position rather than exact carriage number. Must be less than or equal to `carriage_count`. | -| `carriage_count` | Non-negative integer | **Required** | Number of carriage positions in this configuration. May represent logical divisions (e.g., 3 for front/middle/back) rather than actual carriage count. | -| `front_car_position` | Enum | **Required** | Platform side where the front carriage (carriage 1) stops at `from_stop_id`, from the perspective of a passenger facing the track. Valid options are:

`left` - Front carriage stops on the left side of the platform.
`right` - Front carriage stops on the right side of the platform. | -| `facility_type` | Enum | Optional | Type of facility available close to the recommended carriage with destination `to_stop_id`. Valid options are:

`elevator` - Elevator access.
`escalator` - Escalator access.
`stairs` - Stair access.

May be empty if the destination is another platform or general exit. | +| `stop_id` | Foreign ID referencing `stops.stop_id` | **Required** | Identifies the arrival platform. Must reference a stop with `location_type=0`. | +| `to_stop_id` | Foreign ID referencing `stops.stop_id` | Optional | Identifies a specific destination: a transfer platform, station entrance, or exit. Must reference a stop with `location_type=0` or `location_type=2`. When empty, the recommendation applies as a general default for the station. When provided, it gives a destination-specific recommendation that takes priority over the general default. | +| `recommended_carriage` | Positive integer | **Required** | The recommended carriage to board, 1-indexed from the front of the vehicle. May represent a logical position rather than exact carriage number. Must be less than or equal to `carriage_count`. | +| `carriage_count` | Positive integer | **Required** | Number of carriage positions in this configuration. May represent logical divisions (e.g., 3 for front/middle/back) rather than actual carriage count. | +| `facility_type` | Enum | Optional | Type of facility available close to the recommended carriage. Valid options are:

`elevator` - Elevator access.
`escalator` - Escalator access.
`stairs` - Stair access.

May be empty if the destination is another platform or general exit. | ### levels.txt From c334a5a799aaf64083a159326f04f849b6f2c0e3 Mon Sep 17 00:00:00 2001 From: Guillaume Campagna Date: Mon, 23 Feb 2026 15:29:04 -0500 Subject: [PATCH 5/5] Update spec --- gtfs/spec/en/reference.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/gtfs/spec/en/reference.md b/gtfs/spec/en/reference.md index 406421bf..988cab0c 100644 --- a/gtfs/spec/en/reference.md +++ b/gtfs/spec/en/reference.md @@ -762,7 +762,7 @@ Defines which side of the platform the front carriage stops at. This information | Field Name | Type | Presence | Description | | ------ | ------ | ------ | ------ | | `stop_id` | Foreign ID referencing `stops.stop_id` | **Required** | Identifies the platform. Must reference a stop with `location_type=0`. | -| `front_car_position` | Enum | **Required** | Platform side where the front carriage (carriage 1) stops, from the perspective of a passenger facing the track. Valid options are:

`left` - Front carriage stops on the left side of the platform.
`right` - Front carriage stops on the right side of the platform. | +| `front_car_position` | Enum | **Required** | Platform side where the front carriage (carriage 0) stops, from the perspective of a passenger facing the track. Valid options are:

`left` - Front carriage stops on the left side of the platform.
`right` - Front carriage stops on the right side of the platform. | ### carriage_positions.txt @@ -774,13 +774,13 @@ Defines optimal carriage positioning for transfers and platform exit access. Ena While [pathways.txt](#pathwaystxt) handles navigation within stations, it does not address where to stand on the platform before boarding. This file complements pathways by providing carriage-level boarding recommendations. -Producers MAY use logical carriage divisions when exact carriage positions are unavailable. For example, `carriage_count=3` with `recommended_carriage=1` indicates "board near the front" regardless of actual vehicle length. +Producers MAY use logical carriage divisions when exact carriage positions are unavailable. For example, `carriage_count=3` with `recommended_carriage=0` indicates "board near the front" regardless of actual vehicle length. | Field Name | Type | Presence | Description | | ------ | ------ | ------ | ------ | | `stop_id` | Foreign ID referencing `stops.stop_id` | **Required** | Identifies the arrival platform. Must reference a stop with `location_type=0`. | | `to_stop_id` | Foreign ID referencing `stops.stop_id` | Optional | Identifies a specific destination: a transfer platform, station entrance, or exit. Must reference a stop with `location_type=0` or `location_type=2`. When empty, the recommendation applies as a general default for the station. When provided, it gives a destination-specific recommendation that takes priority over the general default. | -| `recommended_carriage` | Positive integer | **Required** | The recommended carriage to board, 1-indexed from the front of the vehicle. May represent a logical position rather than exact carriage number. Must be less than or equal to `carriage_count`. | +| `recommended_carriage` | Non-negative integer | **Required** | The recommended carriage to board, 0-indexed from the front of the vehicle. May represent a logical position rather than exact carriage number. Must be less than `carriage_count`. | | `carriage_count` | Positive integer | **Required** | Number of carriage positions in this configuration. May represent logical divisions (e.g., 3 for front/middle/back) rather than actual carriage count. | | `facility_type` | Enum | Optional | Type of facility available close to the recommended carriage. Valid options are:

`elevator` - Elevator access.
`escalator` - Escalator access.
`stairs` - Stair access.

May be empty if the destination is another platform or general exit. |