Addition of vehicles.txt to GTFS schedule

[doconnoronca]

Summary

Adds new file vehicles.txt to describe the capacity, accessibility, appearance and features of individual vehicles or vehicle ranges.

Describe the Problem

Based on issue 458. When combined with the vehicle label in GTFS real-time or other real-time APIs, this allows consumers to provide a variety of information about the approaching vehicle to riders.

Use Cases

• Inform riders about the type of vehicle approaching and if it is the same as the scheduled type of vehicle, such as when streetcars are replaced by buses.
• Inform riders of the size, color and appearance of the approaching vehicle.
• Inform consumers about the capacity of vehicles so that a better passenger load estimate can be calculated.
• Allow analysts to calculate the actual capacity of a route based on vehicle capacity.
• Inform riders of the availability of features including bike storage, luggage space, restrooms, changing points, WiFi.
• Provide disabled riders of the accessibility features of the approaching vehicles and how the use them.

Proposed Solution

The addition of a new table called vehicles.txt that describes the vehicles of a transit agency. Also, the addition of vehicle_class columns to routes.txt and trips.txt which allows routes and trips to include the vehicles that typically operate for that route or trips and allow vehicles.txt information to be used if real-time data isn't available.

Type of change

GTFS Schedule

• Functional Change
• Non-Functional Change
• Documentation Maintenance

Additional Information

There is currently a vehicles file in TIDES as well as TODS. This proposal expands on TODS with additional details that are useful for riders.

The Proposal: Add cyclist position availability fields to VehiclePosition and CarriageDetails includes a total_cyclist_positions value, which wouldn't be needed if the data was available from vehicles.txt.

Some of the examples for the use of Proposal: Additional (Trip) Notices could be handled by vehicles.txt including the availability of WiFi, food and bicycle storage.

I have created a Google Sheet with vehicles data for Toronto TTC, Los Angeles Metro, New York Metro North rail and Toronto GO Train. These can be downloaded as Comma Separated Values to generate a vehicles.txt file. These have been loaded into TransSee.

Some transit enthusiasts who use TransSee have contributed files as well. Transit enthusiasts could crowd source data in places where transit agencies don't generate it on their own. There could be TODS like extensions to this structure that would include data that is important to them.

BusTimes.org provides some of the same information for bus fleets in the UK.

Proposed Discussion Period

As a large proposal, I suggest at least three months of discussion.

Testing Details

• Consumer(s): TransSee
• Producer(s): TransSee has produced some vehicles.txt file based on public data and some transit enthusiasts have contributed some. I would like to see a transit agencies start generating the file.
• Estimated Testing Period: At least three months.

Proposal Update Tracker

Date	Update Description
2026-05-10	Create PR draft

Checklist

• I have read and understood the GTFS Change process.
• I have read and understood the GTFS Guiding Principles.
• I understand the Role of Advocate and the Responsibilities attached to it.
• I have signed the Contributor License Agreement (CLA).
• I have ensured that this proposal is not covered by an existing Pull Request.

[skinkie]

You are actually introducing Transmodel like functionality with newly invented terms. My suggestion would be to fully align the attribute names with NeTEx.

[kona314]

• TODS defines a vehicles.txt with much more limited information. This would be a breaking conflict for producers attempting to provide both.
  • To resolve this, I'd suggest moving the bulk of the attributes in this file to a vehicle_groups.txt file (or other similar name), then define vehicles.txt as identical to TODS, but with an extra vehicle_group_id column referencing an ID in vehicle_groups.txt.
    • This would also handle the concerns in the next two bullets.
• If the corresponding RT field is label, should vehicle_id be called vehicle_label instead? Same for vehicle_id_high, which would be vehicle_label_high.
• Some agencies have letter prefixes/suffixes on their coaches, e.g. B0747 or 1312E. How would this work with defining ranges?
  • Are there libraries to expand e.g. B0741-B0749 and 1301E-1325E into 9 and 25 labels respectively? This is just not a problem I'm familiar with.
• agency_id should be added and part of the primary key, with the same semantics as routes.agency_id, for handling feeds with multiple agencies.
  • If moving to vehicle_groups.txt, I don't think it would need to be part of the PK, since the group ID column would handle that.
• Should cab be explicitly forbidden for non-rail vehicles?
• To me, "standing capacity" is subtly different from "fully loaded capacity," as agencies often differentiate between comfortable standing room and crush loading. Should the description for capacity_standing draw a clearer line here?
  • I think my preference would be to rename to capacity_full and have the description explicitly tie this to the RT OccupancyStatus.FULL value and definition, which it feels like it's already alluding to.
• Why are AC/USB-A/USB-C plugs defined the way they are? I think it's confusing to have 1 mean an unknown number, but all other numbers mean there are that many. What if there's one plug? (Most likely on small vehicles, e.g. vans or gondolas.)
  • Can -1 be used for an unknown quantity? This is more intuitive to me since you can't have negative plugs.
    • Bikes, wheelchairs, strollers, restrooms/accessible restrooms (maybe?), could also benefit from -1 as unknown quantity.
• vehicle_type and fuel_type both reference US FTA values. I believe there's been a historic intent in GTFS to avoid endorsing any specific country's systems, which I would agree with.
  • I don't have an alternative proposal here. There are of course the GTFS route types, which are more limited, especially when not counting the extended route types.
• I like the inclusion of vehicle_class. This almost invites a vehicle_classes.txt, which could define rider-facing values for this info like a name? This would also help the above with overcoming shortcomings of the GTFS route types (e.g. double-decker buses would still be vehicle_route_type = 3, but with a vehicle_class_name = "Double-decker").
• Buses at my agency announce the route automatically only when the stop is served by multiple routes, otherwise no. Would this be value 2 of route_announcements?
• Nitpicky naming consistency items:
  • capacity_bike and car_capacity having the word "capacity" switched seems unnecessary.
  • strollers should be capacity_strollers.
  • Some capacity items are plural (strollers) and others are not (bike, car).
  • bicycle_notes should be bike_notes for consistency with capacity_bike and trips.bikes_allowed.

[doconnoronca]

You are actually introducing Transmodel like functionality with newly invented terms. My suggestion would be to fully align the attribute names with NeTEx.

Based on the NeTEx standard these are the relevant fields.

• SelfPropelled: Covered by fuel_type
• TypeOfFuel: Same as fuel_type, but uses a different format. Also GTFS uses underscores between words.
• EuroClass: Seems to be specific model of bus.
• LowFloor: Covered by boarding_steps,
• HasLiftOrRamp: Covered by accessible_boarding enum with more detail,
• HasHoist: Also covered by accessible_boarding,
• Length: Matches.
• Width, Height, Weight: Not included, but could be added if there is interest.

[doconnoronca]

• TODS defines a vehicles.txt with much more limited information. This would be a breaking conflict for producers attempting to provide both.

  * To resolve this, I'd suggest moving the bulk of the attributes in this file to a `vehicle_groups.txt` file (or other similar name), then define `vehicles.txt` as identical to TODS, but with an extra `vehicle_group_id` column referencing an ID in `vehicle_groups.txt`.
    
    * This would also handle the concerns in the next two bullets.
  

Yes, I can see the benefit from creating two tables, one based on the TODS vehicles.txt plus a vehicle_group_id and year_manufactured and moving most of the other columns into a vehicle_groups.txt file. However creating two tables makes the structure somewhat more complex.

I could just update vehicles.txt with all the columns to follow TODS instead of TIDES.

* If the corresponding RT field is `label`, should `vehicle_id` be called `vehicle_label` instead? Same for `vehicle_id_high`, which would be `vehicle_label_high`.

* Some agencies have letter prefixes/suffixes on their coaches, e.g. B0747 or 1312E. How would this work with defining ranges?
  
  * Are there libraries to expand e.g. B0741-B0749 and 1301E-1325E into 9 and 25 labels respectively? This is just not a problem I'm familiar with.

In TransSee, for an individual vehicle, it finds the record where the vehicle's label is between the low and high range, so a library to expand the values isn't really needed.

* `agency_id` should be added and part of the primary key, with the same semantics as `routes.agency_id`, for handling feeds with multiple agencies.

This would help for some places with overlapping fleet numbers.

* Should `cab` be explicitly forbidden for non-rail vehicles?

The Niagara Falls People Mover used to have unpowered bus trailers with no cabs.

* To me, "standing capacity" is subtly different from "fully loaded capacity," as agencies often differentiate between comfortable standing room and crush loading. Should the description for `capacity_standing` draw a clearer line here?
  
  * I think my preference would be to rename to `capacity_full` and have the description explicitly tie this to the RT `OccupancyStatus.FULL` value and definition, which it feels like it's already alluding to.

That would probably be better.

* Why are AC/USB-A/USB-C plugs defined the way they are? I think it's confusing to have `1` mean an unknown number, but all other numbers mean there are that many. What if there's one plug? (Most likely on small vehicles, e.g. vans or gondolas.)
  
  * Can `-1` be used for an unknown quantity? This is more intuitive to me since you can't have negative plugs.

    * Bikes, wheelchairs, strollers, restrooms/accessible restrooms (maybe?),  could also benefit from `-1` as unknown quantity.

It's worth considering. Looks like transfer_count uses -1 for unlimited transfers.

* `vehicle_type` and `fuel_type` both reference US FTA values. I believe there's been a historic intent in GTFS to avoid endorsing any specific country's systems, which I would agree with.
  
  * I don't have an alternative proposal here. There are of course the GTFS route types, which are more limited, especially when not counting the extended route types.

* I like the inclusion of `vehicle_class`. This almost invites a `vehicle_classes.txt`, which could define rider-facing values for this info like a name? This would also help the above with overcoming shortcomings of the GTFS route types (e.g. double-decker buses would still be `vehicle_route_type = 3`, but with a `vehicle_class_name = "Double-decker"`).

I think that vehicle_group would be more specific than vehicle_class. A route could be in the double-decker class but have a few different models with different features from different vehicle_groups.

* Buses at my agency announce the route automatically only when the stop is served by multiple routes, otherwise no. Would this be value `2` of `route_announcements`?

Interesting feature.

* Nitpicky naming consistency items:
  
  * `capacity_bike` and `car_capacity` having the word "capacity" switched seems unnecessary.
  * `strollers` should be `capacity_strollers`.
  * Some capacity items are plural (strollers) and others are not (bike, car).
  * `bicycle_notes` should be `bike_notes` for consistency with `capacity_bike` and `trips.bikes_allowed`.

Good suggestions.

[kona314]

Yes, I can see the benefit from creating two tables, one based on the TODS vehicles.txt plus a vehicle_group_id and year_manufactured and moving most of the other columns into a vehicle_groups.txt file. However creating two tables makes the structure somewhat more complex.

I could just update vehicles.txt with all the columns to follow TODS instead of TIDES.

To follow TODS would eliminate the ability to define things with high/low ranges, which to me would be massively more complex than having a separate table since producers have to duplicate this data across a ton of individual vehicles. In my experience, operators already understand this concept and would have no problem mimicking it.

In TransSee, for an individual vehicle, it finds the record where the vehicle's label is between the low and high range, so a library to expand the values isn't really needed.

Pantograph does this currently but is moving away from it, instead defining every single vehicle ID. I think it's also a pretty basic expectation that a consumer could determine all the vehicles an agency has based on this file.

This would help for some places with overlapping fleet numbers.

There are also cases where this would be useful to riders. In Puget Sound, bus routes from Sound Transit are operated by one of the three county partners, and ST routes appear in those agencies' GTFS feeds. The agencies usually operate ST service with ST buses and their own service with their own buses, but this does get mixed up from time to time. Similar to the above, I think it's also a reasonable expectation that a consumer could know who owns a vehicle in this file. The semantics should work just like routes.agency_id, so it would only be required if there's more than one agency in the feed.

The Niagara Falls People Mover used to have unpowered bus trailers with no cabs.

The description for this field is ambiguous as written and implies it's only for rail vehicles. If the intent is to cover all vehicles then it should be updated accordingly.

I think that vehicle_group would be more specific than vehicle_class. A route could be in the double-decker class but have a few different models with different features from different vehicle_groups.

I agree. My agency has route_type = 3 for everything since we operate bus service. We have a few different classes of buses—30s, 40s, artics, BRT artics, double deckers—which map directly to scheduled vehicle type assignments. Then groups would be used to define specific models and series.

Interesting feature.

The ADA requires this at stops served by multiple routes, so our system is configured to do it only at those stops. I'm sure other agencies have similar functions. (I do not know why one wouldn't just always announce the route, but this is the reality of the situation at the moment.) Point being, route_announcements as-is seems to imply all or nothing. Separately, I wonder if there are cases where some stations announce the route within the station but others depend on the vehicle exterior announcements. All of this also seems to be wandering into the category of stop amenities rather than vehicle amenities. I think this field might need some additional work and would be interested in feedback from those more familiar with this topic.

[doconnoronca]

I have updated the fields to match TODS field names.

The question is should this data be split into two tables, vehicles.txt with the vehicle_label, vehicle_label, license_plate from TODS as well as year_manufactured, nick_name, decoration from my proposal and a vehicle_group field which links to the vehicle_group.txt table with the rest of the columns.

There would still be a vehicle_class column in the vehicle_group.txt table to link to the routes and trips, and would be less specific that the vehicle_group. The vehicle_group would generally be a series of vehicles bought in the same order, while the vehicle_class would be type of vehicle, like articulated buses.

Is it better to split the data into table tables and making the structure somewhat more complex or to keep it in one table with a vehicle_label_high column for ranges, but to be TODOs compatible they wouldn't be able to use the vehicle_label_high column?

[Brickblock1]

Is it better to split the data into table tables and making the structure somewhat more complex or to keep it in one table with a vehicle_label_high column for ranges, but to be TODOs compatible they wouldn't be able to use the vehicle_label_high column?

I don't see using the vehicle label as the primary key working. In Stockholm for example there are multiple buses with the same label used by different operators which all run under the same agency. This can not be solved without using unique vehicle_ids.