Clarify spec: Add definitions to Cause and Effect values and clarify Trip Update and Service Alerts usage for consumer routing decisions

[skalexch]

Summary

MobilityData is currently developing Service Alerts guidance to help the community use Service Alerts more consistently. As part of this work, we are gathering feedback through the Service Alerts Working Group meeting.

In the Apr 28th, 2026 meeting, we presented and discussed detailed definitions of values for the Cause and Effect fields, drafted here, to make sure that producers are attributing the correct values to real-world cases.

In addition, we discussed how consumers should interpret cases where both Trip Updates and Service Alerts apply but provide conflicting information. The group reached consensus that consumers should by default give precedence to Trip Updates for routing decisions. use both to inform routing decisions, and that producers should have the highest quality possible in their trip updates feeds.

Proposed Solution

This PR

1. Adds a clarification to feed-entities.md describing that both trip updates and services alerts should be used to inform routing decisions. And that trip updates must always be accurate to what is happening in the transit network.
   While this clarification will also be included in the Service Alerts guidance, we believe it is appropriate to include it directly in the specification as well, in order to make this shared expectation clearer.

2. Details the definitions for values of Cause and Effect, to make sure that service alerts are correctly categorized.

These changes are intended to clarify definitions and to clarify a principle for expected consumer behaviour, and they do not introduce a new field or functional change. Therefore, I propose that it can proceed to a vote without requiring implementation testing.

Type of change

GTFS Schedule

• Functional Change
• Non-Functional Change
• Documentation Maintenance

GTFS Realtime

• Specification Change
• Specification Change (Experimental Field)

Additional information

Here is the working group meeting notes

We also plan to add an additional Service Alerts meeting in July to continue discussing guidance around Service Alert usage. Registration page

[felixguendling]

If data consumers use Service Alerts to affect routing decisions

Wouldn't it be nice to have a clear guidance on whether they should do this or not? At the moment it seems to be "do whatever you want"?

I also only see NO_SERVICE where this would be an option. Or are there others that should be considered for routing?

[gcamp]

My comment here still stands. From @tzujenchanmbd's response, the argument that there's flexibility in the guidelines doesn't remove the fact that I have the feeling that anyone considering NO_SERVICE in their routing will do the opposite of what the guidelines suggest. Might as well not have a guideline?

[gcamp]

Was leaving out station entrances and pathway nodes done on purpose?

[skalexch]

@gcamp yes. The topic of allowing alerts for pathways, entrances, exits is something that has been talked about for a while and we are planning to start that conversation soon. Building one what was mentioned on issue#268, the intent was to clarify some things in the realtime spec (such as here and in #546 ), create documentation to help with implementation and how to deal with use-cases (such as the spec vs RT Guidance and the RT Alerts Guidance), then eventually get to "alerts on pathway data". That conversation can involve all location_types and pathway_modes.

[felixguendling]

TU is generally a couple hours in the future and alerts are multiple weeks in advance.

What stops you from sending TU for multiple weeks in advance? Technically there's no blocker on the protocol level that would prevent this. It's a bit verbose, so that might be an indicator to improve TU rather than to (mis)use NO_SERVICE? The other option would be to clearly define that NO_SERVICE has to be considered during routing. The status-quo that everyone does what they want is something a standard should avoid. Most feeds are tailored to show the right thing for their "main" consumer (often that's Google Maps). But that's exactly what a good standard should prevent (tailoring the producer to a specific consumer).

[leonardehrenfried]

I concur with @felixguendling: This dispute has been going on for so long that I frankly don't really care anymore what the standard position is as long as it is clear and the argument is over.

[tzujenchanmbd]

As @leonardehrenfried mentioned, this has been an ongoing discussion for a long time. At the same time, we can also observe that Service Alerts are already widely used in practice, while some aspects of the documentation still need clarification. The current situation can lead to information that is difficult for riders to understand or even incorrect.

We (MobilityData) have been trying to find practical solutions that improve the current situation while remaining acceptable to different stakeholders within the community, including this PR, #546, and the Service Alerts Guide, even if these compromise-based solutions are probably not perfect for everyone.

One observation from recent discussions is that the community seems to be increasingly recognizing the practical value of using NO_SERVICE as a routing signal. As @felixguendling suggested, perhaps we could explicitly indicate that NO_SERVICE has to be considered a valid input for routing decisions, which should align with what many trip planners already do today. We'd be interested in hearing what others think about making that expectation explicit.

However, once we clarify that NO_SERVICE can be used as a routing input, as well as its definition for different entities, a follow-up question is what consumers would do when NO_SERVICE conflicts with TU. This was discussed during the April Working Group Meeting, where the following direction emerged from the discussion:

• When SA is the only available data, consumers use NO_SERVICE as a routing signal.
• When both SA and TU are present and conflict, TU takes precedence by default.

During the discussion, this direction received support from the producers participating in the meeting, and representatives from both Google and Apple also expressed support in principle. (Meeting notes)

Even though there may be situations where consumers choose to prioritize SA instead (e.g. when there is clear evidence that TU is incorrect), I think defining a default behavior can still provide value by establishing a common expectation for handling conflicts. Does this seem like a reasonable balance that the community could align on?

[leonardehrenfried]

My preference is to put everything routing-related in TU but I can get behind this definition.

[felixguendling]

MOTIS is currently not considering NO_SERVICE relevant for routing and expects another TU. Currently TU=routing, SA=annotation. But as @leonardehrenfried, I'm open to change this to TU=routing, SA=routing+annotation if the GTFS standard clearly states that it has to be done this way.

we clarify that NO_SERVICE can be used as a routing input

Please don't clarify that NO_SERVICE can be used as a routing input. Either clarify that it has to be used as a routing input or clarify that it must not be used as a routing input. If you say "can" be used as a routing input we are not making any progress. That's obviously already the status quo. I'm open for both options - as long as it's a clear "has to be used" (+ conflict resolution) or "must not be used".

[skalexch]

@leonardehrenfried @felixguendling
After the last RT Service Alerts Working Group Meeting, the group discussed this specific proposal. The main points concerned:

• The shorter timespan of Trip Updates which gives rise to the necessity of another disruption source for planning trips beyond that span.
• Risk of contradiction between Trip Updates and Service Alerts.
• Limited agency resources and consumers having to act quickly.

A consensus was reached in which:

1. Both Trip Updates and Service Alerts can be used to affect routing decisions. The group is also okay with using MUST and SHOULD for them. No priority order is put here.
2. Producers must have accurate Trip Update feeds. They also need to make sure that their alerts feed does not fully depend on their TU so that they can adjust it through other ways.
3. Producers must avoid contradictions between their feeds.
4. Consumers should use both feeds to inform routing decisions.

@gcamp @skinkie

Your feedback is welcome!

[leonardehrenfried]

I can live with this outcome and prefer it over the current ambiguity.

[skalexch]

We are starting a vote to formally adopt these definitions and clarifications into the spec.

The voting period will span 1 week and will end on 2026-08-20 at 23:59:59 UTC.

[gcamp]

+1 Transit

[phil-swiftly]

+1 Swiftly

[skalexch]

The vote concludes in one day. Tagging remaining participants from the previous working group meeting for visibility.
@bdferris-v2 @evansiroky @halbertram @jfabi @vicentecamposquezada

[halbertram-ito]

+1 Ito

[felixguendling]

Data consumers SHOULD use both Trip Updates and Service Alerts to make routing decisions

Why only SHOULD? Why not MUST? For SHOULD a few examples should be listed in which situations you would not want to have service alerts influence routing.

SHOULD   This word, or the adjective "RECOMMENDED", mean that there
may exist valid reasons in particular circumstances to ignore a
particular item, but the full implications must be understood and
carefully weighed before choosing a different course.

Can we please state those "valid reasons in particular circumstances" explicitly? It's not obvious why the standard would not pin this down to "MUST".

"such as cancelling a trip or closing a stop"

I would like to have an exhaustive list, not just examples. Currently I only see NO_SERVICE and the effect for routing should be clearly stated. For example for a stop: does NO_SERVICE mean I can't board/alight there or I can't even pass there, so all trips passing the stop are effectively cancelled? This leaves a lot of room for ambiguity. I don't see a good reason why the standard would leave this open?

---

Overall it leaves a lot of room for interpretation where it would help to be precise.

[leonardehrenfried]

I find this sentence very hard to parse. Could you perhaps re-write it for maximum clarity (perhaps at the cost of some verbosity)?

[skinkie]

The discussion was something like: some producers are unable to make new timetables. For months they are using their AVL system to skip a stop. But their AVL system has a horizon of just 90 minutes. Hence every trip planned after 90 minutes would still show the regular timetable.

For me it is also very hard to comprehend why people would accept this quality of their vendors.

[felixguendling]

Does it make sense to design the GTFS standard for the worst practices? I would rather design for good practices to produce great results.

In case they really can't produce a static GTFS file for months, I would rather write a little script that takes the GTFS file and the GTFS-RT protobuf and update the GTFS file accordingly. In most systems data coming in via GTFS-static will also be displayed differently than GTFS-RT and in this case you would probably want the GTFS-static version.

[leonardehrenfried]

So, cancelling a route or agency recursively cancels all trips of that entity? I think this would be a very valuable clarification.

[skinkie]

My suggestion was more in the direction: there should be to cancellation flags. One from tripUpdates and one from ServiceAlerts.

[leonardehrenfried]

Can you set an agency to NO_SERVICE? If yes, what happens then?

[skinkie]

There is a strike :-)

[leonardehrenfried]

I recognize that I'm coming in late but I have a few comments:

I agree with @felixguendling that the current wording is only a small improvement and would like to see it spelled out in more detail.

Questions:

• is it only NO_SERVICE that close stops or POLICE_ACTIVITY and CONSTRUCTION, too

[felixguendling]

I'm clearly "pro clarification", so I support this effort, but in it's current status, I vote:

-1 MOTIS

I think we don't have to rush this one. And it's not much that's missing to make it a proper clarification.

I'm open to work on a clear table that maps "effect" to an equivalent TripUpdate (for everything that has a routing impact) with "for all" clauses. As long as TripUpdates are then clearly defined, this will give us a 100% clear guidance of how to apply ServiceAlerts for routing.

[leonardehrenfried]

I hate to make this more painful than it already is but I agree with Felix.

-1 OTP

[gcamp]

On the SHOULD vs MUST, my understanding is that since we have this language

Producers MUST also ensure that there is no conflict between their Trip Updates and Service Alerts feeds.

The idea is that consumer don't have to consume both alerts and trip updates, if they don't want to. It's basically a way to have current consumer not taking alerts into account not having the obligation to update their implementation. I agree wording can be improved.

My point at the meeting was that alerts are useful in the real world, since trip updates often lack the required cancellation, so the MUST ensure no conflict was a way that we all agreed.

That said I agree wording could be improved

[gcamp]

Suggested change

	| **DETOUR** | The route changes its shape, resulting in the route not serving one or multiple stops, or picking up/dropping off at other locations. |
	| **DETOUR** | The route changes its shape, which may affect pickup/drop off at some stops. |

Detour doesn't mean stops are cancelled

[felixguendling]

The idea is that consumer don't have to consume both alerts and trip updates, if they don't want to.

If the consumer happens to be a routing engine, then that routing engine will definitely produce wrong routing results if the producer happens to produce NO_SERVICE alerts and expects routing results to change without also encoding the same service change as TU?

Maybe some consumers can ignore ServiceAlerts but if we say that NO_SERVICE (and potentially others) should impact routing, I don't see another option than to make consuming ServiceAlerts mandatory for routing engines? If we say "if they don't want to", they can ignore SA for routing, then we are again at the starting point, i.e. the status "you can do whatever you want".

I think we should aim for more consistent behavior of routing results across routers. This can only be achieved by making those very fundamental decisions (like SA impacts routing or not) strict requirements. The other option is that GTFS is just pure syntax and every producer/consumer chooses the semantics on a "do whatever you want" basis making 1:1 alignment between producers+consumers necessary. IMO this is something a good standard should avoid. 100% compatibility = the default: you can't claim GTFS-RT support and then not be compatible in practice.

I would be interested to learn from someone who implemented a routing engine that already implements "SA impacts routing results" how they did this: is it only NO_SERVICE or also others? Is it possible to set NO_SERVICE on a complete agency which should then kill all trips of that agency in the complete impact period? That sounds dangerous in terms of "oops, wrong button -> nothing works" but could also be useful to model a strike?

[gcamp]

if the producer happens to produce NO_SERVICE alerts and expects routing results to change
That's why there's the language that alerts and trip updates should match. If they don't, then it's against the spec. The proposal here is exactly what you're pushing for : a consistent behaviour if everyone follows the spec.

Why not enforcing the alert consideration for consumers too? Because there was strong voice against that it should not be necessary. By putting Producers MUST also ensure that there is no conflict between TU and SA we solve the impasse while enforcing something everyone agrees on.

I would be interested to learn from someone who implemented a routing engine that already implements "SA impacts routing results" how they did this: is it only NO_SERVICE or also others? Is it possible to set NO_SERVICE on a complete agency which should then kill all trips of that agency in the complete impact period? That sounds dangerous in terms of "oops, wrong button -> nothing works" but could also be useful to model a strike?

Google and Transit only does it for NO_SERVICE yes. I think Google has some heuristics, and we also have feature flag depending on the agency.

We support NO_SERVICE on an entire agency, but yes it's too high risk of false positive, so we again have a separate feature flag that we manually enable. We also support stop_id on a station entrance that is explicitly disallowed in this proposal.

[felixguendling]

By putting Producers MUST also ensure that there is no conflict between TU and SA we solve the impasse while enforcing something everyone agrees on.

Totally agree 👍

Google and Transit only does it for NO_SERVICE yes

I would be happy to see this as hard requirement in this PR. Since Google and Transit do it this way, it's proven to work and Google+Transit don't have to put any additional effort and the rest can align on this as well and know exactly what to do.

We also support stop_id on a station entrance that is explicitly disallowed in this proposal.

I think disallowing it is a bad idea because any future change might become a compatibility issue. We can either keep this undefined (to clearly define it in the future) or just clearly define that all pathways through this entrance are considered infeasible, requiring the router to find new shortest paths (which might make a whole journey infeasible). It would also be interesting to allow referencing pathways to disable elevators in the future. We currently only support this for OSM+SIRI in MOTIS.

[skalexch]

The vote has concluded and failed. The result is as follows:
+1: Transit, Swiftly, ITO (@gcamp @phil-swiftly @halbertram-ito )
-1: OTP, MOTIS (@leonardehrenfried @felixguendling )

The criticisms made above make sense. Based on the discussion so far, we will get back soon with some suggestions to make the proposal clearer and more practical.

[leonardehrenfried]

I am sorry for voting -1. This has been the first time I ever did this.

I don't reject this feature outright and will vote in favour if the wording is clarified.