Skip to content

Clarify spec: Add definitions to Cause and Effect values and clarify Trip Update precedence for consumer routing decisions #648

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
skalexch wants to merge 4 commits into
base: master
Choose a base branch
from
Open

Clarify spec: Add definitions to Cause and Effect values and clarify Trip Update precedence for consumer routing decisions #648

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
85b781a
Add definitions to Cause and Effect values
skalexch Jun 23, 2026
a547a6a
added definition to reference page
skalexch Jul 8, 2026
2021aa5
# This is a combination of 5 commits.
skalexch Jul 8, 2026
4745f61
add tripupdate clarification
skalexch Jul 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions gtfs-realtime/spec/en/feed-entities.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,13 @@ A service alert will usually consist of some text which will describe the
problem, and we also allow for URLs for more information as well as more
structured information to help us understand who this service alert affects.

#### Interaction between Trip Updates and Service Alerts

If data consumers use Service Alerts to affect routing decisions, and both Trip Updates
and Service Alerts apply but provide conflicting information, consumers should
give precedence to Trip Updates for routing decisions, unless there is clear
evidence that the Trip Updates is incorrect.

[More about Service Alerts...](service-alerts.md)

## Vehicle Positions
Expand Down
56 changes: 28 additions & 28 deletions gtfs-realtime/spec/en/reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -386,41 +386,41 @@ Cause of this alert.

**Values**

| _**Value**_ |
|-------------|
| **UNKNOWN_CAUSE** |
| **OTHER_CAUSE** |
| **TECHNICAL_PROBLEM** |
| **STRIKE** |
| **DEMONSTRATION** |
| **ACCIDENT** |
| **HOLIDAY** |
| **WEATHER** |
| **MAINTENANCE** |
| **CONSTRUCTION** |
| **POLICE_ACTIVITY** |
| **MEDICAL_EMERGENCY** |
| **SPECIAL_EVENT** |
| _**Value**_ | _**Comment**_ |
|-------------|----------------|
| **UNKNOWN_CAUSE** | Used when the cause of the disruption is not known or has not been determined. Should be avoided if any more specific cause can be reasonably identified. |
| **OTHER_CAUSE** | Used for causes that do not represented by any of predefined options. |
| **TECHNICAL_PROBLEM** | Issues related to vehicles or infrastructure malfunctioning. Examples include mechanical failure and information system bugs. |
| **STRIKE** | Service disruptions caused by a labor strike involving the transit agency or operator. |
| **DEMONSTRATION** | Service disruptions caused by public demonstration, protest, or gathering. |
| **ACCIDENT** | Incidents such as collisions or derailments that disrupt services. |
| **HOLIDAY** | Any public holiday that might result in a change of service. |
| **WEATHER** | Disruptions caused by weather conditions such as snow, storms, flooding, etc. |
| **MAINTENANCE** | Planned maintenance related to the services. Examples include track maintenance, elevator maintenance and vehicle maintenance. |
| **CONSTRUCTION** | Any construction that affects the service, regardless whether it relates to the services or not. Examples include station construction and roadworks that affect bus routes. |
| **POLICE_ACTIVITY** | Disruptions due to law enforcement activity or security incidents. Examples include investigations or security threats. |
| **MEDICAL_EMERGENCY** | Incidents involving passenger or staff medical emergencies. Examples include an on-board medical problem that forces a train to stop. |
| **SPECIAL_EVENT** | A special one-time or recurring event such as a parade, festival, performance, farmers market, or sporting event. |

## _enum_ Effect

The effect of this problem on the affected entity.

**Values**

| _**Value**_ |
|-------------|
| **NO_SERVICE** |
| **REDUCED_SERVICE** |
| **SIGNIFICANT_DELAYS** |
| **DETOUR** |
| **ADDITIONAL_SERVICE** |
| **MODIFIED_SERVICE** |
| **OTHER_EFFECT** |
| **UNKNOWN_EFFECT** |
| **STOP_MOVED** |
| **NO_EFFECT** |
| **ACCESSIBILITY_ISSUE** |
| _**Value**_ | _**Comment**_ |
|-------------|----------------|
| **NO_SERVICE** | No transit service to the specified entity(-ies).<br>- For stations or stops, the rider will not be able to board or alight.<br>- For routes, the route will not run.<br>- For trips, those specific trips are cancelled. |

@gcamp gcamp Jul 14, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@skalexch skalexch Jul 15, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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.

| **REDUCED_SERVICE** | The number or frequency of trips is reduced. |
| **SIGNIFICANT_DELAYS** | The route will consistently run late (insignificant delays should only be provided through [Trip updates](trip-updates.md)). |
| **DETOUR** | The route changes its shape, resulting in the route not serving one or multiple stops, or picking up/dropping off at other locations. |
| **ADDITIONAL_SERVICE** | The number or frequency of trips is increased. For example, more buses are running to cover for a special event. |
| **MODIFIED_SERVICE** | Operations are different from what the rider would normally expect. An example is an alert that reminds riders of an upcoming holiday schedule that is different from normal service on that day of the week. |
| **OTHER_EFFECT** | Not represented by any of these options. |
| **UNKNOWN_EFFECT** | Used for alerts whose effect has not been identified yet. Do not use "Unknown effect" if the effect of the alert is known or can be deduced from the alert header or description. |
| **STOP_MOVED** | A stop location is changed temporarily or permanently (if known to be permanent, ensure the new location is reflected in the schedule data). |
| **NO_EFFECT** | The alert provides information to riders but does not affect operations. Examples include advertising public meetings and soliciting feedback via surveys. Unless necessary, it is advised not to use this effect. |
| **ACCESSIBILITY_ISSUE** | The alert provides information about accessibility issues that affect step-free access. Examples include an out of service elevator or movable ramps, a bus that is unable to kneel, or an exceptional service with trains that have a big platform gap. |

## _enum_ SeverityLevel

Expand Down
51 changes: 27 additions & 24 deletions gtfs-realtime/spec/en/service-alerts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,32 +32,35 @@ If you would like to represent an alert that affects more than one entity (e.g.

What is the cause of this alert? You may specify one of the following:

* Unknown cause
* Other cause (not represented by any of these options)
* Technical problem
* Strike
* Demonstration
* Accident
* Holiday
* Weather
* Maintenance
* Construction
* Police activity
* Medical emergency
* Special Event
* **Unknown cause**: Used when the cause of the disruption is not known or has not been determined. Should be avoided if any more specific cause can be reasonably identified.
* **Other cause**: Used for causes that do not represented by any of predefined options.
* **Technical problem**: Issues related to vehicles or infrastructure malfunctioning. Examples include mechanical failure and information system bugs.
* **Strike**: Service disruptions caused by a labor strike involving the transit agency or operator.
* **Demonstration**: Service disruptions caused by public demonstration, protest, or gathering.
* **Accident**: Incidents such as collisions or derailments that disrupt services.
* **Holiday**: Any public holiday that might result in a change of service.
* **Weather**: Disruptions caused by weather conditions such as snow, storms, flooding, etc.
* **Maintenance**: Planned maintenance related to the services. Examples include track maintenance, elevator maintenance and vehicle maintenance.
* **Construction**: Any construction that affects the service, regardless whether it relates to the services or not. Examples include station construction and roadworks that affect bus routes.
* **Police activity**: Disruptions due to law enforcement activity or security incidents. Examples include investigations or security threats.
* **Medical emergency**: Incidents involving passenger or staff medical emergencies. Examples include an on-board medical problem that forces a train to stop.
* **Special Event**: A special one-time or recurring event such as a parade, festival, performance, farmers market, or sporting event.

## Effect

What effect does this problem have on the specified entity? You may specify one of the following:

* No service
* Reduced service
* Significant delays (insignificant delays should only be provided through [Trip updates](trip-updates.md)).
* Detour
* Additional service
* Modified service: Operations are different from what the rider would normally expect. An example is an alert that reminds riders of an upcoming holiday schedule that is different from normal service on that day of the week.
* Stop moved
* Other effect (not represented by any of these options)
* Unknown effect
* No effect: The alert provides information to riders but does not affect operations. Examples include advertising public meetings and soliciting feedback via surveys.
* Accessibility issue: The alert provides information about accessibility issues that affects step-free access. Examples include an out of service elevator or movable ramps.
* **No service**: No transit service to the specified entity(-ies).
* For stations or stops, the rider will not be able to board or alight.
* For routes, the route will not run.
* For trips, those specific trips are cancelled.
* **Reduced service**: The number or frequency of trips is reduced.
* **Significant delays**: The route will consistently run late (insignificant delays should only be provided through [Trip updates](trip-updates.md)).
* **Detour**: The route changes its shape, resulting in the route not serving one or multiple stops, or picking up/dropping off at other locations.
* **Additional service**: The number or frequency of trips is increased. For example, more buses are running to cover for a special event.
* **Modified service**: Operations are different from what the rider would normally expect. An example is an alert that reminds riders of an upcoming holiday schedule that is different from normal service on that day of the week.
* **Stop moved**: A stop location is changed temporarily or permanently (if known to be permanent, ensure the new location is reflected in the schedule data).
* **Other effect** Not represented by any of these options.
* **Unknown effect**: Used for alerts whose effect has not been identified yet. Do not use “Unknown effect” if the effect of the alert is known or can be deduced from the alert header or description.
* **No effect**: The alert provides information to riders but does not affect operations. Examples include advertising public meetings and soliciting feedback via surveys. Unless necessary, it is advised not to use this effect.
* **Accessibility issue**: The alert provides information about accessibility issues that affect step-free access. Examples include an out of service elevator or movable ramps, a bus that is unable to kneel, or an exceptional service with trains that have a big platform gap.
Loading