Vehicle assignments

docs/spec/examples.md

@@ -168,3 +168,24 @@ weekday,10000,20,BLOCK-A,deadhead       ,,garage,08:50:00,stop-1,09:00:00
 weekday,10000,30,BLOCK-A,run-as-directed,,stop-1,09:00:00,stop-1,12:00:00
 weekday,10000,30,BLOCK-A,deadhead       ,,stop-1,12:00:00,garage,12:10:00
 ```
+
+## Vehicle assignments by service date
+
+### `vehicles.txt`
+
+```csv
+vehicle_id,vehicle_label,license_plate
+bus-1,Old Reliable,OR-E285104
+bus-2,Buster,OR-E251432
+```
+
+### `vehicle_assignments.txt`
+
+In this example, vehicle assignments are provided for 3 consecutive days from February 5 through 7.
+
+```csv
+date,service_id,block_id,vehicle_id
+20250205,daily,BLOCK-A,bus-1
+20250206,daily,BLOCK-A,bus-2
+20250207,daily,BLOCK-A,bus-1
+```

docs/spec/index.md

@@ -139,3 +139,30 @@ Because some events may overlap in time, it may not be possible to choose a sing
 - Events may have gaps between the end time of one event and the start time of the next. e.g. if an operator's layovers aren't represented by an event.
 - `start_time` may equal `end_time` for an event that's a single point in time (such as a report time) without any duration.
 - Recommended sort order: `service_id`, `run_id`, `event_sequence`.
+
+### `vehicle_assignments.txt`
+
+Primary Key: `(date, block_id, service_id)`
+
+| Field Name | Type | Required | Description |
+|---|---|---|---|
+| `date` | Date | Required |  |
+| `service_id` | ID referencing `calendar.service_id` or `calendar_dates.service_id` | Optional | Identifies a set of *service days* when the trip is scheduled to take place. Note the [https://github.com/google/transit/blob/master/gtfs/spec/en/reference.md#term-definitions](GTFS definition) of *service day* is invoked here. Required if `block_id`s are repeated between different `service_id`s. |
+| `block_id`		  | ID referencing `trips.block_id` | Required | Identifies the block. |
+| `vehicle_id` | ID referencing `vehicles.vehicle_id` | Required | Refers to a specific vehicle in the transit fleet. |
+
+Not every block and date combo needs to have a vehicle specified.
+
+*Note for future-compatibility:* `vehicle_id` field may change to conditionally required in a future version where assignments may be made to either an individual vehicle OR a grouping of vehicles. See [GTFS-Vehicles](http://bit.ly/gtfs-vehicles) for how vehicle categories (types) might be incorporated.
+
+### `vehicles.txt`
+
+Primary Key: `vehicle_id`
+
+| Field Name | Type | Required | Description |
+|---|---|---|---|
+| `vehicle_id` | ID, primary key | Required | Defines an ID for a vehicle. It is *recommended* but not required to match the `vehicle_id` in GTFS-realtime feeds. |
+| `vehicle_label` | Text | Optional | Free text label for a vehicle, e.g. bus number or vessel name. |
+| `license_plate` | Text | Optional | License number or global identifier for the vehicle, e.g. “E898656”. The field name was chosen to align with the `license_plate` field in GTFS-Realtime. It may specify a different global identifier, particularly for non-road vehicle types without license plates, e.g. Maritime Mobile Service Identity (MMSI) for ferries. |
+
+*Note for future-compatibility:* Future TODS versions may support vehicle couplings: specifically, train cars (individual vehicles) that comprise a train set. Such a proposal is described by the [GTFS-VehicleCouplings draft extension](http://bit.ly/gtfs-vehicles).