Mobility Data Interoperability Principles

Public Transit, and the mobility services which support it, is a critical backbone to our environmental, economic, and societal well-being. Modern, easily-accessible and well-operated public transit depends on a complex system of operations and customer-oriented technology components which work together.

Interoperable transit technology systems enable transit providers to plan service which is responsive to rider needs, improve service quality and efficiency, and adapt to continuing changes. Interoperability also encourages innovation among transportation technology companies while helping them to contain costs.

Released in October 2021 after a collaborative public process, Mobility Data Interoperability Principles create an industry-agreed upon vision, definition and direction for achieving interoperability with clear roles and responsibilities. The Principles were collaboratively developed and refined over Summer and Fall of 2021 by dozens of public and private organizations and researchers through a public review process.

Over 60 public and private signatories have committed to implementing the Principles. Organizations who are interested in publicly committing to the Principles and their faithful implementation can submit the form found at: Mobility Data Interoperability Principles.

Attribution

• California Association of Coordinated Transportation (CALACT)
• California Integrated Travel Project (Cal-ITP)
• Denver Regional Transportation District (RTD)
• ENTUR
• Los Angeles County Metropolitan Transportation Authority
• Massachusetts Bay Transportation Authority (MBTA)
• MetroTransit
• Metropolitan Transportation Commission (MTC)
• Minnesota Department of Transportation
• MobilityData
• North Carolina Department of Transportation
• Oregon Department of Transportation
• Shared Use Mobility Center (SUMC)
• Taskar Center for Accessible Technology
• Tri-Met
• Vermont Agency of Transportation
• VIA Metropolitan Transit San Antonio
• Washington State Department of Transportation (WSDOT) Public Transportation Division

Specification registry (/specifications)

The /specifications page, one page per specification under /specifications/<id>/, and a read-only JSON API under /api/ are generated at build time from the files in data/. GitHub is the source of truth and the place to contribute: each specification and each organization is one Markdown file with YAML front matter, and "Suggest a change" on a specification's page opens that file in GitHub's editor.

Path	What it is
data/specifications/<id>.md	One specification: fields in front matter, then # Description.
data/organizations/<id>.md	One organization, its role and a link to its logo.
data/principles.csv	The criteria and what earns each verdict.
data/licences.csv	The licence ids specifications may use.
data/README.md	Every field and allowed value, the ranking, and the API.
scripts/spec_data.py	Loads, validates and joins the files.
scripts/spec_api.py	Builds the /api/ files: catalogue, full records, export CSV, the OpenAPI description, and its Swagger UI page at /api/docs/.
scripts/check_specs.py	make specs-check: validation, also run on every pull request.
hooks/specifications.py	MkDocs hook that renders the pages and publishes the API.

make specs-check    # validate the data; fails on any unknown value or key
make specs-export   # write the API files to generated/api/
make serve          # check the result

make serve caches the hook module, so restart the server after editing hooks/ or scripts/: it rebuilds, but with the previous code.

Building the site locally

1. In Terminal, change the directory to one where you wish to build the site.
2. Ensure you have an up-to-date version of pip:
   • Linux: pip install pip or pip install --upgrade pip
   • macOS: pip3 install pip or pip3 install --upgrade pip
3. Clone this repository:
   • git clone https://github.com/MobilityData/Mobility-Data-Interoperability-Principles
4. Change the directory to the cloned repository, and create & enable a Python virtual environment:
   • python3 -m venv venv
   • source venv/bin/activate
5. Have requirements.txt installed:
   • Linux: pip install --force-reinstall -r requirements.txt
   • macOS: pip3 install --force-reinstall -r requirements.txt
6. Have Material for MkDocs Insiders installed. Substitute ${GH_TOKEN} with MobilityData's access token:
   • Linux: pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
   • macOS: pip3 install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
7. To run the site locally (command defined in MakeFile):
   • make serve
   • Then each language will have it's own address:
     • English: http://127.0.0.1:8000/
8. To build the site locally only (command defined in MakeFile):
   • make build
9. Deactivate the Python virtual environment when done:
   • deactivate

License

This code in this repository is licensed under Apache 2.0.

The content in this repository is licensed under CC BY 2.0