How Do Calendar Exceptions Interact with Weekly Service?
From the earlier reference collection. Read the current software blog.
GTFS weekly service patterns establish recurring dates, while calendar-date exceptions adjust the service that applies on a particular date.
Begin with the recurring pattern
In GTFS, calendar.txt describes service that operates on selected weekdays during a date range. Trips point to service identifiers, so the calendar pattern helps determine which trips are in effect on an ordinary date. This recurring pattern is a useful baseline, but it may not capture every special operating day. Holidays, unusual closures, or other date-specific changes can require an exception.
Apply the date-specific record
calendar_dates.txt provides additions or removals for service on specified dates. A date-specific addition can make a service identifier active on a date outside its usual weekday pattern; a removal can make it inactive on a date when the weekly pattern would otherwise include it. The file adjusts service for that identifier, rather than rewriting the weekday pattern itself.
For example, suppose service WKD normally operates Monday through Friday. If a particular Monday is a holiday and the agency does not run that service, an exception can remove WKD for that date. If a Saturday has a special weekday schedule, an addition can make WKD active on that Saturday. In each case, trips associated with WKD inherit the date-specific result.
Evaluate a date as a combined rule
A consumer should not read calendar.txt and calendar_dates.txt as unrelated alternatives. Determine the normal activity for the service identifier and date, then apply any matching date exception according to the specification. This yields the service status used to decide whether associated trips operate. A calendar-date row that refers to a different service identifier does not alter the one being evaluated.
When debugging a missing trip, inspect the trip’s service identifier first, then the weekly calendar and any exception for the date in question. This often reveals whether the issue is an incorrect trip reference, a date outside the calendar range, or a service removal.
Keep exceptions explicit and testable
Publishers can reduce ambiguity by checking all exceptional dates near the start and end of service periods and confirming that each exception names an existing service identifier. Consumers should preserve the distinction between the recurring rule and the exception when explaining a result: “inactive because of a date exception” is more informative than simply saying the trip is missing. The GTFS reference defines calendar.txt and calendar_dates.txt as complementary schedule files; applying both gives a clearer account of how weekly service changes on special dates.