openmobilityfoundation / mds-openapi

OpenAPI description for MDS data feeds, managed by the Open Mobility Foundation.

Mobility Data Specification OpenAPI

The Mobility Data Specification (MDS), a project of the Open Mobility Foundation (OMF), is a data standard to enable right-of-way regulation and two-way communication between mobility companies and local governments.

This is the OpenAPI description for MDS data feeds, managed by the Open Mobility Foundation.

Online documentation is available on Stoplight.

MDS versions are organized by branches starting with a branch for v2.0.

Python project

A small Python project defined in pyproject.toml supports the schema development process.

# install the project and its dependencies
pip install -e .

Schema validation

Tests written in pytest check various components of the schemas. These tests can be run locally, and also run in GitHub Actions on commits to this repository.

# run the tests with pytest from the root of the repo
pytest

Notebooks

Jupyter Notebooks to help with one-time data cleanups and issue checking.

# install the 'notebooks' extras
pip install -e .[notebooks]

License

The MDS OpenAPI, like MDS itself, is licensed under Creative Commons Attribution 4.0 International Public License

mds-openapi's Issues

Make sure /entity/{entity_id} endpoints return an array of length 1

And disallow paging.

Jurisdiction API

Spec description: https://github.com/openmobilityfoundation/mobility-data-specification/tree/release-2.0.0/jurisdiction

Endpoints

• /jurisdictions: GET
• /jurisdictions.json: GET
• /jurisdictions/{jurisdiction_id}: GET

Data requirements

• jurisdiction
• modes enum

Provider API

Spec description: https://github.com/openmobilityfoundation/mobility-data-specification/tree/release-2.0.0/provider

Endpoints

• /vehicles
• /vehicles/{device_id}
• /vehicles/status
• /vehicles/status/{device_id}
• /events/historical
• /events/recent
• /trips
• /telemetry
• /stops
• /stops/{stop_id}
• /reports

Data requirements

• Standard MDS payload wrapper
• Optional paging
• Optional data latency
• journey_attributes
  • car-share: journey_id
  • car-share.trip: reservation_id
  • passenger-services: journey_id
  • passenger-services.trip: shift_id
  • delivery-robots: journey_id
• Conditional trip_ids
  • micromobility.event.event_types: trip_start, trip_end, trip_cancel, trip_enter_jurisdiction, or trip_leave_jurisdiction.
  • passenger-services.event.event_types: reservation_start, reservation_stop, trip_start, trip_pause, trip_resume, trip_end,trip_cancel, customer_cancellation, provider_cancellation, driver_cancellation, trip_enter_jurisdiction, trip_leave_jurisdiction
  • delivery-robots.event.event_types: reservation_start, reservation_stop, trip_start, trip_pause, trip_resume, trip_end,trip_cancel, customer_cancellation, provider_cancellation, driver_cancellation, trip_enter_jurisdiction or trip_leave_jurisdiction
• Conditional event_geographies on Event
• State machine transitions

Agency GET endpoints return MDS version in responses

Agency GET endpoints return their data payload, and optionally the JSON API pagination fields, e.g. for Vehicles:

{
    "vehicles": [ ... ],
    "links": {
        "first": "https://...",
        "last": "https://...",
        "prev": "https://...",
        "next": "https://..."
    }
}

Should the MDS version be included in this response? Like it is for Provider, Policy, Jurisdiction responses?

{
    "version": "2.0.0",
    "vehicles": [ ... ],
    "links": {
        "first": "https://...",
        "last": "https://...",
        "prev": "https://...",
        "next": "https://..."
    }
}

Use endpoint for summary field

E.g. in the Provider API doc we have:

/vehicles:
    get:
      operationId: get-vehicles
      description: Get a list of known vehicles, with properties that do not change often.
      summary: Get near-realtime vehicle information.

In the Stoplight menu, this looks like (notice some items are cut off):

Instead reuse the endpoint name in the summary field:

/vehicles:
    get:
      operationId: get-vehicles
      description: Get a list of known vehicles, with properties that do not change often.
      summary: /vehicles

This will reduce duplication within these OpenAPI docs and with the MDS docs, and it makes it much clearer in the Stoplight menu:

Is it possible to create somehow one OpenApi file?

I'm used to generate code using the swagger editor (https://editor.swagger.io/). Therefore the code should be in one file. Is it possible to obtain all the parts in one file?

Media type in OpenAPI

UPDATE

See comment below #34 (comment)

Original

MDS defines the media type application/vnd.mds+json for use in the (response) Content-type header, and for the purposes of version negotiation whereby a client could request a particular version:

Accept application/vnd.mds+json;version=2.0

The OpenAPI endpoints thus far have used application/vnd.mds+json as the Content-type and not required it as an Accept header.

Policy API

Spec description: https://github.com/openmobilityfoundation/mobility-data-specification/tree/release-2.0.0/policy

Endpoints

• /policies: GET
• /policies.json: GET
• /policies/{policy_id}: GET
• /value: GET (i.e. a sample Policy value URL endpoint)
• /requirements: GET

Data requirements

• policy
• rule
• requirements schema
  • metadata
  • programs
  • required_data_specs
  • required_apis / available_apis

Metrics API

Spec description: https://github.com/openmobilityfoundation/mobility-data-specification/tree/release-2.0.0/metrics

Endpoints

• /metrics: GET
• /metrics: POST

Data requirements

• ISO 8601 formatted strings with minute granularity supported and time zone (default UTC - YYYY-MM-DDTHH:mm or included offset (YYYY-MM-DDTHH:mm). Dates and times may also be specified using a numeric Unix epoch/timestamp
• ISO 8601 duration format strings (e.g. PT15M, PT1H, P1D)
• metrics GET response
• metrics POST parameters
• metrics POST response

Conflict in documentation regarding Trip - trip_type

So is trip_type one string or many strings in array ?

https://github.com/openmobilityfoundation/mobility-data-specification/blob/2.0.0/data-types.md#trips

https://github.com/openmobilityfoundation/mobility-data-specification/blob/2.0.0/modes/micromobility.md#trip-type

https://openmobilityfnd.stoplight.io/docs/mds-openapi/0f4cefcc4c183-trips

Add securitySchemes for Metrics

https://github.com/openmobilityfoundation/mobility-data-specification/blob/release-2.0.0/metrics/README.md#authorization

Create project in Stoplight

Follow approach in cds-openapi to connect Stoplight project to this GitHub repository via the @omf-service-account.

Policy rule conditional requirements

1. If rule_type != user, then rule_units required
2. Valid combinations of rule_type and rule_units
3. If rate_recurrence = *_time_unit, then rule_type = time

Fix mode trip_id requirements and event_types

RE: openmobilityfoundation/mobility-data-specification#843 (comment)

car-share

• trip_end
• trip_resume
• trip_start
• trip_stop

delivery-robots

• trip_end
• trip_resume
• trip_start
• trip_pause

micromobility

• trip_cancel
• trip_end
• trip_start

passenger-services

• trip_end
• trip_resume
• trip_start
• trip_stop

vehicle_type allowed values

Currently, vehicle_type is described here and shared between all the modes.
My question is should it be one list of allowed values ​​for all modes? I assume allowed values should be separated per each mode.

Seems like it should be separated to each mode, like:

• bicycle is related to micromobility
• bus - passenger-services (?)
• cargo_bicycle - micromobility
• car - car-share
• delivery_robot - delivery-robots
• moped - micromobility
• motorcycle - micromobility (?)
• scooter_standing - micromobility
• scooter_seated - micromobility
• truck - car-share
• other - ...

Could you please review this moment?

Describe 400 for Provider endpoints with params

All Provider endpoints that accept parameters (either in the path or in query string) should define a 400 response code.

Agency API

Spec description: https://github.com/openmobilityfoundation/mobility-data-specification/tree/release-2.0.0/agency

Endpoints

• /events: POST
  • Request body
  • Success body
  • Error body
• /reports: POST
  • Request body
  • Success body
  • Error body
• /stops: GET
• /stops/{stop_id}: GET
• /stops: POST, PUT
  • Request body
  • Success body
  • Error body
• /telemetry: POST
  • Request body
  • Success body
  • Error body
• /trips: POST
  • Request body
  • Success body
  • Error body
• /vehicles: POST, PUT
  • Request body
  • Success body
  • Error body
• /vehicles: GET
• /vehicles/{device_id}: GET
• /vehicles/status: GET
• /vehicles/status/{device_id}: GET

Data requirements

• Single error response
• Bulk responses
• Event errors
• Reports register errors
• Stop register errors
• Stop update errors
• Telemetry errors
• Trip errors

Create v2.0 branch

Requires the following issues to be complete:

• #6
• #7
• #8
• #9
• #10
• #11

Tasks

• Create a new branch from main, called v2.0
• Make the new branch the default branch in this repository
• In the Stoplight project, track the new branch and make it the default

Geography API

Spec description: https://github.com/openmobilityfoundation/mobility-data-specification/tree/release-2.0.0/geography

Endpoints

• /geographies: GET
• /geographies.json: GET
• /geographies/{geography_id}: GET

Data requirements

• geography
• geography.geography_json: GeoJSON FeatureCollection reference
• geography_type - this isn't actually an enum, but a list of recommended strings (implemented as examples)