Skip to content

[GTFS-Fares v2] Add networks.txt & route_networks.txt #405

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tzujenchanmbd merged 5 commits into from
Nov 28, 2023
Merged

[GTFS-Fares v2] Add networks.txt & route_networks.txt #405

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
ba95dca
Add networks.txt & route_networks.txt
tzujenchanmbd Oct 9, 2023
6016f23
Modify presence of routes.network_id
tzujenchanmbd Oct 9, 2023
5bbcd8b
Modify fare_leg_rules.network_id
tzujenchanmbd Oct 9, 2023
8664074
Modify primary key of route_networks.txt
tzujenchanmbd Nov 21, 2023
f191923
Revise link
tzujenchanmbd Nov 22, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 32 additions & 2 deletions gtfs/spec/en/reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,8 @@ This document defines the format and structure of the files that comprise a GTFS
- [fare\_transfer\_rules.txt](#fare_transfer_rulestxt)
- [areas.txt](#areastxt)
- [stop_areas.txt](#stop_areastxt)
- [networks.txt](#networkstxt)
- [route_networks.txt](#route_networkstxt)
- [shapes.txt](#shapestxt)
- [frequencies.txt](#frequenciestxt)
- [transfers.txt](#transferstxt)
Expand Down Expand Up @@ -119,6 +121,8 @@ This specification defines the following files:
| [fare_transfer_rules.txt](#fare_transfer_rulestxt) | Optional | Fare rules for transfers between legs of travel.<br><br>Along with [fare_leg_rules.txt](#fare_leg_rulestxt), file [fare_transfer_rules.txt](#fare_transfer_rulestxt) provides a more detailed method for modeling fare structures. As such, the use of [fare_transfer_rules.txt](#fare_transfer_rulestxt) is entirely separate from files [fare_attributes.txt](#fare_attributestxt) and [fare_rules.txt](#fare_rulestxt). |
| [areas.txt](#areastxt) | Optional | Area grouping of locations. |
| [stop_areas.txt](#stop_areastxt) | Optional | Rules to assign stops to areas. |
| [networks.txt](#networkstxt) | **Conditionally Forbidden** | Network grouping of routes.<br><br>Conditionally Forbidden:<br>- **Forbidden** if `routes.network_id` field exists.<br>- Optional otherwise. |
Copy link

@ferranmanya ferranmanya Aug 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why would networks.txt be forbidden when the relation between networks an routes is specified in routes.txt? The conditionally forbidden relation this pull request intends is only between routes.network_id and route_networks.txt

Copy link

@sberkley sberkley Aug 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ferranmanya I agree and was recently confused by this as well. As currently written here and validated by MobilityData's validator (https://github.com/MobilityData/gtfs-validator/pull/1671/files), networks can't both be named (requires use of networks.txt) and be linked to routes (requires use of routes.network_id or route_networks.txt).

Copy link
Collaborator Author

@tzujenchanmbd tzujenchanmbd Aug 15, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ferranmanya @sberkley
Agree this could be a bit confusing... Here’s some background information:

routes.network_id, networks.txt, and route_networks.txt were not all introduced into GTFS at the same time. routes.network_id was added to GTFS in May 2022 through PR#286. At that time, there was no dedicated networks.txt table for networks (“non-normalized”), and most producers simply defined networks using routes.network_id.

In 2023, the community raised the need to handle fares data separately—which is what this PR addresses—and that led to the addition of both route_networks.txt and networks.txt. With networks.txt, networks became normalized and have a network_id primary key.

After introducing networks.txt, what if it also became the primary table referenced by routes.network_id? This would mean the validator must check the references between the two tables, which would be a breaking change for producers who had previously only provided routes.network_id. And GTFS currently maintains strict backward compatibility for producers. We also want to avoid the confusion that could result from mixing old and new approaches. In a mixed scenario, it can become unclear which definition of a network should be treated as authoritative...

This is why the current validator rule exists. Its meaning is essentially: either use the previous routes.network_id alone, or use the new [route_networks.txt + networks.txt] combination to define networks.

| [route_networks.txt](#route_networkstxt) | **Conditionally Forbidden** | Rules to assign routes to networks.<br><br>Conditionally Forbidden:<br>- **Forbidden** if `routes.network_id` field exists.<br>- Optional otherwise. |
| [shapes.txt](#shapestxt) | Optional | Rules for mapping vehicle travel paths, sometimes referred to as route alignments. |
| [frequencies.txt](#frequenciestxt) | Optional | Headway (time between trips) for headway-based service or a compressed representation of fixed-schedule service. |
| [transfers.txt](#transferstxt) | Optional | Rules for making connections at transfer points between routes. |
Expand Down Expand Up @@ -210,7 +214,7 @@ Primary key (`route_id`)
| `route_sort_order` | Non-negative integer | Optional | Orders the routes in a way which is ideal for presentation to customers. Routes with smaller `route_sort_order` values should be displayed first. |
| `continuous_pickup` | Enum | Optional | Indicates that the rider can board the transit vehicle at any point along the vehicle’s travel path as described by `shapes.txt`, on every trip of the route. Valid options are: <br><br>`0` - Continuous stopping pickup. <br>`1` or empty - No continuous stopping pickup. <br>`2` - Must phone agency to arrange continuous stopping pickup. <br>`3` - Must coordinate with driver to arrange continuous stopping pickup. <br><br>Values for `routes.continuous_pickup` may be overridden by defining values in `stop_times.continuous_pickup` for specific `stop_time`s along the route. |
| `continuous_drop_off` | Enum | Optional | Indicates that the rider can alight from the transit vehicle at any point along the vehicle’s travel path as described by `shapes.txt`, on every trip of the route. Valid options are: <br><br>`0` - Continuous stopping drop off. <br>`1` or empty - No continuous stopping drop off. <br>`2` - Must phone agency to arrange continuous stopping drop off. <br>`3` - Must coordinate with driver to arrange continuous stopping drop off. <br><br>Values for `routes.continuous_drop_off` may be overridden by defining values in `stop_times.continuous_drop_off` for specific `stop_time`s along the route. |
| `network_id` | ID | Optional | Identifies a group of routes. Multiple rows in [routes.txt](#routestxt) may have the same `network_id`.|
| `network_id` | ID | **Conditionally Forbidden** | Identifies a group of routes. Multiple rows in [routes.txt](#routestxt) may have the same `network_id`.<br><br>Conditionally Forbidden:<br>- **Forbidden** if `route_networks.txt` file exists.<br>- Optional otherwise.

### trips.txt

Expand Down Expand Up @@ -436,7 +440,7 @@ To process the cost of a leg:
| Field Name | Type | Presence | Description |
| ------ | ------ | ------ | ------ |
| `leg_group_id` | ID | Optional | Identifies a group of entries in [fare_leg_rules.txt](#fare_leg_rulestxt).<br><br> Used to describe fare transfer rules between `fare_transfer_rules.from_leg_group_id` and `fare_transfer_rules.to_leg_group_id`.<br><br>Multiple entries in [fare_leg_rules.txt](#fare_leg_rulestxt) may belong to the same `fare_leg_rules.leg_group_id`.<br><br>The same entry in [fare_leg_rules.txt](#fare_leg_rulestxt) (not including `fare_leg_rules.leg_group_id`) must not belong to multiple `fare_leg_rules.leg_group_id`.|
| `network_id` | Foreign ID referencing `routes.network_id` | Optional | Identifies a route network that applies for the fare leg rule.<br><br>If there are no matching `fare_leg_rules.network_id` values to the `network_id` being filtered, empty `fare_leg_rules.network_id` will be matched by default.<br><br> An empty entry in `fare_leg_rules.network_id` corresponds to all networks defined in `routes.txt` excluding the ones listed under `fare_leg_rules.network_id` |
| `network_id` | Foreign ID referencing `routes.network_id` or `networks.network_id`| Optional | Identifies a route network that applies for the fare leg rule.<br><br>If there are no matching `fare_leg_rules.network_id` values to the `network_id` being filtered, empty `fare_leg_rules.network_id` will be matched by default.<br><br> An empty entry in `fare_leg_rules.network_id` corresponds to all networks defined in `routes.txt` or `networks.txt` excluding the ones listed under `fare_leg_rules.network_id` |
| `from_area_id` | Foreign ID referencing `areas.area_id` | Optional | Identifies a departure area.<br><br>If there are no matching `fare_leg_rules.from_area_id` values to the `area_id` being filtered, empty `fare_leg_rules.from_area_id` will be matched by default. <br><br>An empty entry in `fare_leg_rules.from_area_id` corresponds to all areas defined in `areas.area_id` excluding the ones listed under `fare_leg_rules.from_area_id` |
| `to_area_id` | Foreign ID referencing `areas.area_id` | Optional | Identifies an arrival area.<br><br>If there are no matching `fare_leg_rules.to_area_id` values to the `area_id` being filtered, empty `fare_leg_rules.to_area_id` will be matched by default.<br><br> An empty entry in `fare_leg_rules.to_area_id` corresponds to all areas defined in `areas.area_id` excluding the ones listed under `fare_leg_rules.to_area_id` |
| `from_timeframe_group_id` | Foreign ID referencing `timeframes.timeframe_group_id` | Optional | Defines the timeframe for the fare validation event at the start of the fare leg.<br><br>The “start time” of the fare leg is the time at which the event is scheduled to occur. For example, the time could be the scheduled departure time of a bus at the start of a fare leg where the rider boards and validates their fare. For the rule matching semantics below, the start time is computed in local time, as determined by [Local Time Semantics](#localtimesemantics) of [timeframes.txt](#timeframestxt). The stop or station of the fare leg’s departure event should be used for timezone resolution, where appropriate.<br><br>For a fare leg rule that specifies a `from_timeframe_group_id`, that rule will match a particular leg if there exists at least one record in `timeframes.txt` where all of the following conditions are true<br>- The value of `timeframe_group_id` is equal to the `from_timeframe_group_id` value.<br>- The set of days identified by the record’s `service_id` contains the “current day” of the fare leg’s start time.<br>- The “time-of-day” of the fare leg's start time is greater than or equal to the record’s `timeframes.start_time` value and less than the `timeframes.end_time` value.<br><br>An empty `fare_leg_rules.from_timeframe_group_id` indicates that the start time of the leg does not affect the matching of this rule. |
Expand Down Expand Up @@ -505,6 +509,32 @@ Assigns stops from [stops.txt](#stopstxt) to areas.
| `area_id` | Foreign ID referencing `areas.area_id` | **Required** | Identifies an area to which one or multiple `stop_id`s belong. The same `stop_id` may be defined in many `area_id`s. |
| `stop_id` | Foreign ID referencing `stops.stop_id` | **Required** | Identifies a stop. If a station (i.e. a stop with `stops.location_type=1`) is defined in this field, it is assumed that all of its platforms (i.e. all stops with `stops.location_type=0` that have this station defined as `stops.parent_station`) are part of the same area. This behavior can be overridden by assigning platforms to other areas. |

### networks.txt

File: **Conditionally Forbidden**

Primary key (`network_id`)

Defines network identifiers that apply for fare leg rules. Forbidden if `routes.network_id` field exists.

| Field Name | Type | Presence | Description |
| ------ | ------ | ------ | ------ |
| `network_id` | Unique ID | **Required** | Identifies a network. Must be unique in [networks.txt](#networkstxt). |
| `network_name` | Text | **Optional** | The name of the network that apply for fare leg rules, as used by the local agency and its riders.

### route_networks.txt

File: **Conditionally Forbidden**

Primary key (`route_id`)

Assigns routes from [routes.txt](#routestxt) to networks. Forbidden if `routes.network_id` field exists.

| Field Name | Type | Presence | Description |
| ------ | ------ | ------ | ------ |
| `network_id` | Foreign ID referencing `networks.network_id` | **Required** | Identifies a network to which one or multiple `route_id`s belong. A `route_id` can only be defined in one `network_id`. |
| `route_id` | Foreign ID referencing `routes.route_id` | **Required** | Identifies a route. |

### shapes.txt

File: **Optional**
Expand Down