How Can You Make a Tiny GTFS Feed Inspector?
From the earlier reference collection. Read the current software blog.
An archive inspector can list files, check expected tables, count rows, and show headers without attempting full feed validation.
Inspect the archive as supplied
A tiny GTFS feed inspector is a read-only first look at an archive. It answers practical questions: which files are present, are key tables included, how many records do they contain, and what headers were detected? It should describe what it sees without claiming that the feed is fully valid.
Open the archive and list its member names before reading any table. This makes unexpected directory nesting or alternate filenames visible. For each text table, report whether it can be opened and parsed as CSV. Avoid extracting files to an arbitrary location; reading directly from the archive keeps the tool simple and reduces leftover temporary files.
Check required tables carefully
Define the minimum expected file set for the inspector’s chosen scope. For a basic schedule inspection, that might include agency.txt, stops.txt, routes.txt, trips.txt, and stop_times.txt; a more complete feed has additional tables and conditional requirements. The GTFS reference distinguishes required, optional, and conditionally required files, so consult it when deciding what to flag.
Print missing expected tables separately from present files. A missing file should not prevent the inspector from reporting all other archive contents. Be precise in wording: “expected table missing” is safer than “invalid feed” unless the program implements the specification’s complete validation rules.
Count rows and expose headers
For each readable CSV file, show its header fields and the number of data rows, excluding the header itself. A table with only a header has zero records, not one. Use a CSV parser to handle quoted values and embedded commas correctly. If the file is empty or has a malformed header, report that condition rather than presenting an invented count.
A compact output could say: trips.txt — 42 rows — headers: route_id, service_id, trip_id. The count is useful when comparing two feed versions, while the header list can reveal a renamed or missing column at a glance. Preserve the original spelling of names; a diagnostic should not silently rewrite source data.
Keep the tool honest about its limits
The inspector should separate archive problems, CSV parsing problems, and basic content observations. For example, a corrupt archive is a different failure from a valid archive that lacks calendar.txt. Return a useful status code for unreadable input and include the offending member name in diagnostics.
A useful next step is to test with a small archive containing one normal table, one header-only table, and one absent expected table. Verify that the reported row counts and missing-file list match the fixture. This check keeps the utility understandable: it is an inventory aid, and deeper validation can be added as a distinct feature when needed.