How Do You Document a Schedule’s Update Cadence?
From the earlier reference collection. Read the current software blog.
Document how often schedule data is expected to refresh, what a successful retrieval means, and when the current feed was last fetched successfully.
Describe an expectation, not a promise
A schedule tool should tell readers how frequently it normally checks for updated feed data and how it behaves when retrieval fails. The cadence is an operational expectation, not a guarantee that an agency will publish new content on a fixed timetable. Keep the wording tied to the tool’s actual process and avoid implying that every check produces a new schedule.
A static schedule dataset has a versioned set of files, and a changed dataset represents a new version in the GTFS reference. That makes it useful to distinguish when the tool retrieved a dataset from when the publisher last changed it. [GTFS schedule reference](https://gtfs.org/documentation/schedule/reference/)
Show the last successful retrieval
Display a timestamp such as “Feed last retrieved successfully: Tuesday, 09:15 local time,” ideally with the relevant time zone. If retrieval attempts have failed since then, say that the displayed data comes from the earlier successful fetch. A failed check should not reset the successful-retrieval timestamp.
For example, if a service checks every six hours but the latest request timed out, the interface can report the last successful retrieval and avoid suggesting that the feed is six hours fresh merely because a check was attempted. Store separate fields for attempt time and success time.
Define what freshness means
Document whether “updated” means newly downloaded bytes, a changed content fingerprint, or a successful validation of the feed. Those are different events. A publisher may serve identical content on repeated retrievals; that is still a successful check but not a new dataset version.
If the tool detects a changed feed, explain when the new version becomes available in search results and whether cached answers are rebuilt. Readers need enough information to understand why a timetable may differ from one they viewed earlier.
Make the cadence useful to operators
Record retrieval status, response time, feed fingerprint, validation outcome, and success timestamp in operational logs. Keep public messages concise and avoid exposing internal error details that do not help riders. An operator view can provide more specific diagnostics for failed downloads or invalid files.
A clear cadence note answers three questions: how often checks are expected, when the current data was last retrieved successfully, and whether the publisher’s content changed. That makes freshness understandable without promising an update schedule the tool cannot control.