[GTFS-Fares v2] Add rule_priority to fare_leg_rules.txt

[tzujenchanmbd]

Context

The rule_priority field is originally derived from Ito World's "override" proposal, it is used to simply represent cases when some matching rules need to take precedence over other matching rules.

During the discussion of the rule_priority proposal, the working group identified issues regarding backward compatibility and how to align with the existing empty semantics(“anything except…”) of network_id, from_area_id, and to_area_id. In the meeting on August 22nd, the working group reached a consensus on the need for a rule_priority field and the mechanism for changing empty semantics. It was agreed that this mechanism should not cause breaking changes for feed producers. After this discussion, we have also drafted this spec modeling proposal.

In the meeting on September 26th, there was agreement on moving forward with Option 1 in the spec modeling proposal for changing empty semantics (rule_priority field existence as a trigger)

Changes in this PR

• Add rule_priority field in fare_leg_rules.txt
• Modify fare_leg_rules file description to indicate the difference between rule_priority and existing empty semantics
• Modify fare_leg_rules.network_id, fare_leg_rules.from_area_id, fare_leg_rules.to_area_id field description to indicate the difference between rule_priority and existing empty semantics

This PR uses the existence of the rule_priority field as a trigger to change existing empty semantics.

What is not included in this PR

• scope or rule_priority_scope field
• rule_priority in fare_transfer_rules.txt

The working group agrees that we can consider introducing rule_priority for fare_transfer_rules after gaining a better understanding of the mechanism behind fare_transfer_rules.

Validator rule

We noticed that producers might directly include field headers (without any values), but failed to realize this could pose in altering the existing empty semantics. Therefore, the description of rule_priority included the sentence "If the rule_priority field exists, it should not have all records entirely empty." When the rule_priority field exists, but all records across the files are empty, the validator will trigger a warning.

For previous discussions, please see issue#383 and working group meeting minutes.

Please go through the changes and feel free to share your thoughts/questions here.

[westontrillium]

In the following case:

fare_leg_rules.txt

leg_group_id	network_id	fare_product_id	rule_priority
a	route_1	one-way_general	3
a	route_1	20dollar_card	2
a	route_1	monthly_pass	1

All fare leg rules are equally valid for the same trip, but different fare products are available. Does adding rule_priority then just determine display order, or would a consumer only be expected to display the highest priority option (one-way_general, in this case)?

[tzujenchanmbd]

@westontrillium To my understanding, rule_priority serves to implement "override" functionality rather than to "sort" search results. In other words, consumers will only be expected to display the highest priority option. In the example above, since "all fare leg rules are equally valid for the same trip," these three fare products should be modeled with the same rule_priority.

rule_priority can be used in scenarios like the following: From 11:00 to 15:00, there is cheaper fares available, and the all-day fare can still be used during this time frame. However, from the riders' perspective, when I ride at 11:30, the trip planner should not present the more expensive all-day fare. Therefore, fares from 11:00 to 15:00 have a higher priority and "override" the all-day fare.

leg_group_id	fare_product	from_timeframe_group_id	to_timeframe_group_id	rule_priority
1	all_day_single
1	offpeak_special_single	11_to_15		1

---

Regarding how to present all candidate fares on the frontend (e.g., sorting, menus, defaults, etc.), I am inclined to leave this up to consumers to decide.

Fwiw, regarding the expectations between producers and consumers about "what fares should be included in the candidate fares for presentation (sorting, menu, etc)," I've drafted the "expected outcome" section in this doc to share my thoughts.

---

(Also curious about what you thoughts on this @npaun @halbertram @bdferris-v2 @skinkie)

[bdferris-v2]

+1 to @tzujenchanmbd 's interpretation.

[npaun]

I agree with @tzujenchanmbd's explanation as well. I'll add an example of when rule priority can really simplify things:

network_id	from_area_id	to_area_id	fare_product_id	rule_priority
airport-lines	airport		airport-pass	2
airport-lines		airport	airport-pass	2
			regular-ticket	1

In Denver, taking the A line or an airport express bus to the airport requires an additional charge. All other travel is at regular rate. Rule priority saves us the work of exhaustively defining cases like "a local route to the airport is regular rate", "an airport route to a destination outside the airport is regular rate", and so on.

[halbertram]

Also +1 to @tzujenchanmbd 's interpretation. It might be worth adding stronger wording that all but the highest rule(s) will be discarded from the match set and therefore not considered for display, transfers etc.

[halbertram]

Additionally, do we need to make clear that this effectively makes fare_product_id a predicate where it might not be otherwise considered as one? Ie in a version of @npaun 's airport example where the special airport fares only applied to contactless, we presumably don't want to regard either of the priority 2 rules as matched unless those products have a line that matches a contactless fare_media_id.

Or are there other thoughts of how it should work in those cases?

[bdferris-v2]

@halbertram I would not have considered fare_product_id a predicate in this case. Namely, if the airport bus only needs special pricing when paying with one media vs another, then I think you'd have to specify both those medias for the fare product associated with the higher rule_priority rule.

Put another way, I don't believe rule_priority allows a rule override for just one media type, per my interpretation. I recognize that this might make certain cases more verbose when you only need to override the price for a particular media type, but I think the implications of making fare_product_id a predicate would come with its own complications.

[bdferris-v2]

If the rule_priority field exists, it should not have all records entirely empty.

If a feed provider just wanted to add an empty rule_priority column to turn off empty-value semantics for the feed, would that be acceptable?

[npaun]

I think this should be allowed.

[tzujenchanmbd]

Removed the sentence "If the rule_priority field exists, it should not have all records entirely empty."
0d3a8a5

[tzujenchanmbd]

Hello,

We have at least one producer: Ito. They have shared their dataset in this file, which is part of a private feed.
We have at least one consumer: Apple Maps. Please see the screenshot below for the same dataset.

As per the GTFS amendment process, the requirements to open a vote are met.
We are opening a vote for adding rule_priority.

Voting ends on 2024-05-20 at 23:59:59 UTC.

[bdferris-v2]

+1 from Google

I can confirm that we are using this extension as well.

[saraemarcus]

+1 from Apple

[npaun]

+1 from Transit

[halbertram]

+1 from Ito

[drewda]

+1 from Interline

[tzujenchanmbd]

The vote passed on 2024-05-20 at 23:59:59 UTC.

5 votes in favour and no votes against.

The votes came from:
Google (@bdferris-v2)
Apple (@saraemarcus)
Transit (@npaun)
Ito (@halbertram)
Interline (@drewda)

Thanks to everyone who contributed and voted!