Add cause_detail and effect_detail to Alerts

[mckenzie-maidl-ibigroup]

Background:

Transit agencies use different language when describing the effect of an alert. For example, when there is a rail suspension some agencies prefer saying 'bus bridge' while others prefer 'shuttle'. As another example, some agencies use the spelling ‘cancellation’ while others use ‘cancelation’ to describe trip or service cancellations. In addition, transit agencies may require more effects than those defined in the GTFS-realtime specification to describe the impact of their alerts. The specification currently allows for 12 enum values that correspond with different effects (see here). However, each of these values may correspond with more than one effect used by an agency. For example, a stop closure, suspension, and trip cancellation may all map to the NO_SERVICE effect in the specification.

Similarly, an agency may use more causes than those defined in the GTFS-realtime specification for the Cause field (see here). For example, causes like a fire, disabled bus, or mechanical issue could all correspond to the TECHNICAL_PROBLEM cause in the specification.

These limitations may keep transit agencies from being able to programmatically create alerts between two systems. For example, to automatically create alerts in an alert management system, causes and effects would need to be restricted to a one-to-one relationship between those used to describe alerts and those in the GTFS-realtime specification. These limitations also prevent consumers from using more granular effect and cause names when displaying or grouping alerts. For example, we have worked with transit agencies who prefer prominently showing "Stop Closure" for an alert on their website rather than "No Service" as would be communicated by the existing effect field.

Alternatives:

Summary of alternative options, and why they are insufficient:

1. Add new enum values to cause and effect in the GTFS-realtime specification.

   1. This still limits data producers to a specific set of causes and effects, and as noted above agencies each use specific language when communicating to customers. Also, the timeline for proposing, debating, and voting on new enum values (and the chance that new enum values will not be unanimously approved) is a barrier to this option.

2. Use existing effect options plus the collection of selected affected entities to determine a more granular effect than allowed by existing enums.

   1. For example, a route-direction-trip level NO_SERVICE alert is most likely a trip cancellation.
   2. More than one effect may correspond to the same effect/affected entity combination. For example, a route-direction-stop DETOUR alert may be either a detour or a snow route.

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[skinkie]

I really wonder when people start to see that these additions virtually 1 to 1 mimic SIRI...

[gcamp]

We have similar value in our backend so this makes sense to me. Should there be a maximum length? It's the type of field that if it's entirely freeform consumer won't be able to use without validation.

[lauramatson]

We produce these fields and also consume/use them in our displays of alerts. We are keen to see these fields added officially to facilitate communication between the system Operations uses to manage disruptions and the system we use to create customer-facing alerts. Thanks to IBI for putting this together.

[mckenzie-maidl-ibigroup]

We have similar value in our backend so this makes sense to me. Should there be a maximum length? It's the type of field that if it's entirely freeform consumer won't be able to use without validation.

We are open to this suggestion. Note however that for other translated strings in the spec (e.g., header_text or description_text) there are no set max lengths. We would be interested in hearing what other consumers think.

[jmburge]

As a producer we have been asked for extensions to the cause/effect values that are presented. This would give us some flexibility to extend without much difficulty in messing up multiple consumers. What additional information would be needed to move this along?

[mckenzie-maidl-ibigroup]

@gcamp Our preference would be to not require a max length to follow precedence. Are you okay moving ahead without this? If yes, it seems like this is the only open question, and we can call a vote to add these as experimental fields once we are all on the same page. Anyone else on this thread - thoughts about this question/are there any others we should discuss?

[mckenzie-maidl-ibigroup]

This pull request has been open for more than one week, so I am calling for a vote. Note that this is for the adoption of effect_detail and cause_detail as experimental fields.

Please vote with a +1 (for) or -1 (against) in the comments. Voting ends on 2022-07-22 at 23:59:59 UTC.

Thanks
Kenzie

[skinkie]

+1 (OpenGeo)

[leonardehrenfried]

@gcamp Our preference would be to not require a max length to follow precedence. Are you okay moving ahead without this? If yes, it seems like this is the only open question, and we can call a vote to add these as experimental fields once we are all on the same page. Anyone else on this thread - thoughts about this question/are there any others we should discuss?

As a consumer of RT feeds (OTP developer) I'm also in favour of not imposing an arbitrary limit. Of course there is some technical limit at which things become slow but if you put a, say, 10MB alert string in your GTFS-RT feed you probably have other problems, too.

[gcamp]

+1 Transit

[lauramatson]

+1 Metro Transit (Minneapolis/St. Paul, Minnesota)

[mckenzie-maidl-ibigroup]

Thanks all for participating! The vote ended on Friday, July 22 at 23:59:59 UTC with a unanimous consensus of 3 'yes' votes from OpenGeo (@skinkie), Transit (@gcamp), and Metro Transit (@lauramatson).

As per the specification amendment process, this proposal is now accepted!