Add new SPECIAL_EVENT Cause to GTFS-realtime Service Alerts

[ckraatz]

Summary

Adds a new Cause called "Special Event" to GTFS-realtime Service Alerts, to fill a gap affecting many producers.

Describe the Problem

Many producers find it difficult to select a Cause from the current list in certain common situations, and we've heard complaints from customers about this.

I'm proposing to add SPECIAL_EVENT to address this. Capturing alert causes also provides more structured data, which could be used to display Alerts in certain ways on agency websites and potentially in apps.

Use Cases

SPECIAL_EVENT would be the appropriate Cause to select in the following common scenarios faced by many agencies:

• Parades and festivals
• Sporting events that shut down streets or impact traffic
• Concerts and other performances
• Farmers markets

Proposed Solution

Add SPECIAL_EVENT to the Cause list as option 13 as follows:

// Cause of this alert. If cause_detail is included, then Cause must also be included.
enum Cause {
UNKNOWN_CAUSE = 1;
OTHER_CAUSE = 2; // Not machine-representable.
TECHNICAL_PROBLEM = 3;
STRIKE = 4; // Public transit agency employees stopped working.
DEMONSTRATION = 5; // People are blocking the streets.
ACCIDENT = 6;
HOLIDAY = 7;
WEATHER = 8;
MAINTENANCE = 9;
CONSTRUCTION = 10;
POLICE_ACTIVITY = 11;
MEDICAL_EMERGENCY = 12;
SPECIAL_EVENT = 13; // A special one-time or recurring event such as a parade, festival, performance, farmers market, or sporting event.
}

Type of change

GTFS Schedule

• Functional Change
• Non-Functional Change
• Documentation Maintenance

GTFS Realtime

• Specification Change
• Specification Change (Experimental Field)

Additional Information

Discussed and supported in this Issue: #576

Proposed Discussion Period

Since this is clearly needed and will have minimal effect on producers and consumers that don't use it, I propose the 7-day voting period.

Testing Details

Testing isn't required, as this is just adding a new value to an existing core field.

• Consumer(s): n/a
• Producer(s): n/a
• Estimated Testing Period: n/a

Proposal Update Tracker

Date	Update Description
(YYYY-MM-DD)	(Brief description of the update)

Checklist

• I have read and understood the GTFS Change process.
• I have read and understood the GTFS Guiding Principles.
• I understand the Role of Advocate and the Responsibilities attached to it.
• I have signed the Contributor License Agreement (CLA).
• I have ensured that this proposal is not covered by an existing Pull Request.

[hbruch]

+1 for this addition.

In file spec/en/reference.md, SPECIAL_EVENT should be added as well, IMHO.

[skinkie]

I really do not see a benefit over OTHER_CAUSE. This is just OTHER_CAUSE with a different name.

[ckraatz]

In file spec/en/reference.md, SPECIAL_EVENT should be added as well, IMHO.

Thank you for catching that additional reference! I added the new Cause there as well.

[ckraatz]

I really do not see a benefit over OTHER_CAUSE. This is just OTHER_CAUSE with a different name.

It's certainly not OTHER_CAUSE with a different name, although if it were a 1:1 replacement that would speak to this being very sensible because that means whenever people are using OTHER_CAUSE they actually mean SPECIAL_EVENT. I don't think that's quite true, but others have commented in Issue #576 that 90%+ of OTHER_CAUSE usage is actually for SPECIAL_EVENTS.

Questioning the benefit of specificity over "Other Cause" would imply we should question having the Cause field at all. Why specify Construction, Police Activity or Weather?

I think Cause benefits riders with clues as to why a disruption is happening and how long it might go on. I recommend SimplifyTransit Alerts users include "why" in the Header field for that reason, and pushed hard for that when I was at VTA.

In our discussion someone noted that agency websites and apps can use the specificity of the Cause to display icons, words, and other UI elements that help riders distinguish between alerts.

[stevenmwhite]

While currently, this use case is captured by Other Cause, it is clearly not the same as Other Cause. Other is a catch all for unrepresented causes and this is a specific, and common, cause for delays or detours.

A separate note on process: is a producer and consumer required before a vote can be called?

[Sergiodero]

Hi @ckraatz, Sergio from MobilityData here. Thanks for opening this PR!

Could you please announce it in the GTFS-realtime mailing list? A short message letting people know that the PR is open and inviting folks to participate in the discussion would be more than enough, similar to the post you made for the related issue (#576). This will help comply with step 3 of the Specification Amendment Process.

Thanks, and let us know if you have any questions!

[Sergiodero]

A separate note on process: is a producer and consumer required before a vote can be called?

@stevenmwhite that is correct, as per step number 5 of the Specification amendment process. It's worth remining that this is a GTFS-Realtime change which is subject to this process, which at the moment is still separate from the GTFS Schedule governance.

[skinkie]

Questioning the benefit of specificity over "Other Cause" would imply we should question having the Cause field at all. Why specify Construction, Police Activity or Weather?

Because it is specific. And this proposal is as abstract as other cause.

[ckraatz]

@skinkie I see your point. I think we just have to accept that all of these Causes fall on a specific-vague continuum (Strike on the specific end, Other on the vague end, others somewhere in between). That's why I like the cause_detail and effect_detail fields - they allow agencies to give riders more specific information that will help them understand what's going on.

[ckraatz]

@Sergiodero I posted in the GTFS-realtime mailing list - thanks for the reminder of that step.

Step 5 of the amendment process says it "should" be demonstrated prior to calling for a vote, but doesn't actually "require" testing. If producers and consumers can produce and consume any other Cause on the list, they can produce and consume this Cause.

The Changes process defined here is focused on "Adding new fields to GTFS Realtime." That's the top-level heading on the page. This Pull Request wouldn't add any new fields or features, really, and it's entirely backwards compatible.

That said, we'll work on producing an Alerts feed with an active alert using the SPECIAL_EVENT cause, if folks need to see that to feel comfortable voting.

SimplifyTransit Subscriptions is also a GTFS-realtime Service Alerts consumer, but I assume we want another consumer to validate they can consume that feed without problems. @gcamp or @bdferris-v2 would Transit or Google be willing to consume that feed and confirm it generates no problems? Would your applications just ignore the added Cause?

[skinkie]

@skinkie I see your point. I think we just have to accept that all of these Causes fall on a specific-vague continuum (Strike on the specific end, Other on the vague end, others somewhere in between). That's why I like the cause_detail and effect_detail fields - they allow agencies to give riders more specific information that will help them understand what's going on.

I would support specific causes like you pointed out FESTIVAL, MARKET, and I think it would be even better to take the TPEG standard for this list: https://github.com/SIRI-CEN/SIRI/blob/master/xsd/siri_model/siri_situationReasons.xsd#L165

[ckraatz]

@skinkie those of us who help agencies publish GTFS-realtime Service Alerts need to balance how the specificity of the data actually benefits riders with pragmatic ease-of-use that leads to actual alerts. More options = harder (AKA the Paradox of Choice). Staff - often very busy dispatchers amongst our customers - get overwhelmed, make mistakes, or simply won't create alerts if we make it too hard.

I have personal experience publishing of service alerts and training others to when I managed Digital Communications for VTA. So I understand the user experience more than most (any?) of the alert tool vendors on the market. I also monitored Twitter and responded to customers during incidents.

Unless you have experience publishing alerts for an agency or selling a popular product that helps staff do that, I'd ask that you trust the insights this proposal is based on.

Personally, I think the Siri enumeration you shared goes to a level of detail I'm not sure is helpful ... bombDisposal 💣 😲, emergencyBrake, cableTheft, congestion AND heavyTraffic 🤔, vegetation 😆, lowWaterLevel AND highWaterLevel, fallenLeaves 🍂, foreignDisturbances. I'm very confident if we had hundreds of options we'd see a skyrocketing use of "unknown."

[doconnoronca]

Toronto GO Transit is entering fallen-leaves-related-delay season.

[skinkie]

Unless you have experience publishing alerts for an agency or selling a popular product that helps staff do that, I'd ask that you trust the insights this proposal is based on.

We have and in use with several Dutch agencies, open source, obviously. https://github.com/stichtingOpenGeo/openebs2

[ckraatz]

@skinkie Does that application include all of those potential causes in the UI? Do you have any stats about how many alerts per year have each of those Causes applied, including the "unknown" cause?

[skinkie]

@skinkie Does that application include all of those potential causes in the UI?

Of the national standard, yes.

Do you have any stats about how many alerts per year have each of those Causes applied, including the "unknown" cause?

Operational (vehicle, personal) and weather related are obviously in the top 3.

[felixguendling]

I'm not sure is helpful ... bombDisposal

In Germany there are thousands of bomb disposals per year (e.g. almost 3000 in a single year in the state NRW), and obviously some of them are impacting public transport operations. I would not say that having this as an alert cause is useless. It's then part of the software design to decide which alert cause is really relevant for a specific region and exclude the rest to keep the UI simple and usable.

[ckraatz]

@skinkie @felixguendling @doconnoronca I can see you feel strongly about expanding the Cause field by adopting the more specific Siri list of causes. That's a big difference from what I'm proposing here (adding one Cause), which is in direct response to a request from one of our customers.

I'd suggest that if you'd like GTFS-realtime Service Alerts to adopt all the Siri fields you could create an Issue to discuss that. I'm open to ideas, as long as the end result for agency staff is simple, pragmatic and relevant to their agency's needs. I'd suggest you also factor in the currently experimental cause_detail and effect_detail fields, which address a similar need but leaning towards customizability rather than standardization.

It's clear that the Cause field is currently a list of Categories, not specific causes. There's a valid discussion to be had about whether the data standard should have categories, specific causes, or both. And if both, should those be in one list, or multiple?

In the meantime, I hope you'll either support or at least not oppose this Pull Request (once I set up a demonstration/test). It will help agencies that have asked for it, and at least goes in the direction of adding to the list of Causes!

[skinkie]

I am against to add more vague ambiguous causes, that can perfectly fit in OTHER_CAUSE. As mentioned, for your specific examples I would support the change. Because that could also lead to something useful like icons or automatically generated text messages.

[ckraatz]

@skinkie I won't be changing the Pull Request from adding SPECIAL_EVENT to adding a different Cause or additional more specific causes because those don't respond to customer needs expressed to me and two other companies. If you're going to vote -1 I'd appreciate you doing that now and stating your actionable feedback.

@Sergiodero I'm also trying to understand better how the change process works. I noticed the change spec calls for "unanimous consensus yes with at least 3 votes." That's an oxymoron. There's no such thing as "unanimous consensus."

• "Unanimous" or "unanimity" means that every person who votes votes yes. A single no can veto the proposal, giving that person a lot of power.
• "Consensus" means there's overall agreement and is more about an organic process of conflict resolution. There's not a vote tally in consensus. Some participants consent not because they strongly support but because they don't have a strong opposition.

[skinkie]

@ckraatz while GTFS-RT is not part of the new governance (yet), I am acting in that spirit. Hence I motivate you to change your proposal for the better.

[ckraatz]

GTFS-RT is not part of the new governance (yet), I am acting in that spirit.

@Sergiodero could you help clarify how we'd apply the spirit of the new GTFS governance here?

The voting rules for GTFS-schedule governance state

Before testing, the community holds a vote to confirm unanimous consensus on the proposal. This means all participating voters must be in favor. For the vote to be valid, it must include at least five contributors, with a minimum of two Producers and two Consumers. The voting period must last at least 14 days.

1. "Unanimous consensus" is not a real thing, and is therefore impossible. It's an oxymoron, like "old news" or a "deafening silence." "Unanimous consent" and "consensus" would be real things.
2. If we followed that here, the advocate isn't allowed to test this idea until @skinkie withdraws his objection and we get more Producers and Consumers voting yes. High bar for testing!
3. There could be 38 Yes votes from 5 Consumers and 33 Producers (mostly transit agencies), but the feature cannot be tested if even one Consumer or Producer voted No.
4. Who would enforce that prohibition, and how? What would happen if a Producer and Consumer tested it?

The community holds a vote to determine whether the changes should be officially adopted. This vote follows an 80% majority rule, meaning at least 80% of votes must be in favor for it to pass. To be valid, the vote must include at least five contributors, with a minimum of two Producers and two Consumers. The voting period must last at least 14 days.

1. After testing shows it "works," the voting standard would be lowered from "unanimous" to "80% majority rule." So the advocate needs at least 4 Yes votes for every No vote?
2. Every transit agency that Produces a GTFS-realtime Service Alerts feed or consumes GTFS-realtime Service Alerts data into their website could vote. Correct?

[Sergiodero]

Thanks for raising this @ckraatz.

First, we want to clarify that the new GTFS Schedule governance and the GTFS Realtime Specification Change process are two separate processes. Since this change impacts GTFS Realtime, we have to work with the current rules that govern GTFS Realtime changes.

That said, we recognize this process is far from perfect and has many areas for improvement (including the language/terminology used, as you’ve pointed out.) Historically, though, the community has followed a consistent process that looks like the following. I’ll ask you to refrain from over-reading the wording of steps, as they’re meant to be an overview of the relevant steps, not the exact process.

1. A PR is opened and announced on the GTFS Realtime Mailing List (Which You’ve Done)
2. The community engages in a discussion period to provide feedback, which should last at least 7 days (This is our current stage).
3. After the discussion period, one Producer and one Consumer implement and test the proposal and share their results (Yet to take place)
4. After results have been shared, the advocate can call for a vote. This period lasts at least 7 days.
   1. Official adoption into the spec requires a minimum of 3 Yes (+1) votes. However, a single No (-1) vetoes the proposal.
   2. Experimental adoption has a lower threshold for approval - 80% of the votes are in favour. Then, you have 2 years to get the change officially adopted (through a unanimous vote).
   3. In any scenario, everyone is welcome to vote.

This is how the community implements the voting and change process for Realtime. Though, I invite any community members to chime in if I’m missing anything or have misrepresented the process.

There are definitely gaps and areas for improvement in this process, and there may be value in the future to consolidate them or at least bring the RT process closer to parity in terms of robustness and clarity to the new GTFS Schedule governance. But for now, they remain separate.

As for the matter of enforcement, while MobilityData plays an active role in fostering a healthy discussion space and monitoring that the community follows the rules agreed upon, any contributor is capable of speaking up if they believe the process isn't being followed correctly. In practice, the process is based on discussion and mutual accountability to maintain trust, clarity, and collaborative decision-making.

GTFS is community-driven specification, so it relies on healthy discussion where the advocate should work towards building consensus and trust rather than “win” arguments. Disagreements are natural, but we want to encourage contributors to engage constructively and respectfully so that this discussion translates into changes that deliver value for everyone using GTFS.

When discussions risk reaching a dead end, the best next step is often to bring in more voices from the community for additional input and perspective. We’d recommend that approach here to help move the discussion forward.

[ckraatz]

I shared an update about the status of this proposal with our customer who made this request initially, and she wanted me to pass along her comments.

"We asked SimplifyTransit to add Special Event because we have so many different types of festivals, events, parades, etc. and this would be such a huge help rather than using “other." We'd rather just add one broad category like "Special Event" rather than many options for specific types of events. Too many options would just make it harder for us when we're creating alerts." - Hayley Grall, Clallam Transit

[skinkie]

+0 OpenGeo, specialEvent is part of the SIRI enumeration list too, so from that point of view "look it is interoperability!" But I personally I think we should refrain from adding ambiguous things. We would implement it, if available.

[ckraatz]

+0 OpenGeo, specialEvent is part of the SIRI enumeration list too, so from that point of view "look it is interoperability!" But I personally I think we should refrain from adding ambiguous things. We would implement it, if available.

Thank you @skinkie for getting us to consensus. Having cast a +0 vote myself, I think that's a great way to express your perspective.

[etienne0101]

Thank you both for sharing your voting intentions. Just a reminder: the voting period hasn’t opened yet. @ckraatz, it’s up to you to decide when the (minimum 7 days) discussion period has been sufficient to build consensus, and then move the proposal to testing before a vote can be called.

[phil-swiftly]

Wanted to chime in on the discussion to say that Swiftly is in support of this proposal. Internally, we already produce a separate cause for special events, and have over 30 agencies that have found it useful to distinguish between special events and "other" already this year.

[jmchatton]

PVTA (a transit agency/producer) is in support of this modification.

As an agency that must accommodate numerous special events (like parades, street festivals, triathalons, etc.) throughout the year, we feel this is an important enough and frequently-used enough category that it's worth distinguishing from other_cause. For what it's worth, sometimes detours and other disruptions caused by special events can be the most impactful to the network than any other cause that's commonly used (like construction or weather). A rider in our service area, familiar with what happens during special events, may take pause and plan their journeys differently (or at least examine the nature of the disruption more closely) if they see it's caused by a special event.

We are also a Swiftly customer, and we appreciate that Swiftly has added this to their tools that we use every day for the same reasons.

[ckraatz]

sometimes detours and other disruptions caused by special events can be the most impactful to the network than any other cause that's commonly used (like construction or weather). A rider in our service area, familiar with what happens during special events, may take pause and plan their journeys differently (or at least examine the nature of the disruption more closely) if they see it's caused by a special event.

We are also a Swiftly customer, and we appreciate that Swiftly has added this to their tools that we use every day for the same reasons.

@jmchatton thanks for weighing in! You make a very good point about how riders use Cause to inform their journey planning. Another example is police activity, which can indicate the situation is far outside the agency's control and it's very hard to know when it might end.

Mentioning "event" internally or in text without tying that to the data standard doesn't reach riders in the same structured way as adding Special Event to the data standard, which will close that gap for your and your riders.

[westontrillium]

Taking the queue from @phil-swiftly's comment providing actual stats, here's some of ours for 2025 which places me pretty firmly in the camp of supporting this change:

• Of our customers who have published alerts with the existing OTHER_CAUSE cause, half have used it at least once to describe a special event (parade, festival, etc.).
• 21% of all alerts from our customers are OTHER_CAUSE.
• 38% of OTHER_CAUSE alerts could have been categorized as SPECIAL_EVENT if it existed (8% of total alerts)
• If SPECIAL_EVENT existed, it would be the 4th most commonly used cause, redistributing usage to:
  • CONSTRUCTION: 31%
  • UNKNOWN_CAUSE: 23%
  • OTHER_CAUSE: 13%
  • SPECIAL_EVENT: 8%
  • MAINTENANCE: 6%
  • HOLIDAY: 5%
  • ACCIDENT: 4%
  • TECHNICAL_PROBLEM: 3%
  • WEATHER: 3%
  • POLICE_ACTIVITY: 1%
  • MEDICAL_EMERGENCY: 0.7%
  • DEMONSTRATION: 0%

[ckraatz]

@westontrillium that's fantastic data - thanks for sharing! Clearly there's latent demand for this addition.

• How much of your UNKNOWN_CAUSE usage could be reclassified as SPECIAL_EVENT? Would that push this even higher than 4th place?
• I'd guess that another 30-40% of OTHER_CAUSE usage is lack of personnel across all Alerts feeds. What does your data show about why customers use Unknown?

[westontrillium]

@ckraatz I actually did incorporate 7 alerts into my OTHER_CAUSE count which were mischaracterized as "UNKNOWN_CAUSE". :)

I found a few cases this year where staffing shortage is cited as a reason, but it's much less than 30-40%. There were a few where the root cause could plausibly be driver shortage but it wasn't advertised explicitly in the alert.

Unknown cause has included many things including traffic causing general delays, road obstructions/closures, or just notices about a recent change in the schedule/route wherein "unknown" is really being used as "N/A" (and thus should not have actually been defined by the user).

[ckraatz]

@westontrillium I stand corrected! Do you think the UNKNOWN_CAUSE provides any real value to agencies or riders? What if they just selected OTHER instead of UNKNOWN?

We're planning to remove it from our list of options.

The only reason I can see for Unknown is in more automated contexts where one system is pulling in Alerts that didn't have a defined Cause, so they apply Unknown. But if an agency publishes alerts saying the Cause/Effect of the Alert are Unknown, it's not a good look.

[dan-engler-arcadis]

Following @westontrillium's lead, some stats on Arcadis' customers:

• 100% of agencies who have published alerts with the existing OTHER_CAUSE cause have used it at least once to describe a special event.
• 28% of all alerts from agencies are OTHER_CAUSE.
• Depending on the agency, between 0.4% and 71% (19% average) of their OTHER_CAUSE alerts could have been categorized as SPECIAL_EVENT if it existed.

Given these stats and the fact that several agencies have reached out to express interest after seeing this PR, Arcadis is in support of this proposal.

[etienne0101]

For your information @ckraatz, now that the discussion period has taken place, you can open the voting period (vote to test the change). Usually, votes stay open for two weeks. ~

Slight correction: this PR follows the GTFS Realtime Specification Amendment Process, thus the next steps differ slightly from what was previously mentioned.

Since the minimum 7-day discussion period has passed, once you feel there’s sufficient support for the proposal, you can start seeking a producer and a consumer to test the changes.
After providing proof of implementation, you may then call for a vote (which must be opened for at least 7 days).