Modeling a Transit Itinerary as a Sequence of Events
From the earlier reference collection. Read the current software blog.
Represent a transit journey as ordered events with explicit locations, times, and legs, then validate invariants that expose impossible or ambiguous trip plans.
Give each event a place and time
A journey can be modeled as events rather than a single string such as “take the bus, then transfer.” A leg has a boarding location and time, an alighting location and time, and a service or trip identity. A transfer connects the alighting event of one leg to the boarding event of the next.
Keep planned times and observed times in separate fields if both exist. A departure at 08:10 in a schedule is not evidence that a vehicle actually left then. Likewise, store the relevant date and time zone context rather than assuming that a local clock value alone identifies one instant.
Order the events explicitly
For a two-leg trip, the sequence might be: arrive at stop A, depart stop A, arrive at stop B, transfer, depart stop B, arrive at stop C. Represent the transfer as a relationship between legs, not as an invented ride segment. This makes the data easier to render and lets search logic inspect each connection.
A useful model can preserve the source’s trip and stop identifiers alongside display names. Names can be corrected or translated; stable identifiers help link events back to their schedule records. In a GTFS schedule, for example, trips, stops, and stop times are represented in distinct files, and a service day can extend past midnight. This matters when a listed time such as 25:10 belongs to the prior service day rather than the next calendar date.
Validate invariants
Check that each leg’s departure and arrival refer to valid locations, and that its arrival is not earlier than its departure under the service’s time rules. For consecutive legs, ensure the second departure does not precede the first arrival. If the model includes transfer duration, compare it with the stated minimum where available; do not invent a universal connection allowance.
Also check ordering and identity: a leg should have one origin and destination, and a transfer should connect the endpoint of one leg to the start of the next. Report a failed invariant with the event identifiers and the rule that failed, so it can be corrected at the data boundary rather than hidden in the display.
Test with a real planning question
Choose a question a rider might ask: “Can I leave after 08:00, transfer at B, and arrive at C before 09:00?” The model should support filtering departures, checking the connection sequence, and presenting each event with enough context to explain the result. If the answer cannot be computed without guessing a date, time zone, or transfer rule, the data representation is missing a meaningful part of the problem.
A schedule lookup provides a reader-facing way to inspect whether event ordering is useful for an actual trip-planning question. GTFS documentation is a relevant reference for schedule entities and service-day time conventions, though a particular lookup may use a different representation.