How to Use Policy Requirements in MDS 1.2.0

February 8, 2022

Enhancing Privacy in MDS 1.2.0

After 10 months of development and review, MDS 1.2.0 was released in November 2021. This new version added features that improve accuracy and better support data privacy, adding digital program requirements, new options for policies, and more.

Led by a steering committee of experts from across public and private sectors, MDS 1.2.0 was developed through OMF’s unique, open source model. The OMF provides facilitation and a governance model that allows different stakeholders in the community to propose changes and to have those changes reviewed, critiqued, and improved by other community members. This collaborative space results in a better specification, one that’s been “stress tested” in advance by the people who will use it. One of those changes is the addition of Policy Requirements, a new feature in the latest version of MDS.

What is the MDS Policy Requirements Endpoint

This new endpoint in the Policy API allows agencies to express program data requirements digitally, allowing both operators and the public to see what MDS and GBFS versions, APIs, endpoints, and fields are needed. Proposed by Ride Report – with feedback from MDS working group participants like PBOT, SFMTA, Superpedestrian, and Spin – this feature allows cities to publicly express their data requirements in a standardized, digital form.

Examples of city program requirement PDFs

Cities currently communicate data sharing requirements with providers very differently via program permit PDFs.


Cities have traditionally communicated data sharing requirements to providers and the public through written regulations or other non-standardized formats. This makes shared mobility services harder to administer, with providers struggling to know what cities require, and cities challenged with communicating policy changes. Using the new Requirements feature (or, endpoint), cities can specify the parts of MDS, GBFS, and other specifications they intend to use, down to the level of specific APIs, endpoints, and individual fields.

Examples of asking for the Provider Trips endpoint using Requirements in three different ways.

Examples of asking for the Provider Trips endpoint using Requirements in three different ways.


This new endpoint provides a clearer, more scalable solution for operators and cities by utilizing a common digital language. It makes MDS even more flexible by letting agencies tailor the data they get to their specific use cases, and it increases privacy by allowing agencies to ask for only the data they need. Plus, public endpoints like this encourage discovery, transparency, and accountability, as agencies can surface their data collection requirements and policies using a standardized, public mechanism.

MDS: A Kit of Parts

MDS has been designed from the beginning to be a modular kit-of-parts. Regulatory agencies can use the components of the API that are appropriate for their needs. How cities use MDS depends on a variety of factors: their transportation goals, existing services and infrastructure, use cases, and the unique needs of their communities. Most agencies will not use all parts of MDS, and instead can use Requirements to clearly choose only what they need. The full suite of available APIs and endpoints can be seen here.

MDS APIs and Endpoints data from Operators and Cities

The full suite of MDS kit-of-parts optional APIs and endpoints

Policy Requirements in Action

To understand how a city might implement this new feature, it helps to look at examples of Policy Requirements in action.

Example 1: Only Provider Vehicles

Some cities may only need to know the current location, state, and properties of vehicles at rest in their jurisdictions, as a more detailed complement to public GBFS feeds. In this case they could specify only needing the /vehicles endpoint in Provider. Full example details and code in spec.

Example 1: Only using one endpoint (/vehicles) from within the Provider API

Example 2: Trips with Limited Data

A city may want to use an existing endpoint, but for legal or privacy reasons may not require all the data it usually provides. They could ask for historic Provider /trips without the typically required device_id, vehicle_id, start_time, end_time, and route array fields, and ensure the optional parking_verification_url photo URL is not being returned in the endpoint. These fields are marked as ‘disallowed’ so they should not be returned by providers. Full example details and code in spec.

Example 2: Only using one endpoint (/vehicles) from within the Provider API, with some required fields not returned.

Example 3: Publishing and Receiving MDS data

To support more robust use cases and data analysis for a pilot project, a city could request some Provider endpoints, announce the locations of city-published public endpoints in Policy, Geography, Jurisdiction, and note their use of MDS Metrics. Full example details and code in spec.

Policy Requirements example 3

Example 3: Sending and receiving a variety of MDS endpoints for more advanced use cases

More Examples and Details

The Future of Digital Policy

This new feature is currently in beta along with several other new features that have been added to MDS in recent releases. As with all beta features, the OMF encourages real world use and feedback to refine the feature for future releases. If you are a city, company, or individual who is looking to share feedback and help shape the future of MDS, learn more about how to get involved.

Additional enhancements are under discussion already, like specifying exactly what use cases are supported with each endpoint, and enumerating internal data protection policies like data retention and data sharing. Also being discussed is the concept of a parallel endpoint in Provider to allow public publishing of a manifest with operational information. With the MDS Working Group focused on further improving Policy in MDS 2.0, all of these ideas and more will be discussed and evaluated by the community.

The MDS Working Group is open to both OMF members and individual contributors to help refine these proposed enhancements. To participate:

  • Review the MDS Working Group wiki to familiarize yourself with the group’s work
  • Get announcements and review meeting agendas from the MDS mailing list
  • Join bi-weekly meetings (Thursdays, 12pm ET) to discuss issues and hear from other contributors
  • Follow progress and chime in on our MDS repository
Related Posts
Announcing MDS 1.2.0

The 1.2.0 release adds new features that support privacy and Read more

Introducing Task Forces for MDS 2.0 Development

The MDS Working Group Steering Committee has announced the creation Read more

MDS & Data Privacy at the OMF

Learn more about the OMF’s work to support and enhance Read more


1 Step 1
FormCraft - WordPress form builder

Pin It on Pinterest