Make headsigns a recommended GTFS field

[isabelle-dr]

This issue picks up on the conversation in #461.

Context

Certain Optional files/fields are dependent on the service (e. g. timeframes.txt is for modeling fares based on time of day), whereas other files/fields can and should always be added regardless of the type of service being modeled (e. g. feed_info.txt, ). We think there is value in calling out the latter explicitly using the terms associated with the Best Practices (Recommended or Should), to promote higher-quality GTFS.

We looked at what are the most common optional features on the Mobility Database: ~1500 GTFS Static datasets across 79 countries - note that the US accounts for approx half of this, so we also looked at non-US based data. These are the 6 top represented optional features, in both cases.

feature	all data	non-US data
Shapes	84%	72%
Headsigns	82%	79%
Route Colors	73%	57%
Wheelchair Accessibility	62%	41%
Feed Information	62%	43%
Location Types	60%	46%

There is currently a PR open for recommending Shapes in the spec.

Issue

This issue is for making trips.trip_headsign recommended in the spec, given its use in production data across the globe.
Amongst the feeds that don't have headsigns, I didn't find obvious cases where it wouldn't be needed. Do we know of any?

Solution proposed

Adding the Recommended presence requirement for trip_headsign (see all presence requirements here).
This is considered a backwards-compatible change because it wouldn't change the validity of feeds that don't have headsigns. They would trigger a WARNING in the canonical validator.

[westontrillium]

The spec's description of trip_headsign reads as follows: "Text that appears on signage identifying the trip's destination to riders..."

The only concern I can think of is that sometimes a route does not have associated signage indicating trip destination/direction/etc., whether that's due to lack of vehicle/stop infrastructure features, the agency has not defined this piece of information explicitly, and/or their GTFS publisher has no agency contact to get it from. In these cases, would it be recommended for the publisher to unilaterally assign a headsign based on the limited information they have about the route (e.g., the last stop is the transit center, so one could safely assume a headsign of "Transit Center" is acceptable), or should it be left blank?

Additionally, a static "destination headsign" doesn't always make sense when publishing Flex services. How would this be handled?

[antrim]

Comments here are my own and do not represent Optibus & Trillium.

+1 to @westontrillium's comments.

Amongst the feeds that don't have headsigns, I didn't find obvious cases where it wouldn't be needed. Do we know of any? (@isabelle-dr )

Yes, there are many. One example is Arcata, CA's (AMRTS) Red Route:
https://hta.org/agencies/arcata-and-mad-river/?route=red
Like many other loop routes, the vehicle headsign shows "Red Route". There is no direction of travel information.

Many GTFS applications assume a directional headsign. Not to pick on Apple Maps, but here is how the AMRTS Red Route shows in Apple Maps (no trip_headsign provided):

https://maps.apple.com/?daddr=Murphy's Sunnybrae Market’s Work, 785 Bayside Rd, Arcata, CA 95521, United States&dirflg=r&saddr=Janes Rd %26 11th St Stop, Arcata, CA, United States

"Toward Transit Center" isn't meaningful for a rider.

I suspect that Apple Maps is generating a headsign based on the last stop in the trip.

So, at least with loop routes, recommending to provide a headsign might cause feed publishers to insert some junk data.

Anecdote: At Trillium, feed consumers would occasionally require us to include trip_headsign when there wasn't a good value to provide. For loop routes sometimes we'd just include something like "Loop Route". The display wasn't always perfect, but at least it gave riders a better idea of how the service operated.

I suggest revisiting the broader trip_headsign recommendations in the Best Practices before making trip_headsign recommended. https://gtfs.org/schedule/best-practices/#tripstxt

[evansiroky]

+1 to both @westontrillium and @antrim. I think it would be helpful to have a way to share in the data (possibly as a new column in the trips.txt file) that the vehicles associated with some trips do not have headsigns. Once there is that ability, I would be in favor of recommending that the trips.has_headsign (or equivalent column) always be filled out and if it is marked as true that the trips.trip_headisgn be conditionally required.

[westontrillium]

@evansiroky The additional has_headsign field is an interesting solution in being able to express that a trip positively does not have a headsign as opposed to missing data. I don't think, however, that we could retroactively make the existing trip_headsign required on the condition of a new, optional field, as that would not be backwards compatible. "Conditionally recommended," though, there's an idea ("recommended if trips.has_headsign=true").

[westontrillium]

Just brainstorming out loud... One issue with has_headsign is that a true value + presence of trip_headsign would be redundant. If trip_headsign is defined, it intrinsically means that the trip has a headsign, so the only meaningful use of has_headsign is when =false. But how meaningful is that to riders?

[skinkie]

Given that the use case is presented that there are trips without headsigns, it should not become mandatory. The question is how mobiliydata envisions how recommended (eventually) would become required. If that would never happen, recommended isn't a problem.

[antrim]

Do we have some precedents to work from here?

Could trip_headsign become a recommended field, while still allowing blank values?
This could still flag a warning in the validator, but the message should be explicit that blank values are allowed.

@isabelle-dr How many feeds have a combination of empty and full text strings for trip_headsign? That could indicate intentional blank values.

[isabelle-dr]

Thank you for providing your thoughts!

Could trip_headsign become a recommended field, while still allowing blank values?
This could still flag a warning in the validator, but the message should be explicit that blank values are allowed.

@antrim We try to avoid "you can ignore this warning if..." as much as possible because we want to make it possible for datasets to be free of warnings. The validator can be used in RFPs or compliance checks against regulation, so this would be a risk to have producers filling incorrect data to avoid needing to explain why a particular warning is irrelevant here.

That being said, the spec contains instances of must/required and recommended/should that can't easily be checked by the validator and would have to be checked by other means, and I think this is definitely better than nothing. For example:

• In stop_times.stop_id: All stops serviced during a trip must have a record in stop_times.txt.
• in pathways.min_width: This field is recommended if the minimum width is less than 1 meter.
• In agency.agency_email: This email address should be a direct contact point where transit riders can reach a customer service representative at the agency.

So for headsigns, I think a statement that looks like this would be acceptable:

This field is recommended for all services with headsign text displayed on the vehicle which may be used to distinguish amongst trips in a route.

We could also potentially add the existing Best practice statement as well (source):

Values matching route_short_name and route_long_name should not be used in trip_headsign or stop_headsign fields.

[isabelle-dr]

@westontrillium

I don't think, however, that we could retroactively make the existing trip_headsign required on the condition of a new, optional field, as that would not be backwards compatible.

I think this would be backwards compatible, and adding a recommended trips.has_headsign field is an interesting way to say "headsign information is recommended in GTFS".
But the simple spec statement might lead to a good enough outcome with less complexity added to the spec.

[westontrillium]

I'd support adding the language proposed by @isabelle-dr: "This field is recommended for all services with headsign text displayed on the vehicle which may be used to distinguish amongst trips in a route."