docs: clarify v2.1.0 conformance requirements

docs/en/spec/examples.md

@@ -107,14 +107,14 @@ deadhead-2,15:00:00,garage,3
 
 ```csv
 service_id,run_id,event_sequence,piece_id,block_id,job_type,event_type,trip_id,start_location,start_time,start_mid_trip,end_location,end_time,end_mid_trip
-daily,10000,10,       ,       ,Operator,Report Time,        ,garage,09:30:00,,garage,09:30:00,
-daily,10000,20,       ,       ,Operator,Pre-Trip Inspection,,garage,09:35:00,,garage,09:45:00,
-daily,10000,30,10000-1,BLOCK-A,Operator,Pull-Out,deadhead-1 ,garage,09:45:00,2,stop-1,09:55:00,2
-daily,10000,40,10000-1,BLOCK-A,Operator,Operator,101        ,stop-1,10:00:00,2,stop-3,10:50:00,2
-daily,10000,50,10000-1,BLOCK-A,Operator,Operator,102        ,stop-3,11:00:00,2,stop-1,11:50:00,2
-daily,10000,60,       ,       ,Operator,Break,              ,stop-1,11:50:00,,stop-1,13:00:00,
-daily,10000,70,10000-2,BLOCK-A,Operator,Operator,103        ,stop-1,13:00:00,2,stop-3,13:50:00,2
-daily,10000,80,10000-2,BLOCK-A,Operator,Operator,104        ,stop-3,14:00:00,2,stop-1,14:50:00,2
+daily,10000,10,,,Operator,Report Time,,garage,09:30:00,,garage,09:30:00,
+daily,10000,20,,,Operator,Pre-Trip Inspection,,garage,09:35:00,,garage,09:45:00,
+daily,10000,30,10000-1,BLOCK-A,Operator,Pull-Out,deadhead-1,garage,09:45:00,2,stop-1,09:55:00,2
+daily,10000,40,10000-1,BLOCK-A,Operator,Operator,101,stop-1,10:00:00,2,stop-3,10:50:00,2
+daily,10000,50,10000-1,BLOCK-A,Operator,Operator,102,stop-3,11:00:00,2,stop-1,11:50:00,2
+daily,10000,60,,,Operator,Break,,stop-1,11:50:00,,stop-1,13:00:00,
+daily,10000,70,10000-2,BLOCK-A,Operator,Operator,103,stop-1,13:00:00,2,stop-3,13:50:00,2
+daily,10000,80,10000-2,BLOCK-A,Operator,Operator,104,stop-3,14:00:00,2,stop-1,14:50:00,2
 daily,10000,90,10000-2,BLOCK-A,Operator,Pull-Back,deadhead-2,stop-1,14:50:00,2,garage,15:00:00,2
 ```
 
@@ -163,10 +163,10 @@ In this example (unrelated to the previous examples), an operator signs in for t
 
 ```csv
 service_id,run_id,event_sequence,block_id,event_type,trip_id,start_location,start_time,end_location,end_time
-weekday,10000,10,       ,sign-in        ,,garage,08:45:00,garage,08:50:00
-weekday,10000,20,BLOCK-A,deadhead       ,,garage,08:50:00,stop-1,09:00:00
+weekday,10000,10,,sign-in,,garage,08:45:00,garage,08:50:00
+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,40,BLOCK-A,deadhead       ,,stop-1,12:00:00,garage,12:10:00
+weekday,10000,40,BLOCK-A,deadhead,,stop-1,12:00:00,garage,12:10:00
 ```
 
 ## Jobs of entirely nonrevenue operations
@@ -204,10 +204,10 @@ This file references the service ID and trip ID defined in the other supplement
 
 ```csv
 service_id,run_id,event_sequence,event_type,trip_id,start_location,start_time,end_location,end_time
-inspection_train ,1 ,1 ,sign-in  ,                    ,main_terminal ,23:45:00 ,main_terminal ,23:45:00
-inspection_train ,1 ,2 ,operator ,inspection_line1_ob ,downtown      ,24:00:00 ,anytown       ,24:45:00
-inspection_train ,1 ,3 ,operator ,inspection_line1_ib ,anytown       ,25:00:00 ,downtown      ,25:45:00
-inspection_train ,1 ,4 ,sign-off ,                    ,main_terminal ,26:00:00 ,main_terminal ,26:00:00
+inspection_train,1,1,sign-in,,main_terminal,23:45:00,main_terminal,23:45:00
+inspection_train,1,2,operator,inspection_line1_ob,downtown,24:00:00,anytown,24:45:00
+inspection_train,1,3,operator,inspection_line1_ib,anytown,25:00:00,downtown,25:45:00
+inspection_train,1,4,sign-off,,main_terminal,26:00:00,main_terminal,26:00:00
 ```
 
 ## Distinct Crew and Trip schedule scenarios
@@ -248,10 +248,10 @@ gameday,20240903,1
 
 ```csv
 service_id,run_id,event_sequence,block_id,job_type,event_type,trip_id,start_location,start_time,end_location,end_time
-weekday,1,1,       ,collector,sign-in        ,   ,main_terminal,14:00:00,main_terminal,14:15:00
-weekday,1,2,BLOCK-A,collector,collector      ,101,main_terminal,14:45:00,ballpark     ,15:30:00
-gameday,2,1,       ,collector,sign-in        ,   ,main_terminal,14:00:00,main_terminal,14:15:00
-gameday,2,2,BLOCK-A,collector,extra collector,101,main_terminal,14:45:00,ballpark     ,15:30:00
+weekday,1,1,,collector,sign-in,,main_terminal,14:00:00,main_terminal,14:15:00
+weekday,1,2,BLOCK-A,collector,collector,101,main_terminal,14:45:00,ballpark,15:30:00
+gameday,2,1,,collector,sign-in,,main_terminal,14:00:00,main_terminal,14:15:00
+gameday,2,2,BLOCK-A,collector,extra collector,101,main_terminal,14:45:00,ballpark,15:30:00
 ```
 
 ### Trip worked by different runs on different dates
@@ -288,26 +288,26 @@ To detail the presence of the new `service_id`s and assign them to their applica
 ```csv
 service_id,monday,tuesday,wednesday,thursday,friday,saturday,sunday,start_date,end_date
 summer,1,1,1,1,1,0,0,20240601,20240831
-fall  ,1,1,1,1,1,0,0,20240901,20241231
+fall,1,1,1,1,1,0,0,20240901,20241231
 ```
 
 #### `run_events.txt`
 
 The current runs can be modeled with service_id `summer`, and mapped to the existing `weekday` trips. The future runs can be modeled with service_id `fall`, also mapped to the existing `weekday` trips. The service_id `weekday` is already defined in `calendar.txt`, but neither `summer` nor `fall` are.
 
 ```csv
-service_id ,run_id ,event_sequence ,block_id ,event_type ,trip_id ,start_location ,start_time ,end_location ,end_time
-summer ,1 ,20 ,A ,drive ,101 ,westcity ,09:00:00 ,eastland ,10:30:00
-summer ,1 ,30 ,A ,drive ,102 ,eastland ,10:45:00 ,westcity ,12:15:00
+service_id,run_id,event_sequence,block_id,event_type,trip_id,start_location,start_time,end_location,end_time
+summer,1,20,A,drive,101,westcity,09:00:00,eastland,10:30:00
+summer,1,30,A,drive,102,eastland,10:45:00,westcity,12:15:00
 
-summer ,2 ,20 ,B ,drive ,201 ,westcity ,09:00:00 ,eastland ,10:00:00
-summer ,2 ,30 ,B ,drive ,202 ,eastland ,11:00:00 ,westcity ,12:00:00
+summer,2,20,B,drive,201,westcity,09:00:00,eastland,10:00:00
+summer,2,30,B,drive,202,eastland,11:00:00,westcity,12:00:00
 
-fall   ,1 ,20 ,A ,drive ,101 ,westcity ,09:00:00 ,eastland ,10:30:00
-fall   ,1 ,30 ,A ,drive ,202 ,eastland ,11:00:00 ,westcity ,12:00:00
+fall,1,20,A,drive,101,westcity,09:00:00,eastland,10:30:00
+fall,1,30,A,drive,202,eastland,11:00:00,westcity,12:00:00
 
-fall   ,2 ,20 ,B ,drive ,201 ,westcity ,09:00:00 ,eastland ,10:00:00
-fall   ,2 ,30 ,B ,drive ,102 ,eastland ,10:45:00 ,westcity ,12:15:00
+fall,2,20,B,drive,201,westcity,09:00:00,eastland,10:00:00
+fall,2,30,B,drive,102,eastland,10:45:00,westcity,12:15:00
 ```
 
 (In this example, block IDs are listed in `run_events.txt` but not `trips.txt` because the blocks would also change with the schedule change.)

docs/en/spec/index.md

@@ -89,6 +89,7 @@ _Note that the station name "Three" was not modified, and the whole column stop_
 - As blank fields are ignored, data to be removed should either be overwritten with a new value or have their entire row deleted using the `TODS_delete` field.
 - As processing of files is non-sequential, it is prohibited to both delete and re-add a row with identical Primary Keys in the same Supplement file.
 - If a row contains defined values besides the Primary Key and a `TODS_delete` value of `1`, the row shall be removed and other values in that row will be ignored.
+- A row that will be added must define every field marked Required in the corresponding GTFS file, along with any Conditionally Required field whose condition applies to that row. A row that updates or deletes an existing entry does not need to define Required fields other than the Primary Key.
 - When adding rows and updating values, be certain to ensure the values are being updated based on their column values (e.g. if GTFS has fields of `trip_id,route_id,trip_short_name` and the TODS Supplement file has fields of `trip_id,trip_short_name`, be certain that values are mapping to the correct fields without assuming column headers are identical).
 - When deleting a row in a file, any references to that field/value shall be ignored. Thus, it is important to ensure references to that row are either redefined or are being intentionally omitted. For example:
     - When deleting a trip via `trips_supplement.txt`, all of that trip's entires in `stop_times.txt` will not be associated with a valid trip and would thus be ignored.
@@ -121,11 +122,11 @@ Primary Key: (`service_id`, `run_id`, `event_sequence`)
 | `job_type` | Text | Optional | The type of job that the employee is doing, in a human-readable format. e.g. "Assistant Conductor". Producers may use any values, but should be consistent.<br /><br />A single run may include more than one `job_type` throughout the day if the employee has multiple responsibilities, e.g. an "Operator" in the morning and a "Shifter" in the afternoon. |
 | `event_type` | Text | Required | The type of event that the employee is doing, in a human-readable format. e.g. "Sign-in". Producers may use any values, but should be consistent. Consumers may ignore events with an `event_type` that they don't recognize. |
 | `trip_id` | ID referencing `trips.trip_id` | Optional | If this run event corresponds to working on a trip, identifies that trip. Note that the trip may be on a different `service_id` than the run, see [`service_id`, Crew Schedules, and Trip Schedules](#service_id-crew-schedules-and-trip-schedules). |
-| `start_location` | ID referencing `stops.stop_id` | Required | Identifies where the employee starts working this event.<br /><br />If `trip_id` is set (and `mid_trip_start` is not `1`), this should be the `stop_id` of the first stop of the trip in `stop_times.txt` (after applying any trip supplement). If `start_mid_trip` is `1`, this should be the location where the employee starts working, matching a `stop_id` in the middle of the supplemented trip. |
-| `start_time` | Time, as [defined in GTFS](https://gtfs.org/documentation/schedule/reference/#field-types) | Required | Identifies the time when the employee starts working this event.<br /><br />If `trip_id` is set (and `mid_trip_start` is not `1`), this corresponds to the time of the first stop of the trip in `stop_times.txt` (after applying any trip supplement). If `start_mid_trip` is `1`, this time corresponds to a stop time in the middle of the supplemented trip, when the employee starts working on the trip. Note that this time may not exactly match `stop_times.txt` `arrival_time` or `departure_time` if the employee is considered to be working for a couple minutes before the trip departs. This field is about when the employee is working, and consumers who care about the the trip times should check `stop_times.txt` instead. |
+| `start_location` | ID referencing `stops.stop_id` | Required | Identifies where the employee starts working this event.<br /><br />If `trip_id` is set (and `start_mid_trip` is not `1`), this should be the `stop_id` of the first stop of the trip in `stop_times.txt` (after applying any trip supplement). If `start_mid_trip` is `1`, this should be the location where the employee starts working, matching a `stop_id` in the middle of the supplemented trip. |
+| `start_time` | Time, as [defined in GTFS](https://gtfs.org/documentation/schedule/reference/#field-types) | Required | Identifies the time when the employee starts working this event.<br /><br />If `trip_id` is set (and `start_mid_trip` is not `1`), this corresponds to the time of the first stop of the trip in `stop_times.txt` (after applying any trip supplement). If `start_mid_trip` is `1`, this time corresponds to a stop time in the middle of the supplemented trip, when the employee starts working on the trip. Note that this time may not exactly match `stop_times.txt` `arrival_time` or `departure_time` if the employee is considered to be working for a couple minutes before the trip departs. This field is about when the employee is working, and consumers who care about the trip times should check `stop_times.txt` instead. |
 | `start_mid_trip` | Enum | Optional | Indicates whether the event begins at the start of the trip or in the middle of the trip (after applying any trip supplement).<br /><br />`0` (or blank) - Run event is not associated with a trip, or no information about whether the run event starts mid-trip<br />`1` - Run event starts mid-trip<br />`2` - Run event does not start mid-trip |
-| `end_location` | ID referencing `stops.stop_id` | Required | Identifies where the employee stops working this event.<br /><br />If `trip_id` is set (and `mid_trip_end` is not `1`), this should be the `stop_id` of the last stop of the trip in `stop_times.txt` (after applying any trip supplement). If `end_mid_trip` is `1`, this should be the location where the employee stops working, matching a `stop_id` in the middle of the supplemented trip. |
-| `end_time` | Time, as [defined in GTFS](https://gtfs.org/documentation/schedule/reference/#field-types) | Required | Identifies the time when the employee stops working this event.<br /><br />If `trip_id` is set (and `mid_trip_end` is not `1`), this corresponds to the time of the last stop of the trip in `stop_times.txt` (after applying any trip supplement). If `end_mid_trip` is `1`, this time corresponds to a stop time in the middle of the supplemented trip, when the employee stops working on the trip. Note that this time may not exactly match `stop_times.txt` `arrival_time` or `departure_time` if the employee is considered to be working for a couple minutes after the trip finishes. This field is about when the employee is working, and consumers who care about the the trip times should check `stop_times.txt` instead. |
+| `end_location` | ID referencing `stops.stop_id` | Required | Identifies where the employee stops working this event.<br /><br />If `trip_id` is set (and `end_mid_trip` is not `1`), this should be the `stop_id` of the last stop of the trip in `stop_times.txt` (after applying any trip supplement). If `end_mid_trip` is `1`, this should be the location where the employee stops working, matching a `stop_id` in the middle of the supplemented trip. |
+| `end_time` | Time, as [defined in GTFS](https://gtfs.org/documentation/schedule/reference/#field-types) | Required | Identifies the time when the employee stops working this event.<br /><br />If `trip_id` is set (and `end_mid_trip` is not `1`), this corresponds to the time of the last stop of the trip in `stop_times.txt` (after applying any trip supplement). If `end_mid_trip` is `1`, this time corresponds to a stop time in the middle of the supplemented trip, when the employee stops working on the trip. Note that this time may not exactly match `stop_times.txt` `arrival_time` or `departure_time` if the employee is considered to be working for a couple minutes after the trip finishes. This field is about when the employee is working, and consumers who care about the trip times should check `stop_times.txt` instead. |
 | `end_mid_trip` | Enum | Optional | Indicates whether the event ends at the end of the trip or in the middle of the trip (after applying any trip supplement).<br /><br />`0` (or blank) - Run event is not associated with a trip, or no information about whether the run event ends mid-trip<br />`1` - Run event ends mid-trip<br />`2` - Run event does not end mid-trip |
 
 #### `service_id`, Crew Schedules, and Trip Schedules
@@ -172,7 +173,7 @@ This file should represent the schedule after holidays, vacations, and other sch
 
 Each run and date combination may appear 0 times in this file (if there's no assigned employee), 1 time, or multiple times (if multiple employees are assigned to the same run on the same date).
 
-Primary Key: `*`
+Primary Key: (`date`, `service_id`, `run_id`, `employee_id`)
 
 | **Field Name** | **Type** | **Required** | **Description** |
 | --- | --- | --- | --- |
@@ -200,7 +201,7 @@ 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 [GTFS definition](https://github.com/google/transit/blob/master/gtfs/spec/en/reference.md#term-definitions) of *service day* is invoked here. Required if `block_id`s are repeated between different `service_id`s. |
+| `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 [GTFS definition](https://github.com/google/transit/blob/master/gtfs/spec/en/reference.md#term-definitions) of *service day* is invoked here. Required when this row's `block_id` is used by trips with more than one `service_id`. |
 | `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. |