Add conditionally required for alert

[gcamp]

Without at least one effect, header_text or description_text the alert doesn't have semantic value. At least one of these fields should be provided in addition to informed_entity.

Also fixes the error where header_text and description_text were Required even if only optional in the .proto.

[barbeau]

Also fixes the error where header_text and description_text were Required even if only optional in the .proto.

The header and description text were an intentional change to "Required" as part of the GTFS-realtime v2 semantic overhaul (see #64, https://medium.com/@sjbarbeau/whats-new-in-gtfs-realtime-v2-0-cd45e6a861e9) to ensure that all alerts had a human-readable description, considering that the docs say elsewhere:

Delays and cancellations of individual trips should usually be communicated using Trip updates

Are there other case you're seeing where human-readable text isn't needed? Or are trip cancellations the main case you're thinking of?

Without at least one effect, header_text or description_text the alert doesn't have semantic value. At least one of these fields should be provided in addition to informed_entity.

@gcamp Assuming we leave header and description text as required, the question here would then be if effect should be required. Do you have any data on the number of agencies with alerts feeds that are or aren't providing effect in alerts?

[gcamp]

SIGNIFICANT_DELAYS, REDUCED_SERVICE are still useful alerts even if Trip Updates will contain the updates for relevant trips. i.e. you still want to have an alert to mention that to the user.

I could also see STOP_MOVED and DETOUR be valid effect without text if the informed_entity are correctly set to stops. Most agencies I've seen anyway put "Stop moved for stop 5555 on corner of X and Y", which doesn't add anything to the alert.

I'm also open to have at least one text (either description_text or header_text) provided without taking into account effect. However having both required is not how most agencies use the text fields, they often provide one or the other.

Best case scenario is to have both texts (and that would be perfect for us as consumer), but I don't think it's realistic. I feel the spec should only avoid things that really doesn't make sense, even if there's a best practice to provide both text fields.

[barbeau]

SIGNIFICANT_DELAYS, REDUCED_SERVICE are still useful alerts even if Trip Updates will contain the updates for relevant trips. i.e. you still want to have an alert to mention that to the user.

I agree. Generally, the interactions between TripUpdates and Alerts are not well-defined at this point. My preference would be to tackle this change along with a larger effort to reconcile the two, and do this in a data-driven manner to look at actual use cases today. And, to understand why both Alert text fields aren't being populated by agencies - is this a tool limitation for publishing alerts, or is the additional text just not seen as necessary by the agency? Does the agency understand how this text appears in consumer apps?

[gcamp]

 Generally, the interactions between TripUpdates and Alerts are not well-defined at this point.

I agree, that need to defined more clearly. Especially if alerts are expected to change behaviour of apps/trip planner more than just display.

 My preference would be to tackle this change along with a larger effort to reconcile the two, and do this in a data-driven manner to look at actual use cases today.

Would be the perfect outcome but, I would put word of caution of trying to do too much at the same time. The current system works in general, I'd try to improve more than change it significantly.

 And, to understand why both Alert text fields aren't being populated by agencies - is this a tool limitation for publishing alerts, or is the additional text just not seen as necessary by the agency? Does the agency understand how this text appears in consumer apps?

Specifically, most often we've seen agencies only put the description_text. The header text can be deduced from the effect, which I feel is fine. Some agencies also use twitter as a baseline for their alerts, and thus only have 280 (and often 140 still) characters to entry text without a title.

[barbeau]

@gcamp I'm circling back to this. In your opinion, are the changes in this pull request predicated on the fact that alerts are intended to a) modify the network (e.g., prevent a stop from showing up in a trip plan), not b) just be human-readable descriptions shown to the user?

For example:

• A stop closure alert with a) behavior would result in a trip plan that does not include that closed stop
• A stop closure alert with b) behavior would result in a trip plan that included the closed stop, but a text warning being shown to the user that the stop is closed. It would be up to the user to view other trip options not including that closed stop.

From my read the GTFS-rt spec isn't currently clear if expected consumer behavior is a) or b), and I'd like to resolve that. From talking with others, it seems like b) is relatively widely used but not clearly documented in the spec.

If your answer to the initial question is yes, we should better define this expected alert behavior in this PR or another before adopting these changes. If your answer to the initial question is no, then I think we can pursue this PR independently of the larger a)/b) issue.

What are your opinions on this?

[gcamp]

@barbeau These changes are not predicated on the fact that alerts are for modifying the network. My understanding is also that it was never defined clearly but most use it to display human-readable information.

So the answer is no, I think is this still necessary without talking about the alert feed effect on the consumer.

My two main reasons for these changes

1. We see a lot of feeds that don't respect these 'Required' fields. We can push to make sure consumer are compliant but I think it's better to make the spec flexible if it doesn't hurt usability.
2. IMO the spec should make sure the data is semantically correct, not that it respect all best practice. In this case, I agree that both title and description should be required as a best practice. But the question I asked myself was "What is the minimum values that needs to be defined to have a semantically correct alert". The answer was define at least one of effect, header_text or description_text.

For example, I can clearly see an agency putting "Stop X is cancelled" as title without putting a description. That should still be a valid alert, since they might not have more information than this. Otherwise, I can see the agency putting the same text in both title and description, which is arguably worst but would respect the current spec.

[gcamp]

Update on this, seems that producers are really adhering to the spec, so my proposition is not really relevant anymore.

Here are the alerts feeds we support that either have alerts with either no alerts or no description. Note that they all have gtfs-rt version of 1.

Feed Name	GTFS-rt version	has entity without header	has entity without description
Lila	1.0	true	false
Thunder Bay Transit	1.0	true	true
exo (Trains, RTM ex-AMT)	1.0	false	true
ATAC	1.0	true	true
Kingston Transit	1.0	true	true
BC Transit (Nanaimo)	1.0	false	true
Calgary Transit RT	0.1	false	true
Transit Windsor	1.0	false	true
Sarnia Transit	1.0	true	true
TriMet	1	false	true