Reference ¶
The Transit Operational Data Standard was last updated on April 3, 2024 (v2.0 DRAFT). View the full revision history.
Dataset Files ¶
Structure ¶
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.
Files ¶
File Name | Type | Description |
---|---|---|
trips_supplement.txt | Supplement | Supplements and modifies GTFS trips.txt with deadheads and other non-public trip information. |
stops_supplement.txt | Supplement | Supplements and modifies GTFS stops.txt with internal stop locations, waypoints, and other non-public stop information. |
stop_times_supplement.txt | Supplement | Supplements and modifies GTFS stop_times.txt 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 with internal route identifiers and other non-public route identification. |
runs_pieces.txt | TODS-Specific | Defines daily personnel schedules within a feed. |
run_events.txt | TODS-Specific | Defines other scheduled activities to be performed by a member of personnel during a run. |
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.
Supplement Files ¶
Structure ¶
The fields in all Supplement files match those defined in the corresponding file’s GTFS specification.
The overall premise is to update and add data to GTFS, which is accomplished by either updating matching values or adding rows entirely.
Each entry in a Supplement file is paired with its matching entry in the corresponding GTFS file using the GTFS file’s Primary Key, i.e. the fields that uniquely identify the row. If no match is found, the Supplement file’s entry is added to the GTFS file in its entirety.
The standard also supports the removal of rows in their entirety.
Evaluation ¶
Each row in a Supplement file shall be evaluated as follows:
- If the row’s Primary Key is defined in the corresponding GTFS file, and the
TODS_delete
field is defined and equal to1
, remove the corresponding row from the GTFS file. - If the row’s Primary Key is defined in the corresponding GTFS file, and the
TODS_delete
field is not defined or not equal to1
, set or update any fields with defined values in the Supplement file to those values in the corresponding GTFS file. - If the row’s Primary Key is NOT defined in the corresponding GTFS file, add the row to the corresponding GTFS file.
In other words, where a Primary Key matches, the row is either removed or any non-empty values in the row are used to update the corresponding GTFS values. Where a Primary Key match does not exist, the entire row is added.
Example ¶
GTFS stops.txt
:
stop_id,stop_name,stop_desc,stop_url
1,One,Unmodified in TODS,example.com/1
2,Two,Deleted in TODS,example.com/2
3,Three,Will be modified in TODS,example.com/3
TODS stops_supplement.txt
:
stop_id,stop_name,stop_desc,TODS_delete
2,,,1
3,,Has been modified by TODS,
4,Four,New in TODS,
Effective stops.txt
after merging the supplement file:
stop_id,stop_name,stop_desc,stop_url
1,One,Unmodified in TODS,example.com/1
3,Three,Has been modified by TODS,example.com/3
4,Four,New in TODS,
Note that the station name “Three” was not modified, and the whole column stop_url was omitted and not modified.
Implications and Guidance ¶
- 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 of1
, the row shall be removed and other values in that row will be ignored. - 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 oftrip_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 instop_times.txt
will not be associated with a valid trip and would thus be ignored. - When deleting a route via
routes_supplement.txt
, all trips using that route would not be associated with a valid route and would thus be ignored UNLESS theroute_id
on the affected trips is updated via thetrips_supplement.txt
file.
- When deleting a trip via
- After modifying static GTFS content to incorporate the TODS Supplement modifications, the resulting data (“TODS-Supplemented GTFS”) should form a valid GTFS dataset, with the limited exception of missing data that should be ignored per the above.
TODS-Specific Fields ¶
In addition to the fields defined in GTFS, specific fields for use within TODS are denoted by a TODS_
field prefix.
File | Field Name | Type | Required | Description |
---|---|---|---|---|
Any Supplement file | TODS_delete |
Enum | Optional | (blank) - Update other fields; do not delete.1 - Deletes the GTFS row in the corresponding file whose Primary Key matches the value in the Supplement file’s row. |
trips_supplement.txt |
TODS_trip_type |
Text | Optional | Defines the type of the trip if distinct from a standard revenue trip. |
stops_supplement.txt |
TODS_location_type |
Text | Optional | Defines the type of the location if distinct from a standard GTFS location type. Where defined, the GTFS location_type shall be ignored. |
TODS-Specific File Definitions ¶
runs_pieces.txt ¶
Field Name | Type | Required | Description |
---|---|---|---|
run_id | ID | Required | Identifies a run. |
piece_id | ID | Required | Identifies the piece of the run. The piece_id field must be unique. |
start_type | Enum | Required | Indicates whether the piece begins with a deadhead, a revenue trip, or an event. 0 - Deadhead 1 - Trip 2 - Event |
start_trip_id | ID referencing deadheads.deadhead_id or trips.trip_id | Required | Identifies the deadhead or trip with which the piece begins. |
start_trip_position | Non-negative Integer referencing deadhead_times.location_sequence or stop_times.stop_sequence | Optional | Identifies the first operational location or stop to be serviced in the first trip of the piece. This field should only be filled out if the piece does not begin at the first stop of the start trip. |
end_type | Enum | Required | Indicates whether the piece ends with a deadhead, a revenue trip, or an event. 0 - Deadhead 1 - Trip 2 - Event |
end_trip_id | ID referencing deadheads.deadhead_id or trips.trip_id | Required | Identifies the deadhead or trip with which the piece ends. |
end_trip_position | Non-negative Integer referencing deadhead_times.location_sequence or stop_times.stop_sequence | Optional | Identifies the last operational location or stop to be serviced in the last trip of the piece. This field should only be filled out if the piece does not end at the last stop of the end trip. |
run_events.txt ¶
Field Name | Type | Required | Description |
---|---|---|---|
run_event_id | ID | Required | Identifies a run event. |
piece_id | ID referencing runs_pieces.piece_id | Required | Identifies the piece during which the run event takes place. |
event_type | Enum | Required | Indicates which event is scheduled in this entry. 0 - Report Time 1 - Pre-Trip Activity 2 - Post-Trip Activity 3 - Fueling 4 - Break 5 - Availability 6 - Activity 7 - Other |
event_name | String | Optional | The name for the event that is being used. |
event_time | Time | Required | The time at which the event begins. |
event_duration | Non-negative Integer | Required | The scheduled duration of the event from the event_time in seconds. |
event_from_location_type | Enum | Optional | Indicates whether the event is scheduled to begin at an operational location or a stop. 0 - Operational Location 1 - Stop |
event_from_location_id | ID referencing ops_locations.ops_location_id or stops.stop_id | Optional | Identifies the operational location or stop at which the event is scheduled to begin. |
event_to_location_type | Enum | Optional | Indicates whether the event is scheduled to end at an operational location or a stop. 0 - Operational Location 1 - Stop |
event_to_location_id | ID referencing ops_locations.ops_location_id or stops.stop_id | Optional | Identifies the operational location or stop at which the event is scheduled to end. |