Add new vehicle_label field to vehicles table

[chrisyamas]

Summary

Adds an optional vehicle_label field to the vehicles table to distinguish between internal vehicle IDs and public-facing vehicle numbers displayed on the exterior if vehicles. This new field aligns with GTFS-realtime VehicleDescriptor which has both id and label.

Resolves #240

Changes

• spec/vehicles.schema.json added new optional field vehicle_label:
  • type: string
  • description: User-visible label for the vehicle, such as the vehicle number displayed on the exterior. This may differ from vehicle_id, which is the internal identifier. Aligns with GTFS-realtime VehicleDescriptor.label.
  • no constraints (optional field)
  • positioned logically after vehicle_id
• CHANGELOG.md added entry under [Unreleased] > ### Added

Reason for this change

Agencies often have two different identifiers for vehicles:

• an internal ID (vehicle_id) used in fleet management, maintenance systems, and internal databases
• a public-facing number (vehicle_label) displayed on the vehicle exterior for passengers and customer service

Currently the TIDES spec only has vehicle_id, which forces agencies to either lose the public-facing number or use inconsistent workarounds. Adding vehicle_label provides a standard place for this common data element (and aligns with GTFS-realtime's VehicleDescriptor.label).

- See related discussion in Issue #240 and Fall 2025 TIDES Issues Working Group notes from December 10.

Review checklist

Per change management policy, the following must be met before feature branch changes can merge to develop branch:

• All JSON files validate
• Reviewed and approved by 2+ contributors or board members

---

Community review status (updated August 27, 2026)

How community review works: Per the TIDES Change Management Policy, a proposal moves forward once at least three TIDES Contributors outside the originating working group publicly comment with a score: Accepted, Accepted with minor changes, or Substantially revised. A few sentences with your read of the proposal is a complete review.

Originating working group (Fall 2025 Issues Working Group, December 1 and 10, 2025 sessions): Christopher Yamas, Gabriel Sánchez Martínez, Ian Thistle, Jay Gordon, John Levin, Joey Reid, Spenser Sutinen. Their work is reflected in the proposal itself; community review comes from Contributors beyond this group.

Review so far: @lauriemerrell has approved this PR (Accepted), and @paulswartz shared the MBTA ground truth on label uniqueness that settled the design; a scored comment here would add that review to the record.

Thanks to everyone who has weighed in on this proposal; it is moving into final consideration for v2.0. Further comments are always welcome.

[github-actions]

Documentation available at: http://tides-transit.github.io/TIDES/feature/issue-240-vehicle-label

[jlstpaul]

Should samples/template/TIDES/vehicles.csv also be update to add the field.

[github-actions]

Data Validation Report

Sample	Status
./samples/template/TIDES	✔️

[chrisyamas]

Should samples/template/TIDES/vehicles.csv also be update to add the field.

Yes, I went ahead and added vehicle_label as a column in amples/template/TIDES/vehicles.csv, thanks for the suggestion @jlstpaul !

[CTRAN-Sutinen]

vehicle_label is functionally a unique id, I think we need to have a uniqueness constraint.

[paulswartz]

vehicle_label is functionally a unique id, I think we need to have a uniqueness constraint.

Drive-by note: at least for MBTA this is not the case. We have vehicles with the same label, even inside a single mode. 15xx overlaps between both Red and Orange Line cars: http://roster.transithistory.org/

[github-actions]

Data Validation Report

Sample	Status
./samples/template/TIDES	✔️

[chrisyamas]

vehicle_label is functionally a unique id, I think we need to have a uniqueness constraint.

This has been resolved, as vehicle_label is determined not to be unique. This can move forward as-is.

[chrisyamas]

@paulswartz your MBTA example settled the uniqueness question here; labels stay non-unique, and Spenser withdrew the constraint suggestion at the 8/13 Contributors meeting.

If the final shape looks right to you, a comment with a score (Accepted / Accepted with minor changes / Substantially revised) would wrap up your review on this one.