Problem

As originally mentioned in #375, MobilityData’s heard a need to merge best practices into the spec to increase their visibility to producers and reduce confusion between the two documents. We’ve been exploring what a good starting “release” or iteration would look like to begin this work. Based on feedback in #375 and some other discussions, it looks like the one key initial challenge to solve is reconciling places in the best practices and spec where their advice conflicts.

Some examples:

• feed_info.txt is Optional in the spec, but recommended in all cases in best practices.
• agency_id is Optional if there is only one transit agency in the spec, but always recommended in the best practices

Solution

Adding a Recommended and Conditionally Recommended presence in the spec that conforms to RFC conventions. This would make it possible to clearly state that a field or file is not required, but adding it is a best practice that should be considered. Making it immediately obvious that a file or field is recommended in the spec reduces confusion, while preserving backwards compatibility.

This change would not affect validity or the quality evaluation of the dataset according to the Canonical Validator, since the best practices are already warnings in the validator. Any recommended field or file would generate a warning in the validator.

Recommended Scope

MobilityData has done an initial review of all places in the spec and best practices where they offer contradictory advice on when to add a file or field.

All conflicting best practices that don’t require adopting a new field into the spec relate to

• feed_info.txt file and fields
• route_short_name in routes.txt
• agency_id in routes.txt, agency.txt, and fare_attributes.txt
• timepoint in stop_times.txt
• block_id in trips.txt
• Looping or inlining routes
  • shape_dist_traveled in stop_times.txt
  • shape_dist_traveled in shapes.txt
  • direction_id in trips.txt

After the associated PR is adopted, MobilityData will open a PR on https://github.com/MobilityData/GTFS_Schedule_Best-Practices so that all best practices that have been reconciled + adopted into the spec are removed from the best practices repo.

It would be helpful to get feedback on:

• The scope itself: is there any best practice here that there isn’t consensus on and ought to be clarified further before it’s added to the spec?
• If there are particular best practices in this list that are high value to trip planners and regulators to reconcile
• Any recommendations for revising language related to the best practices on looping or inlining routes

Alternatives Considered

• First iteration focused on adding dataset publishing guidelines (Move Dataset Publishing and General Practices from Best Practices to the spec #375). There seems to be a need to clean up discrepancies first before there would be viable buy-in to adding new shoulds and sections to the spec. This is a viable phase 2.
• Status quo: does not resolve need for a better spec experience for producers