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): SimplifyTransit
• Estimated Testing Period: 60 days

Proposal Update Tracker

Date	Update Description
(2026-05-05)	SimplifyTransit provided a feed for testing
(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?

[ckraatz]

Took us awhile, but we're now ready to test the proposed new SPECIAL_EVENT Cause. Who would be willing to test as a Consumer? @felixguendling did I hear correctly that MOTIS would?

• GTFS-realtime Service Alerts endpoint in protobuf format including alerts with the proposed Cause SPECIAL_EVENT: https://cdn.simplifytransit.com/clallam/alerts/test/service-alerts.pb
• Compile this proto spec to test as a Consumer: https://github.com/ckraatz/transit/blob/6356bf5bc2ce15eca36e8e1ef97e34dce35dc7f1/gtfs-realtime/proto/gtfs-realtime.proto#L647
• Here's the GTFS for Clallam Transit, the agency that requested this new Cause, in case you need that for testing: https://irp.cdn-website.com/0eaf265e/files/uploaded/clallam_transit_gtfs.zip

Please let me know if you run into any issues or have any feedback!

[felixguendling]

@felixguendling did I hear correctly that MOTIS would?

I'll look into it.

[felixguendling]

MOTIS supports it now (part of next release).

[ckraatz]

MOTIS supports it now (part of next release).

@felixguendling once that's released, could you share a visual showing these alerts in a MOTIS UI? I think we need to demonstrate the successful test, and then we can advance to the voting stage.

[felixguendling]

MOTIS is primarily a backend (with many frontends, see for example transitous.org with some examples), so there are no visuals. A successful test for MOTIS would be that the API contains the new SPECIAL_EVENT in the response. That's something anyone who's interested can replicate after MOTIS has been released. I don't understand the GTFS process requirements as "it has to be displayed visually".

[ckraatz]

@felixguendling is MOTIS testing as a Consumer or a Producer?

[felixguendling]

MOTIS is a consumer. But consumer != UI.

Edit: MOTIS has a UI but that's not the main part. The main part is the backend.

[ckraatz]

According to the GTFS-schedule Testing process we need to "apply and test the changes in a public-facing environment. For the Producer, this means a public GTFS feed; for the Consumer, this means a public-facing, production version of an application." I'm not sure what that would mean for MOTIS.

I was anticipating a Consumer test leading to a display of the GTFS-ServiceAlert we've produced on a website, in an app, or in some sort of browser-based UI that any GTFS community member could look at and agree it worked.

[felixguendling]

MOTIS is a "public-facing, production version of an application".

Application doesn't mean that it has a user interface. At least if that would be a requirement, it should be clearly stated in the process description.

any GTFS community member could look at and agree it worked

The GTFS community is a community of experts and mainly developers who are capable to use an API.

It wouldn't be a big deal to add support for this in the MOTIS UI but I disagree on this interpretation of the process requirements unless they are changed to explicitly require that the consumer has to include a user interface (web/app).

[etienne0101]

Hello @ckraatz and @felixguendling, thank you for moving this proposal forward.

Here is how the governance can be read in this specific case:

It specifies that:

the GTFS-realtime consumer(s) provides a link in the pull request comments to an application that is utilizing the change in a non-trivial manner (i.e, it is supporting new or improved functionality).

I think it's safe to say that MOTIS qualifies as a consumer tester, as the governance does not explicitly mandate a visual user interface.

[ckraatz]

@etienne0101 wonderful - thank you for clarifying! And thank you @felixguendling for testing and implementing this. Thanks for your patience with this everyone!

We're ready for the Vote to Adopt stage. Given the timing on a Friday before a holiday weekend in the US, I'll leave voting open until June 4 and we'll be ready for a summer of SPECIAL_EVENTs!

Please vote with a +1 or -1, your Organization Name and Contributor Type.

[felixguendling]

This could be the first step in adoption of SIRI reasons to make conversion between formats seemless.

+1 MOTIS

[gcamp]

+1 Transit

[jmchatton]

+1 PVTA

[miklcct]

+1 Aubin

[stevenmwhite]

+1 GMV

[westontrillium]

+1 Optibus

[dan-engler-arcadis]

+1 Arcadis

[bdferris-v2]

+1 Google

[laurentg]

+1 Mecatran.

I do not have very precise stats, but by quickly scanning our database of alerts this kind of cause is rather frequent (market day, fair, match, school event...) and is always classified as "OTHER_CAUSE" which seems to be the default "cover all" case when no other is matching.

[phil-swiftly]

+1 Swiftly

[jfabi]

+1 MBTA

[ckraatz]

This change is Adopted, with a final vote count of 11 in favor (2 major Consumers and at least 7 Producers) and 0 opposed. @etienne0101 could you please proceed with merging this pull request and advising on any next steps?

[etienne0101]

Thank you @ckraatz and all participants for this proposal, and congratulations for getting a consensus!
There is nothing to do on your side in particular.