Vehicle assignments

[antrim]

Proposed spec in response to issue #28 "Allocating drivers and vehicles in ODS".

What it does: Assign individual vehicles to blocks.

What it does NOT do:

• Introduce vehicle types, categories, groupings, or couplings. These could be added in a future version, looking towards drawing from the [http://bit.ly/gtfs-vehicles](GTFS-Vehicles proposal).
• Assign vehicles according to a regular weekly schedule (i.e. instead of individual service date)

Changes included:

• vehicles.txt: ID, text label, license plate. Only a few attribute fields are defined for a minimum viable proposal. TODS consumers may be able to look up additional attributes by vehicle_id. More attributes can be defined in future TODS versions.
• vehicle_assignments.txt: Assignments by service date, block_id, service_id

[github-actions]

Preview url: https://operational-data-standard-85--cal-itp-previews.netlify.app

[antrim]

Based on this #28 (comment) - what @skyqrose outlined in August

Notes:

• vehicles.txt and vehicle_categories.txt crib liberally from http://bit.ly/gtfs-vehicles. That proposal aligned with platform descriptions for GTFS-Pathways. I don't know the current status of that proposal. I included a baseline of fields; perhaps more should be included in this proposal.
• I considered whether to relate vehicle assignments to run_events.txt, but since mid-run events would never involve the change of a vehicle, this would have created more complexity.
• vehicle_assignments can map to trip_id or block_id. This is for cases where block_id is not universally supplied, perhaps because a GTFS feed follows the original usage of block_id - indicating allowed in-seat transfers.

[antrim]

Some internal discussion at Optibus:
Timon Kelter suggested that vehicle_categories sounds very abstract, but vehicle_types would be more natural and is descriptive. I agree. I had was cribbing from the GTFS-Vehicles proposal, but don't see a reason to keep this term. Will plan to change to vehicle_types.txt.
BTW, I have invited Optibus team to share more discussion here. So we'll expose a bit more deliberation that might otherwise have been internal :)

[antrim]

These are vehicle properties that Optibus currently exports in a non TODS format. Which properties should be included in TODS?

Vehicle properties example.xlsx

vehicle_id	ID	Identifies a vehicle.
agency_id	ID referencing agency.agency_id	Agency for the specified vehicle.
start_date	Date	Day when the vehicle begins to be part of the fleet.
license_plate	Text	License plate of the specified vehicle.
make	Text	Make of the specified vehicle.
model	Text	Model of the specified vehicle.
owner	Text	Vehicle owner entity.
registration_date	Date	Date of the first registration.
available_seats	Non-negative Integer	Number of seating places.
available_standing	Non-negative Integer	Number of standing places.
typology	Enum	Vehicle typology. 0 or empty = unknown typology 1 = Urban Mini 2 = Urban Midi 3 = Urban Standard 4 = Urban Articulated 5 = Inter-urban Standard 6 = Inter-urban Articulated 7 = Tourism
vclass	Enum	Vehicle class. 0 or empty = unknown class 1 = A (Urban Mini) 2 = I (Urban Midi, Urban Standard, Urban Articulated) 3 = II (Inter-urban Standard, Inter-urban Articulated) 4 = III (Tourism)
propulsion	Enum	Propulsion technology. 0 or empty = unknown propulsion 1 = Gasoline 2 = Diesel 3 = LPG auto 4 = Mixture 5 = Biodiesel 6 = Electricity 7 = Hybrid 8 = Natural Gas 9 = Other
emission	Enum	Emissions class. 0 or empty = unkwon emissions class 1 = EURO I 2 = EURO II 3 = EURO III 4 = EURO IV 5 = EURO V 6 = EURO VI
new_seminew	Enum	New or Semi-New. 0 or empty = no 1 = yes
ecological	Enum	Non-polluting or energy-efficient vehicle. 0 or empty = no 1 = yes
climatization	Enum	Climatization. 0 or empty = no 1 = yes
wheelchair	Enum	Wheelchair accessible. 0 or empty = no 1 = yes
corridor	Enum	Passageway for wheelchairs / baby strollers. 0 or empty = no 1 = yes
lowered_floor	Enum	Lowered floor. 0 or empty = no 1 = yes
ramp	Enum	Ramp for people with reduced mobility. 0 or empty = no 1 = yes
folding_system	Enum	Folding system for boarding and exiting of people with reduced mobility. 0 or empty = no 1 = yes
kneeling	Enum	Vehicle "kneeling" to reduce entry height. 0 or empty = no 1 = yes
static_information	Enum	Posters and fixed signage. 0 or empty = no 1 = yes
onboard_monitor	Enum	On-board monitor. 0 or empty = no 1 = yes
front_display	Enum	External front destination display. 0 or empty = no 1 = yes
rear_display	Enum	External rear destination panel. 0 or empty = no 1 = yes
side_display	Enum	External right side destination panel. 0 or empty = no 1 = yes
internal_sound	Enum	Internal sound information (on-board Public Address). 0 or empty = no 1 = yes
external_sound	Enum	External sound information (external Public Address). 0 or empty = no 1 = yes
consumption_meter	Enum	Consumption measurement. 0 or empty = no 1 = yes
bicycles	Enum	Permission to transport non-folding bicycles (folding bicycles are always allowed). 0 or empty = no 1 = yes
passenger_counting	Enum	Vehicle has a passenger counting system. 0 or empty = no 1 = yes
video_surveillance	Enum	Vehicle has a video surveillance system. 0 or empty = no 1 = yes

[timon-k]

From the fields mentioned above, I would remove at least new_seminew, ecological, static_information, onboard_monitor, all *_display fields, all *_sound fields and consumption_meter.

To me, those look too undefined, covered by other attributes like emission already or just not needed for operational purposes.

I'm also very unsure about folding_system, ramp and kneeling. Given that we have wheelchair and lowered_floow already that looks like too many details on the same question.

[timon-k]

Having the category here sounds good, but perhaps we should then stress that this is the operationally assigned category of vehicle, not the planned one.

The planned vehicle category/type would be more naturally placed in routes_supplement.txt or trips_supplement.txt. Usually, planned and real vehicle type should be identical, but there could be differences.

[antrim]

Yes. GTFS-Vehicles had proposed to add a routes.vehicle_category_id field that would define "a default vehicle category for all trips belonging to this route". This could be useful for rider-facing applications (i.e. accessibility & amenity information) and for planning, scheduling, and operational purposes as well, I imagine.

[antrim]

@skyqrose @safrazier17 Can you help guide process here? Since I worked off the #81 branch, this has the rosters and employee assignments spec draft. Should I remove those changes?

Will we vote on the two PRs separately or together? Merge separately?

[skyqrose]

I've left lots of line-by-line comments.

As for the process, I think this is completely independent from #81. We could split them into two separate PRs/votes.

[skyqrose]

Would an agency ever schedule multiple vehicles to the same block? Doesn't that go against the definition of block? I know that might happen as a realtime adjustment, but if it's scheduled to happen, shouldn't they change the schedule so it's multiple different blocks?

If we can make that assumption, then this field could be removed.

[antrim]

I included trip_id as an option for cases where block_id is not supplied in the GTFS. On 2nd thought I'd favor removing, unless we know this is a case to plan for out of the gate.

[antrim]

f3281fe

[jeffkessler-keolis]

I'd recommend including it for specific trips. This works for agencies that don't publish blocks and may not wish to make specific trip-specific block assignments in TODS, and likewise works for agencies with interchangeable operations. (I could see us making these assignments on a trip-specific level to specify requirements by trip prior to building out cycles.)

[timon-k]

I'm in favour of keeping it as it is now, with the trip_id removed.

If we allow assignments of individual trips to vehicles it breaks the logic of blocks as @skyqrose pointed out.

If we allow assignments of individual trips to vehicle types/categories it overlaps content-wise with http://bit.ly/gtfs-vehicles (which already has a route-to-vehicle-category assignment modeling a "requirement"). The case that you pointed out last ("specify requirements by trip prior to building out cycles") should probably be modeled using http://bit.ly/gtfs-vehicles.

"agencies that don't publish blocks" can still wrap each trip in an artificial block and assign it this way and/or add their real blocks in the non-public trips_supplement.txt only.

So overall, it seems like we can transmit the operational plan (including which vehicles/types will really be running the trips) without allowing to include trip_id in the assignments.

[antrim]

We've been discussing this internally at Optibus, including with some CAD/AVL partners. For the upcoming version, we propose a "least viable" approach:

• Remove vehicle_types.txt
• Scale vehicles.txt down to vehicle_id and license_plate

This removes speculative vehicle attributes. The CAD/AVL should be able to look up vehicle attributes stored in that system.

Thoughts/reactions?

[skyqrose]

That does remove the ability to assign a type of vehicle without assigning a specific vehicle, but that's probably fine if we're aiming for a least viable approach.

[antrim]

@skyqrose If we pass a version of this without vehicle types, I think the discussion was still useful, so thanks for the review and great comments. And if we do add in more vehicle attributes besides the ID and license plate, then bringing back in vehicle type seems useful.

[antrim]

Proposed changes (from discussion today):

• vehicle_id required
• Remove vehicle_type_id (and vehicle_types.txt file) with a note that this may be introduced in the future, in order to mitigate issues that would be caused by a later backwards-incompatibile change to add vehicle_type_id and make vehicle_id conditionally required.
• Also, in service of future spec evolution, mention GTFS-Vehicles and add note about train couplings
• Add a vehicle label field (e.g. like the name of a ferry)
• Recommend (do NOT require) vehicle_id should match GTFS-realtime vehicle_id
• Keep license_plate field since it matches GTFS-realtime, but note other global identifier may be supplied, particularly for non-road vehicle types, e.g. Maritime Mobile Service Identity (MMSI) for ferries

[safrazier17]

Pre-vote checklist (@antrim)

• Remove vehicle_types.txt
• Remove vehicles.vehicle_type_id
• Remove vehicles.vehicle_description
• Remove vehicles.registration_date
• Remove vehicles.owner
• Edit description of vehicles.license_plate to account for its use as a more generic unique vehicle identifier
• Add vehicles.vehicle_label
• Remove vehicle_assignments.vehicle_type_id
• Edit vehicle_assignments.vehicle_id description to include note about roadmap plan to allow assignments to be made to groups of vehicles (a la vehicle type) rather than just to individual vehicles
• Add vehicle assignments examples
• Edit the PR description so that it includes an overview of proposed changes as they currently stand and the goal of the changes

[skyqrose]

this is looking much better now

[safrazier17]

VOTING PERIOD OPEN

Voting is open on this PR through 11:59:59 UTC on April 8 EDIT: April 15, 2025. This PR is one of 3 comprising the TODS 2.1 version proposal. The other PRs associated with the TODS 2.1 proposal are #80 and #87.

WHO IS ELIGIBLE TO VOTE

Any individual may vote as an ODS Contributor; in voting, Contributors are acknowledging and agreeing to the ODS Contributor Agreement and ODS Code of Conduct.

Issue Working Group members @BTollison, @jeffkessler-keolis, @skyqrose, @jfabi, @safrazier17, @antrim, @hodb are not eligible to vote on this proposal.

HOW TO VOTE

• A vote of support for this PR, comment "+1 [Individual or Organization Name]"
• To support the proposal with a minor correction, add one comment to the PR including both the correction and "+1 [Individual or Organization Name]"
• To vote for a substantial revision to the proposal, comment "-1 [Individual or Organization Name]" along with a brief description of what you believe needs to be substantially revised before the proposal can be adopted. NOTE: TODS governance requires that voters requesting substantial revision commit to working with the Issue Working Group to develop their recommended revision.

OUTCOMES

• At the end of the voting period, if the proposal has received at least THREE (3) +1 votes from stakeholders outside of the Issue Working Group and votes of "Support with Minor Correction" or "Substantial Revision," the proposal is immediately adopted.
• If the proposal receives one or more votes of "Support with Minor Correction," the Issue Working Group may decide whether to incorporate the recommended changes or to appeal to the Board for consideration of the necessity of the recommended changes.
  • If the issue working group or the Board determine that the minor changes should be incorporated into the proposal, the proposal shall be updated and the TODS community shall be notified of the updates. After a period of FOUR (4) business days, the proposal shall be adopted immediately unless valid objections to the minor changes are received. No new voting period is automatically initiated.
• If the proposal receives one or more votes of substantial changes, the author(s) of the recommended changes must commit to working with the issue working group to develop an alternative proposal that meets the need raised by the reviewer. The issue working group may appeal to the Board if they believe a recommended substantial change is without merit.
  • If a proposal is substantially changed, then a new voting period must be opened before the amended proposal can be adopted.
• If the proposal does not meet the minimum threshold for votes outside of the issue working group, the working group may appeal to the Board for a decision. The Board may vote to adopt the proposal or to require a new voting period.

[timon-k]

+1 [Optibus]

[paulswartz]

question: should this be recommended to match the label field in GTFS-RT?

[timon-k]

I'm not very familiar with GTFS-RT, but it sounds logical to add this hint.

Would it have a direct benefit to recommend this explicitly? The vehicle_id is already recommended to match the one from GTFS-RT, what would an additional sync of the label be good for?

[paulswartz]

For MBTA, it's unlikely that a vehicle_id would match, as we create unique vehicle IDs for different consists.

The label field will continue to match individual cars within a consist. Updating the text would also match with the text below about license_plate aligning with GTFS-RT.

[sbindman]

[Sarah from Swiftly]
Apologies for raising questions so late during the voting period but I am not clear on who will be able to leverage this spec. In my experience, I have not seen agencies know vehicle assignments far enough ahead of time to put them in a data feed, but rather it is more common to figure out vehicle assignments day of. I would love to learn about real-world cases where this would be applicable to understand whether it makes sense to add scope to the spec. Thanks!

[evansiroky]

Caltrans would like to have some more information on this specification modification proposal before voting. We conceptually like the idea of noting vehicle assignments. However, we echo @sbindman's inquiry and concerns into how this could be used in practice. Vehicle assignments can vary widely from day-to-day or even on an intra-day basis.

It would be great if some clarity could be introduced up-front into the use cases that these vehicle assignments are likely to help resolve and to suggest other methods for delivering vehicle assignments when the use cases demand finer-grained detail or more realtime delivery of vehicle assignments.

To guess on how this might be helpful, this seems mainly useful for fleet planning and optimization use cases, but in a realtime sense it may not be useful and could be too rigid to support intra-day or even intra-week vehicle assignment variability. And then from a historical perspective (perhaps even realtime??), it seems like the TIDES Trips Performed could be more appropriate for noting the exact operational vehicle assignments that ended up occurring.

Also, a minor formatting request is to note these new files at the list of files towards the beginning of the document.

[evansiroky]

Please add an entry to this file in the Files section of this document.

[evansiroky]

Please add a link to this file in the Files section of this document.

[timon-k]

[Sarah from Swiftly] Apologies for raising questions so late during the voting period but I am not clear on who will be able to leverage this spec. In my experience, I have not seen agencies know vehicle assignments far enough ahead of time to put them in a data feed, but rather it is more common to figure out vehicle assignments day of. I would love to learn about real-world cases where this would be applicable to understand whether it makes sense to add scope to the spec. Thanks!

@sbindman Our intended use case is transmitting the vehicle assignments for the immediate next days (typically the next
1-3 days) into a CAD/AVL system. It's not so much about transmitting a long-term assignment plan, I'm not aware of such a use case in reality.

@evansiroky We did not consider historical data, for that it indeed will be better to use TIDES Trips Performed. It's about the assignments for the next few days only.

Apart from the use case of getting existing vehicle assignments into a CAD/AVL system, transmitting the assignments for the next day can also be used for charge management systems (battery-electric buses). That system needs to know which vehicles will enter/leave a depot in the next day so that they can plan the charging in the best possible way.

As with the rest of TODS, we did not have real-time use cases in mind here.

[evansiroky]

@timon-k thanks for the clarifications that TODS is intended as a "planned" dataset.

I will go ahead and vote a cautious +1 on behalf of Caltrans as I think the concept makes sense, but still wonder about how applicable this is in the field.

I think it would be great to clarify the timing and use cases. The GTFS specification notes that:

the published GTFS dataset should be valid for at least the next 7 days

This is somewhat in conflict with what you've mentioned as the immediate next days (typically the next 1-3 days) with TODS, but perhaps this is to be expected in whatever context this is being used.

[Matthias-Gruetzner]

I am neutral on PRs 85 and 87. In my eyes, vehicle and driver assignments are a different interface and data is updated on a different schedule, but I see that it can be useful.

[arthi-weta]

+1 [San Francisco Bay Ferry]

[erik-a-jensen]

Looks like trying this from my work computer yesterday didn't go through unfortunately, but +1 [CTA]

[safrazier17]

VOTING PERIOD CLOSED

The voting period for this proposal closed yesterday, April 15 at 11:59:59 UTC. The proposal received the following votes:

Support (3): @timon-k (Optibus), @evansiroky (Cal-ITP), @arthi-weta (WETA)
Support with minor correction (0): No votes recorded
Substantial Revision (0): No votes recorded

The proposal has met the threshold of support needed and passes.