employee_run_dates.txt

docs/spec/examples.md

@@ -168,3 +168,67 @@ 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
 ```
+
+## Employee Assignments
+
+This example uses [`employee_run_dates.txt`](/docs/spec.md#employee_run_datestxt) to assign employees to runs (and trips).
+
+In this example, `A` and `B` work Monday-Wednesday and Sunday. `C` and `D` work Thursday-Saturday.
+
+On Wedneday, July 3, `A` has scheduled vacation, so a substitute is assigned instead.
+
+**[`calendar.txt`](https://gtfs.org/documentation/schedule/reference/#calendartxt)**
+
+```csv
+service_id,monday,tuesday,wednesday,thursday,friday,saturday,sunday,start_date,end_date
+weekday,1,1,1,1,1,0,0,20240701,20240707
+weekend,0,0,0,0,0,1,1,20240701,20240707
+```
+
+July 1, 2024 was a Monday.
+
+**[`run_events.txt`](/docs/spec.md#run_eventstxt)**
+
+For this example, the purpose of this file is just to show which runs exist. Real runs would have more interesting data.
+
+```csv
+service_id,run_id,event_sequence,event_type,trip_id,start_location,start_time,end_location,end_time
+weekday,101,1,work,trip1,station,09:00:00,station,17:00:00
+weekday,102,1,work,trip2,station,09:00:00,station,17:00:00
+weekend,103,1,work,trip3,station,09:00:00,station,17:00:00
+weekend,104,1,work,trip4,station,09:00:00,station,17:00:00
+```
+
+**[`employee_run_dates.txt`](/docs/spec.md#employee_run_datestxt)**
+
+```csv
+date,employee_id,service_id,run_id
+20240701,A,weekday,101
+20240701,B,weekday,102
+20240702,A,weekday,101
+20240702,B,weekday,102
+20240703,E,weekday,101
+20240703,B,weekday,102
+20240704,C,weekday,101
+20240704,D,weekday,102
+20240705,C,weekday,101
+20240705,D,weekday,102
+20240706,C,weekend,103
+20240706,D,weekend,104
+20240707,A,weekend,103
+20240707,B,weekend,104
+20240701,A,weekday,101
+20240701,B,weekday,102
+20240702,A,weekday,101
+20240702,B,weekday,102
+20240703,A,weekday,101
+20240703,B,weekday,102
+20240704,C,weekday,101
+20240704,D,weekday,102
+20240705,C,weekday,101
+20240705,D,weekday,102
+20240706,C,weekend,103
+20240706,D,weekend,104
+20240707,A,weekend,103
+20240707,B,weekend,104
+```

docs/spec/index.md

@@ -12,6 +12,8 @@ There are two types of files used in the TODS standard:
 - **Supplement files**, used to add, modify, and delete information from public GTFS files to model the operational service for internal purposes (with a `_supplement` filename suffix).
 - **TODS-Specific files**, used to model operational elements not currently defined in the GTFS standard.
 
+All files are optional.
+
 ### Files
 
 | **File Name** | **Type** | **Description** |
@@ -21,6 +23,7 @@ There are two types of files used in the TODS standard:
 | stop_times_supplement.txt | Supplement | Supplements and modifies GTFS [stop_times.txt](https://github.com/google/transit/blob/master/gtfs/spec/en/reference.md#stop_timestxt) with non-public times at which trips stop at locations, `stop_times` entries for non-public trips, and related information. |
 | routes_supplement.txt | Supplement | Supplements and modifies GTFS [routes.txt](https://github.com/google/transit/blob/master/gtfs/spec/en/reference.md#routestxt) with internal route identifiers and other non-public route identification. |
 | run_events.txt | TODS-Specific | Lists all trips and other scheduled activities to be performed by a member of personnel during a run. |
+| employee_run_dates.txt | TODS-Specific | Assigns employees to runs. |
 
 _The use of the Supplement standard to modify other GTFS files is not yet formally adopted into the specification and remains subject to change. Other files may be formally adopted in the future._
 
@@ -133,9 +136,28 @@ Events that don't have `trip_id` set may overlap in time with any other events.
 
 Because some events may overlap in time, it may not be possible to choose a single order for events within a run that's correct for all uses. Producers should use `event_sequence` to define a reasonable order. If a consumer cares about exactly how overlapping events are ordered, they should sort based on the time fields and `event_type` instead.
 
+#### Run ID Uniqueness
+
+Run IDs may be non-unique. E.g. E.g. there may be a "Run 100" on both Weekday and Weekend service. There may even be a Run 100 on both `garage1-weekday` and `garage2-weekday` services, happening on the same day. Runs are uniquely referred to by a `(service_id, run_id)` pair. This is why the service ID is required on this file and other files that refer to run IDs.
+
 #### `run_events` Notes
 
 - Multiple `run_event`s may refer to the same `trip_id`, if multiple employees work on that trip.
 - 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`.
+
+### `employee_run_dates.txt`
+
+Describes which employees are scheduled to which runs on which dates.
+
+This file should represent the schedule after holidays, vacation, and other scheduled exceptions have been applied.
+
+Primary Key: `*`
+
+| **Field Name** | **Type** | **Required** | **Description** |
+| --- | --- | --- | --- |
+| `date` | Date | Required | Service date. |
+| `employee_id` | ID | Required | References an agency's external systems. Employee IDs are not used elsewhere in TODS. |
+| `service_id` | ID referencing `run_events.txt` | Required | Part of the Run ID, which is refered to as `(service_id, run_id)`. See [Run ID Uniqueness](#run-id-uniqueness). |
+| `run_id` | ID referencing `run_events.txt` | Required | The run that's added to this employee's schedule. |