Home

Awesome

Canonical GTFS Schedule Validator

Test Package Document End to end End to end big End to end 100 Rule acceptance tests Docker image Join the gtfs-validator chat

A General Transit Feed Specification (GTFS) Schedule (static) feed validator, maintained by MobilityData.


<p align="center"> <a href="#using-the-web-based-validator">Web version</a> ● <a href="#using-the-desktop-app">Desktop version</a> ● <a href="#using-the-command-line">Command line</a> ● <a href="#using-docker">Docker</a> </p> <p align="center"> <a href="https://github.com/MobilityData/gtfs-validator/blob/master/RULES.md">☑️ List of rules implemented</a> </p> <p align="center"> <a href="https://github.com/MobilityData/gtfs-validator/blob/master/docs/CONTRIBUTING.md"> 🤝 Contribute to the project</a> </p>

This README contains information for the latest version of the project, which is under active development. You can find the latest version of the validator application on the Releases page.

Introduction

This is a cross-platform application written in Java that performs the following steps:

  1. Loads input GTFS zip file from a URL or disk.
  2. Checks file integrity, numeric type parsing and ranges.
  3. Performs complete validation against the GTFS Schedule standard.
  4. Provides an easy-to-use validation report in HTML format that can be opened in the browser and shared with other parties. See an example of a validation report. The report is also available in JSON format that can be used for parsing and running additional analyses.
<video src="https://user-images.githubusercontent.com/63653518/234697111-59cbc5de-5bf2-4c49-8474-fd41ac51a745.mp4" controls="controls" style="max-width: 730px;"> </video>

Using the web-based validator

The GTFS Web Validator can be accessed at https://gtfs-validator.mobilitydata.org/. The GTFS Web Validator accepts locally saved datasets in a zip format and datasets available via the Web in an URL format. Validation reports have a unique URL link that can be shared and are available 30 days after creation.

The GTFS Web Validator contains two main components: the GTFS Web Validator Client and the GTFS Validator Web Service. More information about these components can be found in GTFS Web Validator Client and GTFS Validator Web Service.

Several users have reported issues with the validator when processing their GTFS feeds. These issues arise due to the configuration of their websites, which may not be set up to handle:

  1. Requests that come with custom user agents.
  2. Requests originating from non-browser sources.

To facilitate easier debugging and logging, we have made our user agent header explicit. The user agent string follows the format: "MobilityData GTFS-Validator/{validatorVersion} (Java {java version})". In cases where the validatorVersion is null, the {validatorVersion} segment in the user agent string will be left blank. The string "MobilityData GTFS-Validator/5.0.1 (Java 11.0.1)" serves as an example of the User Agent string.

Using the Desktop app

Setup

  1. Navigate to the Releases page and download the latest Gtfs Validator installer for your operating system:
    • Windows => .msi
    • Mac OS => .dmg
    • Linux => .deb
  2. Install application to your workstation.

Run it

Once installed, run the application and you will see the following screen:

Application-Windows

There are two primary options to set:

With these two options set, click the "Validate" button to begin validation.

Visualize the results

When validation is complete, the application will automatically open the HTML validation report in your local browser. In addition, the application creates the following files in the output directory:

Advanced Options

Before running validation, tap the Advanced button to configure other aspects of the application, including:

Using the command line

Setup

  1. Install Java 11 or higher. To check which version of Java is installed on your computer, type the following command in the terminal: java --version.
  2. Navigate to the Releases page and download the latest Gtfs Validator CLI jar (not OS-specific). It is located in the Assets section of the release, and it looks like gtfs-validator-vX.X.X_cli.jar
  3. Open the terminal on your computer
  4. Navigate to the directory containing the jar file. You can do this by typing the following command in the terminal:cd {directory path}, where {directory path} is the absolute or relative path to the directory. You can then make sure you're in the right directory by typing pwd in the terminal (this stands for present working directory). You can also make sure the jar file is there by typing ls in the terminal (this stands for list and will display the list of files in this directory). More about commands to navigate file and directories here.

Run it

You can run this validator using a GTFS dataset on your computer, or from a URL.

More detailed instructions with all the parameters that exists are available on our "Usage" page.

Visualize the results

In the output directory, the reports will be created as described here.

Using Docker

Setup

  1. Download and install Docker
  2. To obtain a validator Docker container image, you have two options:
    • Pull a published Docker container image from GitHub. For example, to pull the latest build of the master branch:

      docker pull ghcr.io/mobilitydata/gtfs-validator:latest
      
    • Build a Docker container image locally from any branch or working tree:

      docker build . -t ghcr.io/mobilitydata/gtfs-validator:latest
      

Run it

For Mac and Linux

To verify you can run the Docker image in a new container and see the help text:

docker run --rm ghcr.io/mobilitydata/gtfs-validator:latest --help

In order to pass files in and out of the validator, you'll need to use a volume mount to share a directory between your host computer and the Docker container:

docker run --rm -v /myDirectory:/work ghcr.io/mobilitydata/gtfs-validator:latest -i /work/gtfs.zip -o /work/output

where:

NOTE: On Windows, you must provide the local volume (e.g., c:) as well:

... c:/myDirectory:/work ...

The validator can then be executed via bash commands. See the preceeding instructions for command line usage.

Visualize the results

In the output directory, the reports will be created as described here.

Validation rules

Have a suggestion for a new rule? Open an issue. You can see the complete process for adding new rules on the "Adding new rules" page.

Previous Releases, Snapshot Builds, and Documentation

Build the code

We suggest using IntelliJ to import, build, and run this project.

Instructions to build the project from the command-line using Gradle are available in our Build documentation.

Architecture

The architecture of the gtfs-validator is described on our Architecture page.

Acceptance tests

In order to avoid sudden changes in the validation output that might declare previously valid datasets invalid, all code changes in pull requests are tested against GTFS datasets in the MobilityDatabase. The acceptance test process is described in ACCEPTANCE_TESTS.md.

Projects based on this validator

CalTrans California Integrated Travel Project (Cal-ITP) GTFS Validator API - A thin wrapper around MobilityData/gtfs-validator.

License

Code licensed under the Apache 2.0 License.

Contributing

We welcome contributions to the project! Please check out our Contribution guidelines for details.