📄🚀 – Modify handling of vehicle attributes and vehicles consists

[jlstpaul]

Describe the feature you want and how it meets your needs or solves a problem
This issue proposes to change the approach to how vehicle attributes and vehicle consists are represented in TIDES.

The current spec has the following issues

• Vehicle attribute data is denormalized, so that fields such as capacity information, are repeated for all of the vehicles of the same type (e.g., a series of buses purchased together)
• Vehicle attribute information is defined in both the vehicles table and the train_cars table. This means that both tables need to be modified when there is field change, and two different tables must be populated from agency fleet data
• There is no way to indicate the direction that a consist is traveling in the operational data tables.

Describe the solution you'd like

The proposed changes are as follows

• Create a new vehicle_groups table that details the shared attributes of all vehicles in agency-defined groups. A vehicle_group is a subset in which all vehicles share the same attribute values. A vehicle_group may refer to either individuals vehicles, e.g., specific type of bus, or to a planned consist type, e.g.,“Two car train of Type II vehicles”. See the list of proposed vehicle_group attributes below.

• Modify the the vehicles table

  • Remove attributes related to capacity, amenities, etc. (These are shifted to vehicle_groups table
  • Add a vehicle_label field which is the public identifier of the vehicle if there is one.
  • Add a vehicle_group_id reference to a record in the vehicle_groups table
  • Add is_train_consist boolean field. When true, the vehicle record represents a consist and there should be one or more records for this vehicle_id in the vehicle_train_cars table. Note: This field is not strictly necessary. Open to discussion on whether it is needed.

• Remove the train_cars table. Individual train cars should be represented in the vehicles table.

• Modify the descriptions of fields in vehicle_train_cars table to clarify their use

  • vehicle_id is the identifier for the consist. It references a record in the vehicles table
  • train_car_id is the identifier of an individual train car within the consist. It also references a record in the vehicles table

• Add a train_car_orientation to the vehicle_train_cars table to indicate which way the car is facing the consist.

• Modify the following tables to add a vehicle_direction field associated with the existing vehicle_id field. If vehicle_direction is forward, then the lowest numbered train car is in the front.
  Vehicle_locations
Passenger_events
Fare_transactions
Stops_visited
Trips_performed

Describe alternatives you've considered

This issue grew out of several related proposals and discussions

• GTFS vehicles.txt proposal: Addition of vehicles.txt to GTFS schedule google/transit#636
• Discussion document: Vehicles and Crew in GTFS / TODS / TIDES

The initial list of potential fields for the proposed vehicle_groups table is taken from the GTFS vehicles.txt proposal:

vehicle_group_id
vehicle_group_description
vehicle_class (text field)
vehicle_label
vehicle_label_high
agency_id
facility_name
vehicle_type
manufacturer
model_name
year_manufactured
fuel_type
length
articulated_sections
levels
cab
image_url
image_photographer
image_details
vehicle_notes
capacity_seated
capacity_full
capacity_wheelchairs
capacity_strollers
capacity_bikes
bike_notes
capacity_cars
luggage
luggage_notes
restrooms
accessible_restrooms
air_conditioning
ac_plugs
usba_plugs
usbc_plugs
wifi
wifi_notes
doors
boarding_type
boarding_steps
accessible_boarding
accessibility_note
stop_announcements
route_announcements
stop_displays
livery_color
livery
nickname
decoration

[jlstpaul]

An alternative approach to managing consists would be as follows

• a fleet vehicles table with one record for every physical vehicle
• a vehicle_assignments table with information on the assignment of both individual vehicles and vehicle consists to service operated. This table would at minimum have a record for every block for every day with the vehicle(s) assigned to the block.

The fleet vehicles table would be a slowly changing, with revisions only occurring when the vehicle assets change.

All vehicle assignments and consist information would be in a single vehicle_assignments table

There are three sub-options for how consists would be represented in the vehicle_assignments table:

• Option 1: multiple vehicle_assignments records, one for each car in the consist
• Option 2: a single vehicle_assignments record with a field that combines information on the vehicles in the consist (e.g., concatenated car ids)
• Option 3: a single vehicle_assignments record with a new separate table to document the individual cars within the consist.

Under Option 1, the vehicle_assigments table would have the following fields

• assigned_vehicle_id - unique id for the bus or consist assigned to the work
• vehicle_group_id - the group id for the bus or consist
• vehicle_start - timestamp when the bus or consist starts operation
• vehicle_end- timestamp when the bus or consist ends operation
• fleet_vehicle_id - the fleet_vehicle_id of the bus or of the train car in a consist
• train_car_order - if this is a consist, the order of the car in the consist
• train_car_orientation - if this is a consist, the direction of the car in the consist
• operator_id

There was significant discussion of this alternative at the 6/11/26 TIDES Contributors meeting and it is now documented as Option 2 in the Discussion document: Vehicles and Crew in GTFS / TODS / TIDES

[lauriemerrell]

A couple other notes from today's TIDES Contributors conversation that stood out to me:

• Seems like we need to refine language (table and field names), and we didn't really reach strong consensus:

  • There was some agreement that "vehicles" should possibly be reserved for what @botanize called "logical vehicles" (vehicles as experienced by passengers -- "things that run trips") as opposed to "physical vehicles" (literal train cars) -- one consideration here is alignment with GTFS-RT which has vehicle_id fields that refer to the logical / passenger-facing vehicle
  • There was concern that "fleet" refers specifically to a group or class of vehicles (so might not be a good name for the table of physical vehicles)
  • There was also some ambiguity about "vehicle groups" that I didn't fully catch

• The critical point (to me) about Option 2 is that it captures the conceptual difference between a consist and a train car or bus vehicle, which is that physical vehicles are pretty persistent whereas consists basically only exist in the context of the work they perform and change relatively quite rapidly, and having those two concepts in the same table feels problematic (i.e., the issue with combining them in a single vehicles table is not that consists have sub-entities, which is fine, but that consists change frequently and are basically ephemeral in the context of work assignments and don't really have stable traits of their own)

[chrisyamas]

flagging for the issues working group: this is on the agenda for a one-hour work session on wednesday, july 1 at 12pm eastern. the group expects to work through the approach and, if there's consensus, draft the pr text during the session; follow-up may be needed to finalize. tagging to the v2.0 milestone for tracking, though whether it lands in v2.0 depends on the working group reaching consensus in time for the release.

[jlstpaul]

The latest version of the proposal (expounded here) is as follows:

• Add vehicle_groups table to TIDES with attributes for each unique set of vehicles. This might also be in GTFS and/or TODS.
• Add fleet_vehicles table to TIDES with the list of physical vehicles (buses, train cars)
  • fleet_vehicle_id - static ID for each vehicle
  • vehicle_group_id - reference to the attributes for the vehicle (from its group)
  • vehicle_label - public/agency identifier on the vehicle
  • vehicle_license_plate
  • vehicle_start - when the vehicle entered service
  • vehicle_end - when the vehicle left service
• Add vehicle_assignments table to TIDES with the vehicles assigned for a given time period, including consist information
  • assigned_vehicle_id - unique identifier for each date a fleet vehicle is assigned, or for a consist (but could also be te same as fleet_vehicle_id for a bus or single unit
  • vehicle_group_id- for single unit, same as fleet_vehicles.vehicle_group_id
  • assignment_start - date/time vehicle assigment starts, or when consist is formed
  • assignment_end
  • fleet_vehicle_id
  • train_car_order - for consists
  • train_car_orientation - for consists
  • operator_id
• Add vehicle_direction to the following tables to contain the direction that train consists are moving
  • vehicle_locations
  • passenger_events
  • fare_transactions
  • stops_visited
  • trips_performed
• Remove train_cars and vehicle_train_cars tables

[lauriemerrell]

Follow up from conversation today: I think one remaining question I have is whether any joins to vehicle_assignments have to be date-aware? If we go the direction of listing train cars and consists both together, then you'll have the same vehicle_id (for a train car) many times, which means that assignment_start and assignment_end would need to be part of any join. But then you would need to also have them populated for bus vehicles, right? Would we recommend placeholders in that case?

[gabriel-korbato]

We had a good meeting today about the vehicle_assignments table. Time ran out before we had a chance to discuss vehicle_direction, and we also identified the need to discuss the names of each table and column.

For vehicle_direction, we should consider whether if would be more user friendly to replace the enum with a leading_car or first_car field.

[jlstpaul]

Time ran out before we had a chance to discuss vehicle_direction...

For vehicle_direction, we should consider whether if would be more user friendly to replace the enum with a leading_car or first_car field.

There are several proposed new fields related to the "direction" or "orientation" of consists and cars within consists.

Order: When cars are combined into a consist, they are assigned an order where 1 is the first car, 2 is the second car, and so on. The number 1 car is defined to be the "front" of the consist. This can be somewhat arbitrary, but it is necessary to have a "front" of the consist.

Orientation: Each car within a consist has an orientation within the consist. The orientation is either forward or backward. For this to make sense, the car must have an inherent front and back. For example, an articulated LRV may have an A car and a B car and the A car would be defined as the front of the car. If the front of the car is facing towards the front of the consist (the number 1 car), then the orientation of the car within the consist is forward.

Direction: When a consist is traveling, whether it is one-car or multiple cars, it can be traveling either forward or backward. When the consist has multiple cars, then forward direction is defined as the direction of the number 1 car of the consist. If the consist has only one car, then the forward direction is defined as the "front" of the car.

Order and Orientation of cars within a consist are set when the consist is created and are static attributes of the consist.

Direction of a consist changes over the course of operation so it is an attribute of operational data records (events, trips, stops, etc.). One question to address is whether the direction of the consist is always the same over the course of an entire trip or whether it can change within a trip.