From f3aa2e53f7369477ab98d5997a02f7854a82935b Mon Sep 17 00:00:00 2001 From: Muyi Zhou <141460500+Mu-yi-Zhou@users.noreply.github.com> Date: Tue, 8 Apr 2025 15:26:52 -0700 Subject: [PATCH 001/168] Update data-types.md Add service_start and service_end to Vehicle endpoint of Provider API Signed-off-by: Muyi Zhou <141460500+Mu-yi-Zhou@users.noreply.github.com> --- data-types.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/data-types.md b/data-types.md index 3f292be64..bc12925fe 100644 --- a/data-types.md +++ b/data-types.md @@ -34,6 +34,9 @@ A vehicle record is as follows: | `battery_capacity` | Integer | Required if Available | Capacity of battery expressed as milliamp hours (mAh) | | `fuel_capacity` | Integer | Required if Available | Capacity of fuel tank (liquid, solid, gaseous) expressed in liters | | `maximum_speed` | Integer | Required if Available | Maximum speed (kph) possible with vehicle under normal, flat incline, smooth surface conditions. Applicable if the device has a built-in or intelligent speed limiter/governor. | +|`service_start` |Timestamp | Required | Date/time the vehicle starts providing service | +|`service_end` |Timestamp | Required if Available | Date/time the vehicle stops providing service. Required if the vehicle is retired | + [Top][toc] From 4c9976aa90af491396938d964ef6575782e1e751 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 25 Apr 2025 14:41:13 -0400 Subject: [PATCH 002/168] Making start conditionally required so not breaking Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- data-types.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/data-types.md b/data-types.md index bc12925fe..54a1ba4b1 100644 --- a/data-types.md +++ b/data-types.md @@ -34,7 +34,7 @@ A vehicle record is as follows: | `battery_capacity` | Integer | Required if Available | Capacity of battery expressed as milliamp hours (mAh) | | `fuel_capacity` | Integer | Required if Available | Capacity of fuel tank (liquid, solid, gaseous) expressed in liters | | `maximum_speed` | Integer | Required if Available | Maximum speed (kph) possible with vehicle under normal, flat incline, smooth surface conditions. Applicable if the device has a built-in or intelligent speed limiter/governor. | -|`service_start` |Timestamp | Required | Date/time the vehicle starts providing service | +|`service_start` |Timestamp | Conditionally Required | Date/time the vehicle starts providing service. Required if asked for by public agency. | |`service_end` |Timestamp | Required if Available | Date/time the vehicle stops providing service. Required if the vehicle is retired | From 34d70de2b8bdd5552ce3405cc9f1fe71d4f9f2f7 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 4 Jul 2025 16:46:54 -0400 Subject: [PATCH 003/168] Adding back fixed route fields Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- data-types.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/data-types.md b/data-types.md index 2a5299b57..942012196 100644 --- a/data-types.md +++ b/data-types.md @@ -115,6 +115,7 @@ Events represent changes in vehicle status. | `trip_ids` | UUID[] | [Required if Applicable](./general-information.md#required-if-applicable-fields) | Trip UUIDs (foreign key to /trips endpoint), required if `event_types` contains `trip_start`, `trip_end`, `trip_cancel`, `trip_enter_jurisdiction`, or `trip_leave_jurisdiction` | | `stop_id` | UUID | [Required if Applicable](./general-information.md#required-if-applicable-fields) | Stop that the vehicle is currently located at. See [Stops][stops] | | `associated_ticket` | String | [Optional](./general-information.md#optional-fields) | Identifier for an associated ticket inside an Agency-maintained 311 or CRM system | +| `gtfs_stop_id` | String | [Optional](./general-information.md#optional-fields) | A unique stop ID to be recorded when a vehicle makes a stop event at a location. Matches [GTFS](https://gtfs.org/documentation/schedule/reference/) `stop_id` | ### Event Times @@ -141,6 +142,7 @@ A standard point of vehicle telemetry. References to latitude and longitude impl | `battery_percent` | Integer | [Required if Applicable](./general-information.md#required-if-applicable-fields) | Percent battery charge of vehicle, expressed between 0 and 100 | | `fuel_percent` | Integer | [Required if Applicable](./general-information.md#required-if-applicable-fields) | Percent fuel in vehicle, expressed between 0 and 100 | | `tipped_over` | Boolean | Required if Known | If detectable and known, is the device tipped over or not? Default is 'false'. | +| `gtfs_stop_id` | String | [Optional](./general-information.md#optional-fields) | A unique stop ID to be recorded when a vehicle makes a stop event at a location. Matches [GTFS](https://gtfs.org/documentation/schedule/reference/) `stop_id` | ### GPS Data @@ -238,6 +240,8 @@ A Trip is defined by the following structure: | `standard_cost` | Integer | [Optional](./general-information.md#optional-fields) | The cost, in the currency defined in `currency`, to perform that trip in the standard operation of the System (see [Costs & Currencies][costs-and-currencies]) | | `actual_cost` | Integer | [Optional](./general-information.md#optional-fields) | The actual cost, in the currency defined in `currency`, paid by the customer of the *mobility as a service* provider (see [Costs & Currencies][costs-and-currencies]) | | `currency` | String | [Optional](./general-information.md#optional-fields), USD cents is implied if null.| An [ISO 4217 Alphabetic Currency Code][iso4217] representing the currency of the payee (see [Costs & Currencies][costs-and-currencies]) | +| `gtfs_trip_id` | String | Required if Applicable | A unique trip ID for the associated scheduled GTFS route-trip. Matches [GTFS](https://gtfs.org/documentation/schedule/reference/) `trip_id` in the trips.txt and other files.| +| `gtfs_api_url` | URL | Required if Applicable | Full URL to the location where the associated [GTFS](https://gtfs.org/documentation/schedule/reference/) dataset zip files are located. | [Top][toc] From 821fba0409af5387e5cc7759461fb37b597bfc91 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 4 Jul 2025 18:53:33 -0400 Subject: [PATCH 004/168] Add Incidents data object Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- data-types.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/data-types.md b/data-types.md index 942012196..cd5bb6f47 100644 --- a/data-types.md +++ b/data-types.md @@ -15,6 +15,7 @@ This MDS data types page catalogs the objects (fields, types, requirements, desc - [Stops](#stops) - [Stop Status](#stop-status) - [Trips](#trips) +- [Incidents](#incidents) - [Reports](#reports) ## Vehicles @@ -245,6 +246,23 @@ A Trip is defined by the following structure: [Top][toc] +## Incidents + + Incidents are used in both [Provider](/provider#stops) and [Agency](/agency#stops) telemetry data, whether on or off a Trip. + +| Field | Type | Required/Optional | Comments | +| ---- | ---- | ---- | ---- | +| `incident_id` | UUID | Required | ID used for uniquely identifying an Incident | +| `incident_type` | Enum | Required | The type of incident. One of `unplanned_stop`, `remote_takeover`, `tip_over`, `harsh_stopping`, `harsh_starting`, `near_miss`, `vandalism`, `crash`. | +| `description` | String | Optional | Text description of the incident. | +| `severity` | String | Optional | Description of the severity of the incident. | +| `report_id` | String | Optional | Identifier of an external report, from a police report, citation, internal system, service request, etc. The report source is communicated by the operator to the agency outside of MDS. | +| `report_type` | String | Optional | Description of the type of report referenced by the `report_id`, eg. police, customer, remote operator, 311 call, etc. | +| `contact_info` | String | Optional | Description of any relevant contact information about the incident the operator can provide. | +| `preliminary` | Boolean | Optional | If `true`, then this information in this Incident is only preliminary, with more details and/or validation coming at a later date. If 'false`, the information provided here is deemed valed with no more updates expected. | + +[Top][toc] + ## Reports A Report is defined by the following structure: From 119353800ac8616d3f3723a07147f7c5367e08b2 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 4 Jul 2025 19:30:29 -0400 Subject: [PATCH 005/168] Added publication and updated time to Incident Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- data-types.md | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/data-types.md b/data-types.md index cd5bb6f47..b2d1d7fd8 100644 --- a/data-types.md +++ b/data-types.md @@ -250,16 +250,18 @@ A Trip is defined by the following structure: Incidents are used in both [Provider](/provider#stops) and [Agency](/agency#stops) telemetry data, whether on or off a Trip. -| Field | Type | Required/Optional | Comments | -| ---- | ---- | ---- | ---- | -| `incident_id` | UUID | Required | ID used for uniquely identifying an Incident | -| `incident_type` | Enum | Required | The type of incident. One of `unplanned_stop`, `remote_takeover`, `tip_over`, `harsh_stopping`, `harsh_starting`, `near_miss`, `vandalism`, `crash`. | -| `description` | String | Optional | Text description of the incident. | -| `severity` | String | Optional | Description of the severity of the incident. | -| `report_id` | String | Optional | Identifier of an external report, from a police report, citation, internal system, service request, etc. The report source is communicated by the operator to the agency outside of MDS. | -| `report_type` | String | Optional | Description of the type of report referenced by the `report_id`, eg. police, customer, remote operator, 311 call, etc. | -| `contact_info` | String | Optional | Description of any relevant contact information about the incident the operator can provide. | -| `preliminary` | Boolean | Optional | If `true`, then this information in this Incident is only preliminary, with more details and/or validation coming at a later date. If 'false`, the information provided here is deemed valed with no more updates expected. | +| Field | Type | Required/Optional | Comments | +| ---- | ---- | ---- | ---- | +| `incident_id` | UUID | Required | ID used for uniquely identifying an Incident. | +| `incident_type` | Enum | Required | The type of incident. One of `unplanned_stop`, `remote_takeover`, `tip_over`, `harsh_stopping` (e.g. braking), `harsh_starting` (e.g. acceleration), `near_miss`, `vandalism`, `crash`. | +| `publication_time` | [Timestamp][ts] | Required | Date/time that incident became available through the Incident endpoint. The time of incident occurance is found in the Telemetry data points that reference this `incident_id`. | +| `last_updated` | [Timestamp][ts] | Required | Date/time that incident was last updated in the Incident endpoint. | +| `description` | String | Optional | Text description of the incident. | +| `severity` | String | Optional | Description of the severity of the incident. | +| `report_id` | String | Optional | Identifier of an external report, from a police report, citation, internal system, service request, etc. The report source is communicated by the operator to the agency outside of MDS. | +| `report_type` | String | Optional | Description of the type of report referenced by the `report_id`, eg. police, customer, remote operator, 311 call, etc. | +| `contact_info` | String | Optional | Description of any relevant contact information about the incident the operator can provide. | +| `preliminary` | Boolean | Optional | If `true`, then this information in this Incident is only preliminary, with more details and/or validation coming at a later date. If 'false`, the information provided here is deemed valed with no more updates expected. | [Top][toc] From f44e4455a91864065fb47222694497f1172d066b Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 4 Jul 2025 19:38:32 -0400 Subject: [PATCH 006/168] Add Incidents endpoint Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- provider/README.md | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/provider/README.md b/provider/README.md index 805638600..c08989e0a 100644 --- a/provider/README.md +++ b/provider/README.md @@ -32,6 +32,7 @@ This specification contains a data standard for *mobility as a service* provider * [Recent Events](#recent-events) * [Recent Events - Query Parameters](#recent-events---query-parameters) * [Stops](#stops) +* [Incidents](#incidents) * [Reports](#reports) * [Reports - Response](#reports---response) * [Reports - Example](#reports---example) @@ -526,6 +527,44 @@ See [Responses][responses], [Bulk Responses][bulk-responses], and [schema][schem [Top][toc] +## Incidents + +The `/incidents` endpoint is a feed of various incident data from vehicles and devices that are the public agency's jurisdition, and are connected to the [Telemetry](#telemetry) endpoint which includes geolocation with timestamp, and other information. Included if part of a [Trip](#trips), as long as any part of the trip [intersects][intersection] with the [municipality boundary][muni-boundary]. + +Incidents should be created as close to real-time as possible, and then updated when new information or changes happen. + +**Endpoint:** `/incidents` +**Method:** `GET` +**Schema:** See [`mds-openapi`](https://github.com/openmobilityfoundation/mds-openapi) repository for schema. +**Payload:** `{ "incidents": [] }`, an array of [Incidents][incidents] objects + +[Top][toc] + +### Incidents - Query Parameters + +| Query Parameter | Type | Expected Output | +| ----- | ---- | -------- | +| `incident_id` | UUID | Return details only about a specific incident. | +| `incident_type` | String | Return details only about a specific incident type. | +| `publication_start_time` | [timestamp][ts] | Incidents where `publication_start_time <= incident.publication_time` | +| `publication_end_time` | [timestamp][ts] | Incidents where `incident.publication_time < publication_end_time` | +| `last_updated_start` | [timestamp][ts] | Incidents where `last_updated_start <= incident.last_updated` | +| `last_updated_end` | [timestamp][ts] | Incidents where `incident.last_updated < last_updated_end` | + +#### Responses + +_Possible HTTP Status Codes_: +200, +400 (with parameter), +401, +406, +500 + +See [Responses][responses], [Bulk Responses][bulk-responses], and [schema][schema] for details. + +[Top][toc] + + ## Reports Reports are information that providers can send back to agencies containing aggregated data that is not contained within other MDS endpoints, like counts of special groups of riders. These supplemental reports are not a substitute for other MDS Provider endpoints. @@ -577,6 +616,7 @@ See [Provider examples](examples.md#reports). [geography-driven-events]: /general-information.md#geography-driven-events [geojson-feature-collection]: https://tools.ietf.org/html/rfc7946#section-3.3 [iana]: https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml +[incidents]: /data-types.md#incidents [intersection]: /general-information.md#intersection-operation [iso4217]: https://en.wikipedia.org/wiki/ISO_4217#Active_codes [json-api-pagination]: http://jsonapi.org/format/#fetching-pagination From 52d24638f795699483614a7b8c4333f08a35559d Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 4 Jul 2025 19:42:11 -0400 Subject: [PATCH 007/168] Updated TOC for Incidents Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- provider/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/provider/README.md b/provider/README.md index c08989e0a..3e0ba71eb 100644 --- a/provider/README.md +++ b/provider/README.md @@ -33,6 +33,7 @@ This specification contains a data standard for *mobility as a service* provider * [Recent Events - Query Parameters](#recent-events---query-parameters) * [Stops](#stops) * [Incidents](#incidents) + * [Incidents - Query Parameters](#incidents---query-parameters) * [Reports](#reports) * [Reports - Response](#reports---response) * [Reports - Example](#reports---example) From 34d813941a38a12dbd9eceb963ffd209a717dd3f Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 4 Jul 2025 19:53:48 -0400 Subject: [PATCH 008/168] Add Incidents to Agency Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- agency/README.md | 66 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) diff --git a/agency/README.md b/agency/README.md index 338823048..a56e4cb59 100644 --- a/agency/README.md +++ b/agency/README.md @@ -26,6 +26,9 @@ This specification contains a collection of RESTful APIs used to specify the dig * [Stops - Register](#stops---register) * [Stops - Update](#stops---update) * [Stops - Readback](#stops---readback) +* [Incidents](#incidents) + * [Incident - Create](#incident---create) + * [Incident - Update](#incident---update) * [Reports](#reports) * [Reports - Register](#reports---register) @@ -426,6 +429,69 @@ See [Responses][responses], [Bulk Responses][bulk-responses], and [schema][schem [Top][toc] +## Incidents + +The `/incidents` endpoints allow providers to create and update the details of incidents. + +### Incident - Create + +The `/incidents` create endpoint is used to create incident reports that occur with provider devices. + +**Endpoint**: `/incidents` +**Method:** `POST` +**Payload:** An array of [Incidents](/data-types.md#incidents) + +#### Responses + +_Possible HTTP Status Codes_: +201, +400, +401, +406, +409, +500 + +See [Responses][responses], [Bulk Responses][bulk-responses], and [schema][schema] for details. + +[Top][toc] + +#### Error Codes: + +| `error` | `error_description` | `error_details`[] | +| -------------------- | ------------------------------------------------- | ------------------------------- | +| `bad_param` | A validation error occurred | Array of parameters with errors | +| `missing_param` | A required parameter is missing | Array of missing parameters | +| `already_created` | An incident with `incident_id` is already careated | | + +### Incident - Update + +The `/incidents` update endpoint is used to change incident information, should some aspect of the incident change. Each incident must already be created. + +**Endpoint**: `/incidents` +**Method:** `PUT` +**Payload:** An array of [Incidents](/data-types.md#incidents) + +#### Responses + +_Possible HTTP Status Codes_: +200, +400, +401, +406, +409, +500 + +See [Responses][responses], [Bulk Responses][bulk-responses], and [schema][schema] for details. + +#### Error Codes: + +| `error` | `error_description` | `error_details`[] | +| -------------------- | ------------------------------------------------- | ------------------------------- | +| `bad_param` | A validation error occurred | Array of parameters with errors | +| `unregistered` | This `incident_id` is unregistered | | + +[Top][toc] + ## Reports Reports are information that providers can send back to agencies containing aggregated data that is not contained within other MDS endpoints, like counts of special groups of riders. These supplemental reports are not a substitute for other MDS Provider endpoints. From dc103aa8eb83def52cc80baebb9d3bcda0bbdd99 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 4 Jul 2025 20:09:20 -0400 Subject: [PATCH 009/168] Added Incident IDs to Telemetry object Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- data-types.md | 1 + 1 file changed, 1 insertion(+) diff --git a/data-types.md b/data-types.md index b2d1d7fd8..83f6da67d 100644 --- a/data-types.md +++ b/data-types.md @@ -144,6 +144,7 @@ A standard point of vehicle telemetry. References to latitude and longitude impl | `fuel_percent` | Integer | [Required if Applicable](./general-information.md#required-if-applicable-fields) | Percent fuel in vehicle, expressed between 0 and 100 | | `tipped_over` | Boolean | Required if Known | If detectable and known, is the device tipped over or not? Default is 'false'. | | `gtfs_stop_id` | String | [Optional](./general-information.md#optional-fields) | A unique stop ID to be recorded when a vehicle makes a stop event at a location. Matches [GTFS](https://gtfs.org/documentation/schedule/reference/) `stop_id` | +| `incident_ids` | Array of UUIDs | Optional | Array of one or more [Incident](#incident) IDs that are connected to this telemetry data point. | ### GPS Data From ef747617f6411cbb90e38a7288eb96a73bd405ef Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 4 Jul 2025 20:10:28 -0400 Subject: [PATCH 010/168] Update to data type and link Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- data-types.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/data-types.md b/data-types.md index 83f6da67d..9fc5ed0a5 100644 --- a/data-types.md +++ b/data-types.md @@ -144,7 +144,7 @@ A standard point of vehicle telemetry. References to latitude and longitude impl | `fuel_percent` | Integer | [Required if Applicable](./general-information.md#required-if-applicable-fields) | Percent fuel in vehicle, expressed between 0 and 100 | | `tipped_over` | Boolean | Required if Known | If detectable and known, is the device tipped over or not? Default is 'false'. | | `gtfs_stop_id` | String | [Optional](./general-information.md#optional-fields) | A unique stop ID to be recorded when a vehicle makes a stop event at a location. Matches [GTFS](https://gtfs.org/documentation/schedule/reference/) `stop_id` | -| `incident_ids` | Array of UUIDs | Optional | Array of one or more [Incident](#incident) IDs that are connected to this telemetry data point. | +| `incident_ids` | UUID[] | Optional | Array of one or more [Incident](#incidents) IDs that are connected to this telemetry data point. | ### GPS Data From 205ea7c96c37b8512a8bf8aebab4904a4a52bacc Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 4 Jul 2025 20:12:32 -0400 Subject: [PATCH 011/168] Update links to Incident endpoints Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- data-types.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/data-types.md b/data-types.md index 9fc5ed0a5..21f6b7a16 100644 --- a/data-types.md +++ b/data-types.md @@ -249,7 +249,7 @@ A Trip is defined by the following structure: ## Incidents - Incidents are used in both [Provider](/provider#stops) and [Agency](/agency#stops) telemetry data, whether on or off a Trip. + Incidents are used in both [Provider](/provider#incidents) and [Agency](/agency#incidents) telemetry data, whether on or off a Trip. | Field | Type | Required/Optional | Comments | | ---- | ---- | ---- | ---- | From 3661273425a803d60f9f4781c508111017565cd3 Mon Sep 17 00:00:00 2001 From: Marcus V Date: Tue, 15 Jul 2025 13:48:45 -0700 Subject: [PATCH 012/168] Updated providers.csv Added new providers from issue - Add Provider ID: New SFMTA Commuter Shuttle Operators #942 Signed-off-by: Marcus V --- providers.csv | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/providers.csv b/providers.csv index 642cc0e5a..c0d4168d6 100644 --- a/providers.csv +++ b/providers.csv @@ -75,4 +75,5 @@ Tripshot,passenger-services,e154cf80-df89-4d7e-b5e7-2ee8050a6e9c,https://www.tri Trakk,passenger-services,6a907d9d-1e3c-4cb6-991c-f9738d30337b,https://gettrakk.com/,, Swoop,passenger-services,08ad2b21-8115-4d18-874f-48082e8e50fb,https://www.swoopapp.com/,, GoSharing,micromobility,1f859479-4427-4f52-8220-05c786436314,https://www.binbin.tech/,https://complianceapi.binbinapp.com/api/mds/,https://complianceapi.binbinapp.com/api/gbfs/ - +Mosaic Global,passenger-services,74ba2b64-c44f-474a-afbd-c2030fe162a6,https://mosaicglobaltransportation.com/,, +Code3,passenger-services,b49a32d7-a418-4a6a-9f81-b5227d6c7ef8,https://code3transportation.com/,, From 4a5c5c8a3310d76959ace3b0e47fcea8201b2a19 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 21 Jul 2025 14:16:16 -0400 Subject: [PATCH 013/168] Added more incident timestamps Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- data-types.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/data-types.md b/data-types.md index 21f6b7a16..e6dfeca4a 100644 --- a/data-types.md +++ b/data-types.md @@ -255,7 +255,9 @@ A Trip is defined by the following structure: | ---- | ---- | ---- | ---- | | `incident_id` | UUID | Required | ID used for uniquely identifying an Incident. | | `incident_type` | Enum | Required | The type of incident. One of `unplanned_stop`, `remote_takeover`, `tip_over`, `harsh_stopping` (e.g. braking), `harsh_starting` (e.g. acceleration), `near_miss`, `vandalism`, `crash`. | -| `publication_time` | [Timestamp][ts] | Required | Date/time that incident became available through the Incident endpoint. The time of incident occurance is found in the Telemetry data points that reference this `incident_id`. | +| `incident_time` | [Timestamp][ts] | Required | Date/time that incident first occurred. Note that this timestamp of the incident first occurance is independent of one or more Telemetry timestamps referenced via `incident_id`. Note that more frequent telemetry data points may be required when an incident is first discovered and occuring. | +| `discovery_time` | [Timestamp][ts] | Required | Date/time that incident was first discovered by the operator. This may be at the same moment of the `incident_time`, or may have been discovered later. | +| `publication_time` | [Timestamp][ts] | Required | Date/time that incident became first available through the Incident endpoint. | | `last_updated` | [Timestamp][ts] | Required | Date/time that incident was last updated in the Incident endpoint. | | `description` | String | Optional | Text description of the incident. | | `severity` | String | Optional | Description of the severity of the incident. | From 00cd6c28a0baf086a857e5064b608dc0adfec651 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 21 Jul 2025 14:36:38 -0400 Subject: [PATCH 014/168] Added medical dispatch and transport Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- data-types.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/data-types.md b/data-types.md index e6dfeca4a..f2c1f825a 100644 --- a/data-types.md +++ b/data-types.md @@ -254,13 +254,15 @@ A Trip is defined by the following structure: | Field | Type | Required/Optional | Comments | | ---- | ---- | ---- | ---- | | `incident_id` | UUID | Required | ID used for uniquely identifying an Incident. | -| `incident_type` | Enum | Required | The type of incident. One of `unplanned_stop`, `remote_takeover`, `tip_over`, `harsh_stopping` (e.g. braking), `harsh_starting` (e.g. acceleration), `near_miss`, `vandalism`, `crash`. | +| `incident_type` | Enum | Required | The type of incident. One of `unplanned_stop`, `remote_takeover`, `ads_engaged` (Automated Driving System), `ads_disengaged`, `tip_over`, `harsh_stopping` (e.g. braking), `harsh_starting` (e.g. acceleration), `near_miss`, `vandalism`, `theft`, `crash`. Exact definitions, and when and if which incident types are sent, come from the agency. | | `incident_time` | [Timestamp][ts] | Required | Date/time that incident first occurred. Note that this timestamp of the incident first occurance is independent of one or more Telemetry timestamps referenced via `incident_id`. Note that more frequent telemetry data points may be required when an incident is first discovered and occuring. | | `discovery_time` | [Timestamp][ts] | Required | Date/time that incident was first discovered by the operator. This may be at the same moment of the `incident_time`, or may have been discovered later. | -| `publication_time` | [Timestamp][ts] | Required | Date/time that incident became first available through the Incident endpoint. | +| `publication_time` | [Timestamp][ts] | Required | Date/time that incident became first available to an agency through an Incident endpoint. | | `last_updated` | [Timestamp][ts] | Required | Date/time that incident was last updated in the Incident endpoint. | | `description` | String | Optional | Text description of the incident. | -| `severity` | String | Optional | Description of the severity of the incident. | +| `severity` | String | Optional | Text description of the severity of the incident. | +| `medical_dispatch` | Boolean | Optional | If `true`, a medical dispatch occured connected to the incident. | +| `medical_transport` | Boolean | Optional | If `true`, one or more individuals was transported via an ambulance or emergency response vehicle because of the incident. | | `report_id` | String | Optional | Identifier of an external report, from a police report, citation, internal system, service request, etc. The report source is communicated by the operator to the agency outside of MDS. | | `report_type` | String | Optional | Description of the type of report referenced by the `report_id`, eg. police, customer, remote operator, 311 call, etc. | | `contact_info` | String | Optional | Description of any relevant contact information about the incident the operator can provide. | From ff6c63b75ed9248bf65f2e3f226b9e316fa4ba0f Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 21 Jul 2025 14:39:04 -0400 Subject: [PATCH 015/168] Formatting fixes Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- data-types.md | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/data-types.md b/data-types.md index f2c1f825a..d023b8534 100644 --- a/data-types.md +++ b/data-types.md @@ -251,22 +251,22 @@ A Trip is defined by the following structure: Incidents are used in both [Provider](/provider#incidents) and [Agency](/agency#incidents) telemetry data, whether on or off a Trip. -| Field | Type | Required/Optional | Comments | -| ---- | ---- | ---- | ---- | -| `incident_id` | UUID | Required | ID used for uniquely identifying an Incident. | -| `incident_type` | Enum | Required | The type of incident. One of `unplanned_stop`, `remote_takeover`, `ads_engaged` (Automated Driving System), `ads_disengaged`, `tip_over`, `harsh_stopping` (e.g. braking), `harsh_starting` (e.g. acceleration), `near_miss`, `vandalism`, `theft`, `crash`. Exact definitions, and when and if which incident types are sent, come from the agency. | -| `incident_time` | [Timestamp][ts] | Required | Date/time that incident first occurred. Note that this timestamp of the incident first occurance is independent of one or more Telemetry timestamps referenced via `incident_id`. Note that more frequent telemetry data points may be required when an incident is first discovered and occuring. | -| `discovery_time` | [Timestamp][ts] | Required | Date/time that incident was first discovered by the operator. This may be at the same moment of the `incident_time`, or may have been discovered later. | -| `publication_time` | [Timestamp][ts] | Required | Date/time that incident became first available to an agency through an Incident endpoint. | -| `last_updated` | [Timestamp][ts] | Required | Date/time that incident was last updated in the Incident endpoint. | -| `description` | String | Optional | Text description of the incident. | -| `severity` | String | Optional | Text description of the severity of the incident. | -| `medical_dispatch` | Boolean | Optional | If `true`, a medical dispatch occured connected to the incident. | -| `medical_transport` | Boolean | Optional | If `true`, one or more individuals was transported via an ambulance or emergency response vehicle because of the incident. | -| `report_id` | String | Optional | Identifier of an external report, from a police report, citation, internal system, service request, etc. The report source is communicated by the operator to the agency outside of MDS. | -| `report_type` | String | Optional | Description of the type of report referenced by the `report_id`, eg. police, customer, remote operator, 311 call, etc. | -| `contact_info` | String | Optional | Description of any relevant contact information about the incident the operator can provide. | -| `preliminary` | Boolean | Optional | If `true`, then this information in this Incident is only preliminary, with more details and/or validation coming at a later date. If 'false`, the information provided here is deemed valed with no more updates expected. | +| Field | Type | Required/Optional | Comments | +| ---- | ---- | ---- | ---- | +| `incident_id` | UUID | Required | ID used for uniquely identifying an Incident. | +| `incident_type` | Enum | Required | The type of incident. One of `unplanned_stop`, `remote_takeover`, `ads_engaged` (Automated Driving System), `ads_disengaged`, `tip_over`, `harsh_stopping` (e.g. braking), `harsh_starting` (e.g. acceleration), `near_miss`, `vandalism`, `theft`, `crash`. Exact definitions, and when and if which incident types are sent, come from the agency. | +| `incident_time` | [Timestamp][ts] | Required | Date/time that incident first occurred. Note that this timestamp of the incident first occurance is independent of one or more Telemetry timestamps referenced via `incident_id`. Note that more frequent telemetry data points may be required when an incident is first discovered and occuring. | +| `discovery_time` | [Timestamp][ts] | Required | Date/time that incident was first discovered by the operator. This may be at the same moment of the `incident_time`, or may have been discovered later. | +| `publication_time` | [Timestamp][ts] | Required | Date/time that incident became first available to an agency through an Incident endpoint. | +| `last_updated` | [Timestamp][ts] | Required | Date/time that incident was last updated in the Incident endpoint. | +| `description` | String | Optional | Text description of the incident. | +| `severity` | String | Optional | Text description of the severity of the incident. | +| `medical_dispatch` | Boolean | Optional | If `true`, a medical dispatch occured connected to the incident. | +| `medical_transport` | Boolean | Optional | If `true`, one or more individuals was transported via an ambulance or emergency response vehicle because of the incident. | +| `report_id` | String | Optional | Identifier of an external report, from a police report, citation, internal system, service request, etc. The report source is communicated by the operator to the agency outside of MDS. | +| `report_type` | String | Optional | Description of the type of report referenced by the `report_id`, eg. police, customer, remote operator, 311 call, etc. | +| `contact_info` | String | Optional | Description of any relevant contact information about the incident the operator can provide. | +| `preliminary` | Boolean | Optional | If `true`, then this information in this Incident is only preliminary, with more details and/or validation coming at a later date. If `false`, the information provided here is deemed valed with no more updates expected. | [Top][toc] From 703f2c4cb64ed8d7ee0a80b0bf8010771af24c51 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 21 Jul 2025 14:53:47 -0400 Subject: [PATCH 016/168] Added accelerometer data fields Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- data-types.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/data-types.md b/data-types.md index d023b8534..2865dee7d 100644 --- a/data-types.md +++ b/data-types.md @@ -148,6 +148,8 @@ A standard point of vehicle telemetry. References to latitude and longitude impl ### GPS Data +Includes GPS device data and data from other relevant sensors. + | Field | Type | Required/Optional | Field Description | | ---------- | -------------- | --------------------- | ------------------------------------------------------------ | | `lat` | Double | Required | Latitude of the location | @@ -155,9 +157,12 @@ A standard point of vehicle telemetry. References to latitude and longitude impl | `altitude` | Double | Required if Available | Altitude above mean sea level in meters | | `heading` | Double | Required if Available | Degrees - clockwise starting at 0 degrees at true North | | `speed` | Float | Required if Available | Estimated speed in meters / sec as reported by the GPS chipset | -| `horizontal_accuracy` | Float | Required if Available | Horizontal accuracy, in meters | -| `vertical_accuracy` | Float | Required if Available | Vertical accuracy, in meters | +| `horizontal_accuracy` | Float | Required if Available | Horizontal accuracy, in meters | +| `vertical_accuracy` | Float | Required if Available | Vertical accuracy, in meters | | `satellites` | Integer | Required if Available | Number of GPS or GNSS satellites | +| `accelerometer_x` | Float | Required if Available | The x-axis acceleration in G's (gravitational force). | +| `accelerometer_y` | Float | Required if Available | The y-axis acceleration in G's (gravitational force). | +| `accelerometer_z` | Float | Required if Available | The z-axis acceleration in G's (gravitational force). | [Top][toc] From 2571ad1d0ed031a17dfa60346f6c2fc820398f5a Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 21 Jul 2025 15:21:45 -0400 Subject: [PATCH 017/168] Added update_interval to Requirements Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- policy/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/policy/README.md b/policy/README.md index 82892835a..c55e4e371 100644 --- a/policy/README.md +++ b/policy/README.md @@ -790,6 +790,7 @@ You may also show which APIs, endpoints, and fields your agency is serving to pr | -------------------- | ----- | -------- | ----------------------------------- | | `api_name` | Text | Required | Name of the applicable API required. At least one API is required. APIs not listed will not be available to the agency. E.g. for MDS: 'provider', or 'agency'. For GBFS, this field is omitted since GBFS starts at the `endpoint` level. | | `endpoint_name` | Text | Required | Name of the required endpoint under the API. At least one endpoint is required. E.g. for MDS 'provider': 'trips' | +| `update_interval` | duration | [Optional](../general-information.md#optional-fields) | The expected minimum frequency with which this endpoint should could be updated. [ISO 8601 duration](https://en.wikipedia.org/wiki/ISO_8601#Durations). E.g. "T1M" | | `use_cases` | Object with Array | [Optional](../general-information.md#optional-fields) | The list of policy uses cases that this data standard's information covers for your program. Includes an `external_url` to a HTTP reference list or database (e.g. to the [OMF Use Case Database](https://airtable.com/shrPf4QvORkjZmHIs/tblzFfU6fxQm5Sdhm)), **and** an array of `ids` of each applicable use case (e.g. "OMF-MDS-31"). You may enumerate multiple external use case sources and ids. | [Top][toc] From 9b9470713c29a803b9dacf82459aabdee5d85586 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 21 Jul 2025 15:24:15 -0400 Subject: [PATCH 018/168] Clarified Telemetry update frequency Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- provider/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/provider/README.md b/provider/README.md index 3e0ba71eb..824dbca9c 100644 --- a/provider/README.md +++ b/provider/README.md @@ -355,7 +355,7 @@ See [Responses][responses], [Bulk Responses][bulk-responses], and [schema][schem ## Telemetry -The `/telemetry` endpoint is a feed of vehicle telemetry data for publishing all available location data. For privacy reasons, in-trip telemetry may be delayed at the discretion of the regulating body. +The `/telemetry` endpoint is a feed of vehicle telemetry data for publishing all available location data. Telemetry data occurs whether a vehicle is on a trip or not. The frequency of the telemetry data points is determined by the agency for the specific mobility program and the technical abilities of the vehicles, operator, connectivity, etc. This frequency may be clearly specified with the [Provider Requirements](../policy/README.md#requirement-apis) `update_interval` field. For privacy reasons, in-trip telemetry may be delayed at the discretion of the regulating agency. To represent [trip](#trip) telemetry, the data should include every [observed point][point-geo] in the trip, even those which occur outside the [municipality boundary][muni-boundary], as long as any part of the trip [intersects][intersection] with the [municipality boundary][muni-boundary]. From 9d039d3de075cda00aec3233e5008d4aa009caea Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 21 Jul 2025 15:26:40 -0400 Subject: [PATCH 019/168] Fixed link typo Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- provider/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/provider/README.md b/provider/README.md index 824dbca9c..361fafafa 100644 --- a/provider/README.md +++ b/provider/README.md @@ -355,7 +355,7 @@ See [Responses][responses], [Bulk Responses][bulk-responses], and [schema][schem ## Telemetry -The `/telemetry` endpoint is a feed of vehicle telemetry data for publishing all available location data. Telemetry data occurs whether a vehicle is on a trip or not. The frequency of the telemetry data points is determined by the agency for the specific mobility program and the technical abilities of the vehicles, operator, connectivity, etc. This frequency may be clearly specified with the [Provider Requirements](../policy/README.md#requirement-apis) `update_interval` field. For privacy reasons, in-trip telemetry may be delayed at the discretion of the regulating agency. +The `/telemetry` endpoint is a feed of vehicle telemetry data for publishing all available location data. Telemetry data occurs whether a vehicle is on a trip or not. The frequency of the telemetry data points is determined by the agency for the specific mobility program and the technical abilities of the vehicles, operator, connectivity, etc. This frequency may be clearly specified with the [Policy Requirements](../policy/README.md#requirement-apis) `update_interval` field. For privacy reasons, in-trip telemetry may be delayed at the discretion of the regulating agency. To represent [trip](#trip) telemetry, the data should include every [observed point][point-geo] in the trip, even those which occur outside the [municipality boundary][muni-boundary], as long as any part of the trip [intersects][intersection] with the [municipality boundary][muni-boundary]. From 8b6a09b93430d8c92c09c2d86488f5b6181bc62b Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 24 Jul 2025 15:21:02 -0400 Subject: [PATCH 020/168] Add external reference object Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- data-types.md | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/data-types.md b/data-types.md index 942012196..c314cafb1 100644 --- a/data-types.md +++ b/data-types.md @@ -16,7 +16,8 @@ This MDS data types page catalogs the objects (fields, types, requirements, desc - [Stop Status](#stop-status) - [Trips](#trips) - [Reports](#reports) - +- [External Reference](#external-reference) +- ## Vehicles A vehicle record is as follows: @@ -298,6 +299,22 @@ Other special group types may be added in future MDS releases as relevant agency [Top][toc] +## External Reference + +An External Reference object describes a specific feature from a data feed or API that is relevant to the curb place via an external reference. This allows CDS users to reference other data feeds, documents, websites, or URLs that impact or provide information, and see more details in an external URL. Data feeds can be any existing standard (MDS, WZDx, CWZ, GTFS, GBFS, CDS, etc), custom feed, document, web page, etc. + +An `external_reference` is a JSON *array* with the following fields within objects: + +| Name | Type | Required/Optional | Description | +| ------ | ------ | ------------------- | ------------- | +| `data_feed_url` | URL | Required | A web-accessible identifier for the source of the publicly or privately accessible data feed, document, website, or URL. This MUST be a full HTTPS URL pointing to a location which contains more information impacting or explaining the location or policy. | +| `name` | String | Optional | Name of the data feed for reference. E.g. "WZDx", "CWZ", "MDS", "GBFS", "GTFS", "CDS". | +| `public` | Boolean | Optional | Is this data feed able to be viewed with out any sort of authentication? If `true`, the `data_feed_url` is public. If `false`, the `data_feed_url` requires some sort of authentication, authorization, or API key to access. This is an informational field to set access expectations for the feed user, and does not provide any credentials directly unless explicitly contained in the `data_feed_url` URL string. | +| `identifier_name` | String | Optional | The name of the data field or object that is referenced by the unique `ids`. E.g. "id", "report_id", "trip_id", "vehicle_id", "RoadEventFeature", etc, if relevant and available in the URL. | +| `ids` | Array of Strings | Optional | An array of one or more **ids** from the data feed that impacts the use of or relationship to part of CDS, e.g. a curb zone, curb space, curb area, curb event, etc. The **ids** and their details are be found in the referenced `data_feed_url`. | + +[Top][toc] + [costs-and-currencies]: /general-information.md#costs-and-currencies [event-times]: #event-times [gbfs-station-info]: https://github.com/NABSA/gbfs/blob/master/gbfs.md#station_informationjson From 214f6ed6d814eed73a4eec9310dbeebb760e6a7d Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 24 Jul 2025 15:31:10 -0400 Subject: [PATCH 021/168] Adding external_references to Incidents Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- data-types.md | 1 + 1 file changed, 1 insertion(+) diff --git a/data-types.md b/data-types.md index 2865dee7d..d05bb98e3 100644 --- a/data-types.md +++ b/data-types.md @@ -270,6 +270,7 @@ A Trip is defined by the following structure: | `medical_transport` | Boolean | Optional | If `true`, one or more individuals was transported via an ambulance or emergency response vehicle because of the incident. | | `report_id` | String | Optional | Identifier of an external report, from a police report, citation, internal system, service request, etc. The report source is communicated by the operator to the agency outside of MDS. | | `report_type` | String | Optional | Description of the type of report referenced by the `report_id`, eg. police, customer, remote operator, 311 call, etc. | +| `external_references` | Array of [External Reference][external-reference] objects | Optional | One or more references to external data feeds impacting or related to this Incident, as they become available. | | `contact_info` | String | Optional | Description of any relevant contact information about the incident the operator can provide. | | `preliminary` | Boolean | Optional | If `true`, then this information in this Incident is only preliminary, with more details and/or validation coming at a later date. If `false`, the information provided here is deemed valed with no more updates expected. | From 51cd82db78b71004edd99caba15f4d4909f67ece Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 24 Jul 2025 15:41:26 -0400 Subject: [PATCH 022/168] Link shortcut Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- data-types.md | 1 + 1 file changed, 1 insertion(+) diff --git a/data-types.md b/data-types.md index d05bb98e3..fdcdba57d 100644 --- a/data-types.md +++ b/data-types.md @@ -331,6 +331,7 @@ Other special group types may be added in future MDS releases as relevant agency [costs-and-currencies]: /general-information.md#costs-and-currencies [event-times]: #event-times +[external-reference]: ../data-types.md#external-reference [gbfs-station-info]: https://github.com/NABSA/gbfs/blob/master/gbfs.md#station_informationjson [gbfs-station-status]: https://github.com/NABSA/gbfs/blob/master/gbfs.md#station_statusjson [geography-driven-events]: /general-information.md#geography-driven-events From 7ab2cf1ed257f1926573ae1f746f432d1e58546f Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 24 Jul 2025 15:42:03 -0400 Subject: [PATCH 023/168] External reference link update Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- data-types.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/data-types.md b/data-types.md index fdcdba57d..0997d00dc 100644 --- a/data-types.md +++ b/data-types.md @@ -331,7 +331,7 @@ Other special group types may be added in future MDS releases as relevant agency [costs-and-currencies]: /general-information.md#costs-and-currencies [event-times]: #event-times -[external-reference]: ../data-types.md#external-reference +[external-reference]: #external-reference [gbfs-station-info]: https://github.com/NABSA/gbfs/blob/master/gbfs.md#station_informationjson [gbfs-station-status]: https://github.com/NABSA/gbfs/blob/master/gbfs.md#station_statusjson [geography-driven-events]: /general-information.md#geography-driven-events From b7e5b7b3e084ff6d5519971e8448f08655f5f782 Mon Sep 17 00:00:00 2001 From: Pierre Bouffort <116758761+pierre-bouffort@users.noreply.github.com> Date: Wed, 30 Jul 2025 10:41:42 -0400 Subject: [PATCH 024/168] Update Authorization description to allow authentication.md Changing the Authorization paragraph Signed-off-by: Pierre Bouffort <116758761+pierre-bouffort@users.noreply.github.com> --- policy/README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/policy/README.md b/policy/README.md index 82892835a..87d09ad0b 100644 --- a/policy/README.md +++ b/policy/README.md @@ -80,7 +80,9 @@ See the [MDS Policy Examples](https://github.com/openmobilityfoundation/mobility ### Authorization -The Policy endpoints should be made public. Authorization is not required. Agencies may make reasonable accommodations to manage their endpoints, for example, using an API key that has a clear, public way to obtain - this can be useful for rate limiting requests, ensure proper use, tracking access per requestor, and/or customization of the Policy tailored to the requestor. +In most cases, the Policy endpoints should be made public. Authorization is not required in such cases. Agencies may make reasonable accommodations to manage their endpoints, for example, using an API key that has a clear, public way to obtain - this can be useful for rate limiting requests, ensure proper use, tracking access per requestor, and/or customization of the Policy tailored to the requestor. + +In some cases though, it can be justified to use Authorization for the Policy API (some agencies may decide to make it authenticated for privacy programs or functional purposes). Authorization may then be used for the Policy API. It should then rely on the standard Authorization methods used in other MDS APIs. [Top][toc] From 36aecc6055b73c7918b7a1e1f0ebc85f7765da1f Mon Sep 17 00:00:00 2001 From: Pierre Bouffort <116758761+pierre-bouffort@users.noreply.github.com> Date: Wed, 30 Jul 2025 10:52:49 -0400 Subject: [PATCH 025/168] Added the reference to general Authorization guidelines Added the reference to general Authorization guidelines Signed-off-by: Pierre Bouffort <116758761+pierre-bouffort@users.noreply.github.com> --- policy/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/policy/README.md b/policy/README.md index 87d09ad0b..9d6631601 100644 --- a/policy/README.md +++ b/policy/README.md @@ -82,7 +82,7 @@ See the [MDS Policy Examples](https://github.com/openmobilityfoundation/mobility In most cases, the Policy endpoints should be made public. Authorization is not required in such cases. Agencies may make reasonable accommodations to manage their endpoints, for example, using an API key that has a clear, public way to obtain - this can be useful for rate limiting requests, ensure proper use, tracking access per requestor, and/or customization of the Policy tailored to the requestor. -In some cases though, it can be justified to use Authorization for the Policy API (some agencies may decide to make it authenticated for privacy programs or functional purposes). Authorization may then be used for the Policy API. It should then rely on the standard Authorization methods used in other MDS APIs. +In some cases though, it can be justified to use Authorization for the Policy API (some agencies may decide to make it authenticated for privacy programs or functional purposes). Authorization may then be used for the Policy API. It should then rely on the standard [Authorization](../general-information.md#authorization) methods used in other MDS APIs. [Top][toc] From 5395f183d3ac7881b86c9b5a0e806b7cbe9edcb4 Mon Sep 17 00:00:00 2001 From: Pierre Bouffort <116758761+pierre-bouffort@users.noreply.github.com> Date: Wed, 30 Jul 2025 11:03:33 -0400 Subject: [PATCH 026/168] Adding distance rule types and relevant rule units to policy documentation Adding distance rule types and relevant rule units to policy documentation Signed-off-by: Pierre Bouffort <116758761+pierre-bouffort@users.noreply.github.com> --- policy/README.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/policy/README.md b/policy/README.md index 82892835a..58362924d 100644 --- a/policy/README.md +++ b/policy/README.md @@ -357,10 +357,11 @@ An individual `Rule` object is defined by the following fields: ### Rule Types -| Name | Description | +| Name | Description | | ------- | ------------------------------------------------------------------------------------------------------------- | | `count` | Fleet counts based on regions. Rule `minimum`/`maximum` refers to number of devices in [Rule Units](#rule-units). | | `time` | Individual limitations or fees based upon time spent in one or more vehicle states. Rule `minimum`/`maximum` refers to increments of time in [Rule Units](#rule-units). | +| `distance` | Individual limitations or fees based upon distance travelled during one or more trips. Rule `minimum`/`maximum` refers to increments of distance in [Rule Units](#rule-units). | | `speed` | Global or local speed limits. Rule `minimum`/`maximum` refers to speed in [Rule Units](#rule-units). | | `user` | Information for users, e.g. about helmet laws. Generally can't be enforced via events and telemetry. | @@ -374,6 +375,8 @@ An individual `Rule` object is defined by the following fields: | `minutes` | `time` | Minutes | | `hours` | `time` | Hours | | `days` | `time` | Days | +| `km` | `distance` | Kilometers | +| `miles` | `distance` | Miles | | `mph` | `speed` | Miles per hour | | `kph` | `speed` | Kilometers per hour | | `devices` | `count` | Devices | From 85c3b11c22a5aff7a1b1932c7a3d6648f67a939c Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Wed, 30 Jul 2025 11:46:23 -0400 Subject: [PATCH 027/168] Made space for Policies - Create Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- policy/README.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/policy/README.md b/policy/README.md index 82892835a..7515243b6 100644 --- a/policy/README.md +++ b/policy/README.md @@ -19,6 +19,8 @@ This specification describes the digital relationship between _mobility as a ser - [REST Endpoints](#rest-endpoints) - [Responses and Error Messages](#responses-and-error-messages) - [Policies](#policies) + - [Policies - Get](policies---get) + - [Policies - Create](policies---create) - [Geographies](#geographies) - [Requirements](#requirements) - [Flat Files](#flat-files) @@ -147,6 +149,8 @@ See the [Responses section][responses] for information on valid MDS response cod ### Policies +#### Policies - Get + **Endpoint**: `/policies/{policy_id}` **Method**: `GET` **Schema:** See [`mds-openapi`](https://github.com/openmobilityfoundation/mds-openapi) repository for schema. @@ -175,7 +179,7 @@ Policies will be returned in order of effective date (see schema below), with pa `provider_id` is an implicit parameter and will be encoded in the authentication mechanism, or a complete list of policies should be produced. If the Agency decides that Provider-specific policy documents should not be shared with other Providers (e.g. punitive policy in response to violations), an Agency should filter policy objects before serving them via this endpoint. -### Responses +**Responses** _Possible HTTP Status Codes_: 200, @@ -186,6 +190,16 @@ _Possible HTTP Status Codes_: See [Responses][responses], [Bulk Responses][bulk-responses], and [schema][schema] for details. +[Top][toc] + +#### Policies - Create + + + +**Responses** + + + [Top][toc] ### Geographies From 7c2eaa6f6e07faab77d0fe44e1d6f7bfd9f2c121 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Wed, 30 Jul 2025 12:06:22 -0400 Subject: [PATCH 028/168] Added descriptions Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- policy/README.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/policy/README.md b/policy/README.md index 7515243b6..0db6b8ded 100644 --- a/policy/README.md +++ b/policy/README.md @@ -19,8 +19,8 @@ This specification describes the digital relationship between _mobility as a ser - [REST Endpoints](#rest-endpoints) - [Responses and Error Messages](#responses-and-error-messages) - [Policies](#policies) - - [Policies - Get](policies---get) - - [Policies - Create](policies---create) + - [Policies - Get](#policies---get) + - [Policies - Create](#policies---create) - [Geographies](#geographies) - [Requirements](#requirements) - [Flat Files](#flat-files) @@ -151,6 +151,8 @@ See the [Responses section][responses] for information on valid MDS response cod #### Policies - Get +Allows operators to pull a list of active policies from agencies. + **Endpoint**: `/policies/{policy_id}` **Method**: `GET` **Schema:** See [`mds-openapi`](https://github.com/openmobilityfoundation/mds-openapi) repository for schema. @@ -194,7 +196,7 @@ See [Responses][responses], [Bulk Responses][bulk-responses], and [schema][schem #### Policies - Create - +Allows agencies to push a newly created policies from agencies. **Responses** From 437b38af5fe833e805ae690ec1f87252588bd0d8 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Wed, 30 Jul 2025 14:45:56 -0400 Subject: [PATCH 029/168] Added Policy push endpoint Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- policy/README.md | 28 ++++++++++++++++++++++++++-- 1 file changed, 26 insertions(+), 2 deletions(-) diff --git a/policy/README.md b/policy/README.md index 0db6b8ded..69a1c8ed5 100644 --- a/policy/README.md +++ b/policy/README.md @@ -151,7 +151,7 @@ See the [Responses section][responses] for information on valid MDS response cod #### Policies - Get -Allows operators to pull a list of active policies from agencies. +Allows operators to pull a list of active policies from agencies, similar to the Provider API. **Endpoint**: `/policies/{policy_id}` **Method**: `GET` @@ -196,11 +196,35 @@ See [Responses][responses], [Bulk Responses][bulk-responses], and [schema][schem #### Policies - Create -Allows agencies to push a newly created policies from agencies. +Allows agencies to push a newly created policies from agencies, similar to the Agency API. This push method creates the opportunity for near real-time communication of policy changes. Endpoint producers **SHALL** provide authorization for API endpoints via a bearer token based auth system specified in the MDS [Authorization section](/general-information.md#authorization), to allow handshake communication and response confirmation. + +**Endpoint**: `/policies/` +**Method:** `POST` +**Payload:** An array of [Policy](#policy) objects **Responses** +_Possible HTTP Status Codes_: +201, +400, +401, +406, +409, +500 + +See [Responses][responses], [Bulk Responses][bulk-responses], and [schema][schema] for details. + +[Top][toc] + +#### Error Codes: + +| `error` | `error_description` | `error_details`[] | +| -------------------- | -----------------------------------------------| ------------------------------- | +| `bad_param` | A validation error occurred | Array of parameters with errors | +| `missing_param` | A required parameter is missing | Array of missing parameters | +| `already_created` | A policy with `policy_id` is already created | | +Note that you may only create a new MDS Policy. Retired policies are simply referenced in `prev_policies`. See [Updating or Ending Policies](#updating-or-ending-policies) for details. [Top][toc] From 6c2743649f702c3ba227119b4076799ae0de67b1 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Wed, 30 Jul 2025 14:47:33 -0400 Subject: [PATCH 030/168] Formatting Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- policy/README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/policy/README.md b/policy/README.md index 69a1c8ed5..0d1322161 100644 --- a/policy/README.md +++ b/policy/README.md @@ -196,7 +196,9 @@ See [Responses][responses], [Bulk Responses][bulk-responses], and [schema][schem #### Policies - Create -Allows agencies to push a newly created policies from agencies, similar to the Agency API. This push method creates the opportunity for near real-time communication of policy changes. Endpoint producers **SHALL** provide authorization for API endpoints via a bearer token based auth system specified in the MDS [Authorization section](/general-information.md#authorization), to allow handshake communication and response confirmation. +Allows agencies to push a newly created policies to operators, similar to the Agency API. This push method creates the opportunity for near real-time communication of policy changes. + +Endpoint producers **SHALL** provide authorization for API endpoints via a bearer token based auth system specified in the MDS [Authorization section](/general-information.md#authorization), to allow handshake communication and response confirmation. **Endpoint**: `/policies/` **Method:** `POST` From 0a9faba689f3d616e9312f6eb347493c72f171d2 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Wed, 30 Jul 2025 14:54:01 -0400 Subject: [PATCH 031/168] Added 501 status Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- policy/README.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/policy/README.md b/policy/README.md index 0d1322161..d52a616cd 100644 --- a/policy/README.md +++ b/policy/README.md @@ -202,8 +202,11 @@ Endpoint producers **SHALL** provide authorization for API endpoints via a beare **Endpoint**: `/policies/` **Method:** `POST` +**Authorization**: required **Payload:** An array of [Policy](#policy) objects +_Optional endpoint, as required by public agencies; if not implemented, the server should reply with `501 Not Implemented`._ + **Responses** _Possible HTTP Status Codes_: @@ -212,7 +215,8 @@ _Possible HTTP Status Codes_: 401, 406, 409, -500 +500, +501 See [Responses][responses], [Bulk Responses][bulk-responses], and [schema][schema] for details. From fc4eb1e7d8a8fc82e21ecc8145543308421b345f Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Wed, 30 Jul 2025 15:07:45 -0400 Subject: [PATCH 032/168] External reference description additions Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- data-types.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/data-types.md b/data-types.md index 0997d00dc..e3a064650 100644 --- a/data-types.md +++ b/data-types.md @@ -270,7 +270,7 @@ A Trip is defined by the following structure: | `medical_transport` | Boolean | Optional | If `true`, one or more individuals was transported via an ambulance or emergency response vehicle because of the incident. | | `report_id` | String | Optional | Identifier of an external report, from a police report, citation, internal system, service request, etc. The report source is communicated by the operator to the agency outside of MDS. | | `report_type` | String | Optional | Description of the type of report referenced by the `report_id`, eg. police, customer, remote operator, 311 call, etc. | -| `external_references` | Array of [External Reference][external-reference] objects | Optional | One or more references to external data feeds impacting or related to this Incident, as they become available. | +| `external_references` | Array of [External Reference][external-reference] objects | Optional | One or more references to external data feeds, links, reports, or documents impacting or related to this Incident, as they become available. | | `contact_info` | String | Optional | Description of any relevant contact information about the incident the operator can provide. | | `preliminary` | Boolean | Optional | If `true`, then this information in this Incident is only preliminary, with more details and/or validation coming at a later date. If `false`, the information provided here is deemed valed with no more updates expected. | From 2ee863ac3a570b77147a433fa930be536a372e91 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Wed, 30 Jul 2025 15:16:07 -0400 Subject: [PATCH 033/168] Add external references to Trips, Events, Stops Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- data-types.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/data-types.md b/data-types.md index c314cafb1..b89529476 100644 --- a/data-types.md +++ b/data-types.md @@ -117,6 +117,7 @@ Events represent changes in vehicle status. | `stop_id` | UUID | [Required if Applicable](./general-information.md#required-if-applicable-fields) | Stop that the vehicle is currently located at. See [Stops][stops] | | `associated_ticket` | String | [Optional](./general-information.md#optional-fields) | Identifier for an associated ticket inside an Agency-maintained 311 or CRM system | | `gtfs_stop_id` | String | [Optional](./general-information.md#optional-fields) | A unique stop ID to be recorded when a vehicle makes a stop event at a location. Matches [GTFS](https://gtfs.org/documentation/schedule/reference/) `stop_id` | +| `external_references` | Array of [External Reference][external-reference] objects | Optional | One or more references impacting or related to this Trip. | ### Event Times @@ -188,6 +189,7 @@ Stops describe vehicle trip start and end locations in a pre-designated physical | `parent_stop` | UUID | [Optional](./general-information.md#optional-fields) | Describe a basic hierarchy of stops (e.g.a stop inside of a greater stop) | | `devices` | UUID[] | [Conditionally Required](./general-information.md#conditionally-required-fields) | List of device_ids for vehicles which are currently at this stop. Required if the program has station based availability requirements or service level agreements pertaining to stations. | | `image_url` | URL | [Optional](./general-information.md#optional-fields) | Link to an image, photo, or diagram of the stop. Could be used by providers to help riders find or use the stop. | +| `external_references` | Array of [External Reference][external-reference] objects | Optional | One or more references impacting or related to this Trip. | [Top][toc] @@ -243,6 +245,7 @@ A Trip is defined by the following structure: | `currency` | String | [Optional](./general-information.md#optional-fields), USD cents is implied if null.| An [ISO 4217 Alphabetic Currency Code][iso4217] representing the currency of the payee (see [Costs & Currencies][costs-and-currencies]) | | `gtfs_trip_id` | String | Required if Applicable | A unique trip ID for the associated scheduled GTFS route-trip. Matches [GTFS](https://gtfs.org/documentation/schedule/reference/) `trip_id` in the trips.txt and other files.| | `gtfs_api_url` | URL | Required if Applicable | Full URL to the location where the associated [GTFS](https://gtfs.org/documentation/schedule/reference/) dataset zip files are located. | +| `external_references` | Array of [External Reference][external-reference] objects | Optional | One or more references impacting or related to this Trip. | [Top][toc] From 59b298b11f589f8fbd1372eeaea966f618ef6681 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Wed, 30 Jul 2025 15:19:42 -0400 Subject: [PATCH 034/168] External reference to Policy Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- policy/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/policy/README.md b/policy/README.md index 82892835a..12d8fa5ba 100644 --- a/policy/README.md +++ b/policy/README.md @@ -322,6 +322,7 @@ An individual `Policy` object is defined by the following fields: | `published_date` | [timestamp][ts] | Required | Timestamp that the policy was published | | `prev_policies` | UUID[] | [Optional](../general-information.md#optional-fields) | Unique IDs of prior policies replaced by this one | | `rules` | Rule[] | Required | List of applicable [Rule](#rules) objects | +| `external_references` | Array of [External Reference][external-reference] objects | Optional | One or more references impacting or related to this Policy. | [Top][toc] From 9b0194b851be7a466777243f359ef6a2fbfd688f Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Wed, 30 Jul 2025 15:20:27 -0400 Subject: [PATCH 035/168] Updated descriptions Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- data-types.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/data-types.md b/data-types.md index b89529476..ef5a0399a 100644 --- a/data-types.md +++ b/data-types.md @@ -117,7 +117,7 @@ Events represent changes in vehicle status. | `stop_id` | UUID | [Required if Applicable](./general-information.md#required-if-applicable-fields) | Stop that the vehicle is currently located at. See [Stops][stops] | | `associated_ticket` | String | [Optional](./general-information.md#optional-fields) | Identifier for an associated ticket inside an Agency-maintained 311 or CRM system | | `gtfs_stop_id` | String | [Optional](./general-information.md#optional-fields) | A unique stop ID to be recorded when a vehicle makes a stop event at a location. Matches [GTFS](https://gtfs.org/documentation/schedule/reference/) `stop_id` | -| `external_references` | Array of [External Reference][external-reference] objects | Optional | One or more references impacting or related to this Trip. | +| `external_references` | Array of [External Reference][external-reference] objects | Optional | One or more references impacting or related to this Event. | ### Event Times @@ -189,7 +189,7 @@ Stops describe vehicle trip start and end locations in a pre-designated physical | `parent_stop` | UUID | [Optional](./general-information.md#optional-fields) | Describe a basic hierarchy of stops (e.g.a stop inside of a greater stop) | | `devices` | UUID[] | [Conditionally Required](./general-information.md#conditionally-required-fields) | List of device_ids for vehicles which are currently at this stop. Required if the program has station based availability requirements or service level agreements pertaining to stations. | | `image_url` | URL | [Optional](./general-information.md#optional-fields) | Link to an image, photo, or diagram of the stop. Could be used by providers to help riders find or use the stop. | -| `external_references` | Array of [External Reference][external-reference] objects | Optional | One or more references impacting or related to this Trip. | +| `external_references` | Array of [External Reference][external-reference] objects | Optional | One or more references impacting or related to this Stop. | [Top][toc] From 341ed28d1783879c419fd15d3bb8778dd68ba89d Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 31 Jul 2025 08:42:07 -0400 Subject: [PATCH 036/168] Description update Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- data-types.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/data-types.md b/data-types.md index ef5a0399a..f600c4c5e 100644 --- a/data-types.md +++ b/data-types.md @@ -17,7 +17,7 @@ This MDS data types page catalogs the objects (fields, types, requirements, desc - [Trips](#trips) - [Reports](#reports) - [External Reference](#external-reference) -- + ## Vehicles A vehicle record is as follows: @@ -304,17 +304,17 @@ Other special group types may be added in future MDS releases as relevant agency ## External Reference -An External Reference object describes a specific feature from a data feed or API that is relevant to the curb place via an external reference. This allows CDS users to reference other data feeds, documents, websites, or URLs that impact or provide information, and see more details in an external URL. Data feeds can be any existing standard (MDS, WZDx, CWZ, GTFS, GBFS, CDS, etc), custom feed, document, web page, etc. +An External Reference object describes a specific feature from a data feed or API that is relevant to the curb place via an external reference. This allows MDS users to reference other data feeds, documents, websites, or URLs that impact or provide information, and see more details in an external URL. Data feeds can be any existing standard (CDS, WZDx, CWZ, GTFS, GBFS, MDS, etc), custom feed, document, web page, etc. An `external_reference` is a JSON *array* with the following fields within objects: | Name | Type | Required/Optional | Description | | ------ | ------ | ------------------- | ------------- | | `data_feed_url` | URL | Required | A web-accessible identifier for the source of the publicly or privately accessible data feed, document, website, or URL. This MUST be a full HTTPS URL pointing to a location which contains more information impacting or explaining the location or policy. | -| `name` | String | Optional | Name of the data feed for reference. E.g. "WZDx", "CWZ", "MDS", "GBFS", "GTFS", "CDS". | +| `name` | String | Optional | Name of the data feed for reference. E.g. "WZDx", "CWZ", "CDS", "GBFS", "GTFS", "MDS". | | `public` | Boolean | Optional | Is this data feed able to be viewed with out any sort of authentication? If `true`, the `data_feed_url` is public. If `false`, the `data_feed_url` requires some sort of authentication, authorization, or API key to access. This is an informational field to set access expectations for the feed user, and does not provide any credentials directly unless explicitly contained in the `data_feed_url` URL string. | | `identifier_name` | String | Optional | The name of the data field or object that is referenced by the unique `ids`. E.g. "id", "report_id", "trip_id", "vehicle_id", "RoadEventFeature", etc, if relevant and available in the URL. | -| `ids` | Array of Strings | Optional | An array of one or more **ids** from the data feed that impacts the use of or relationship to part of CDS, e.g. a curb zone, curb space, curb area, curb event, etc. The **ids** and their details are be found in the referenced `data_feed_url`. | +| `ids` | Array of Strings | Optional | An array of one or more **ids** from the data feed that impacts the use of or relationship to part of MDS, e.g. Trips, Events, Stops, etc. The **ids** and their details are be found in the referenced `data_feed_url`. | [Top][toc] From 4a92fbcbd10d86aa5c8ad77ea7142f1dacf9cf63 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 31 Jul 2025 10:17:00 -0400 Subject: [PATCH 037/168] Updated external reference description Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- data-types.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/data-types.md b/data-types.md index f600c4c5e..e851be15f 100644 --- a/data-types.md +++ b/data-types.md @@ -304,7 +304,7 @@ Other special group types may be added in future MDS releases as relevant agency ## External Reference -An External Reference object describes a specific feature from a data feed or API that is relevant to the curb place via an external reference. This allows MDS users to reference other data feeds, documents, websites, or URLs that impact or provide information, and see more details in an external URL. Data feeds can be any existing standard (CDS, WZDx, CWZ, GTFS, GBFS, MDS, etc), custom feed, document, web page, etc. +An External Reference object describes a specific feature from an external data source that is relevant to a part of MDS data. This allows MDS users to reference other data sources that impact or provide information about an MDS object, and see more details at an external URL. Data feeds can be anythin available via a URL, including an existing data standard (CDS, WZDx, CWZ, GTFS, GBFS, MDS, etc), a custom feed, API, document, web page, report, etc. An `external_reference` is a JSON *array* with the following fields within objects: From b2624934c73c6b5a50739314e643627be7a088cc Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 31 Jul 2025 10:19:40 -0400 Subject: [PATCH 038/168] Field description updates Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- data-types.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/data-types.md b/data-types.md index e851be15f..7eb36cf7b 100644 --- a/data-types.md +++ b/data-types.md @@ -304,17 +304,17 @@ Other special group types may be added in future MDS releases as relevant agency ## External Reference -An External Reference object describes a specific feature from an external data source that is relevant to a part of MDS data. This allows MDS users to reference other data sources that impact or provide information about an MDS object, and see more details at an external URL. Data feeds can be anythin available via a URL, including an existing data standard (CDS, WZDx, CWZ, GTFS, GBFS, MDS, etc), a custom feed, API, document, web page, report, etc. +An External Reference object describes a specific feature from an external data source that is relevant to a part of MDS data. This allows MDS users to reference other data sources that impact or provide information about an MDS object, and see more details at an external URL. Data feeds can be anything available via a URL, including an existing data standard (CDS, WZDx, CWZ, GTFS, GBFS, MDS, etc), a custom feed, API, document, web page, report, etc. An `external_reference` is a JSON *array* with the following fields within objects: | Name | Type | Required/Optional | Description | | ------ | ------ | ------------------- | ------------- | -| `data_feed_url` | URL | Required | A web-accessible identifier for the source of the publicly or privately accessible data feed, document, website, or URL. This MUST be a full HTTPS URL pointing to a location which contains more information impacting or explaining the location or policy. | -| `name` | String | Optional | Name of the data feed for reference. E.g. "WZDx", "CWZ", "CDS", "GBFS", "GTFS", "MDS". | -| `public` | Boolean | Optional | Is this data feed able to be viewed with out any sort of authentication? If `true`, the `data_feed_url` is public. If `false`, the `data_feed_url` requires some sort of authentication, authorization, or API key to access. This is an informational field to set access expectations for the feed user, and does not provide any credentials directly unless explicitly contained in the `data_feed_url` URL string. | -| `identifier_name` | String | Optional | The name of the data field or object that is referenced by the unique `ids`. E.g. "id", "report_id", "trip_id", "vehicle_id", "RoadEventFeature", etc, if relevant and available in the URL. | -| `ids` | Array of Strings | Optional | An array of one or more **ids** from the data feed that impacts the use of or relationship to part of MDS, e.g. Trips, Events, Stops, etc. The **ids** and their details are be found in the referenced `data_feed_url`. | +| `data_source_url` | URL | Required | A web-accessible identifier for the source of the publicly or privately accessible data feed, document, website, or URL. This MUST be a full HTTPS URL pointing to a location which contains more information impacting or explaining the location, event, or policy. | +| `name` | String | Optional | Name of the data source for reference. E.g. "WZDx", "CWZ", "CDS", "GBFS", "GTFS", "MDS". | +| `public` | Boolean | Optional | Is this data feed able to be viewed with out any sort of authentication? If `true`, the `data_feed_url` is public. If `false`, the `data_feed_url` requires some sort of authentication, authorization, or API key to access. This is an informational field to set access expectations for the data source user, and does not provide any credentials directly unless explicitly contained in the `data_feed_url` URL string. | +| `identifier_name` | String | Optional | The name of the data source identifier or object that is referenced by the unique `ids`. E.g. "id", "report_id", "trip_id", "vehicle_id", "RoadEventFeature", etc, if relevant and available in the URL. | +| `ids` | Array of Strings | Optional | An array of one or more **ids** from the data sources that impacts the use of or relationship to part of MDS, e.g. Trips, Events, Stops, etc. The **ids** and their details are be found in the referenced `data_source_url`. | [Top][toc] From e780dc6bfbc1dab7db81d5753dfadb520ac8fbac Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 31 Jul 2025 10:21:18 -0400 Subject: [PATCH 039/168] Update data source language Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- data-types.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/data-types.md b/data-types.md index 7eb36cf7b..d77809855 100644 --- a/data-types.md +++ b/data-types.md @@ -304,7 +304,7 @@ Other special group types may be added in future MDS releases as relevant agency ## External Reference -An External Reference object describes a specific feature from an external data source that is relevant to a part of MDS data. This allows MDS users to reference other data sources that impact or provide information about an MDS object, and see more details at an external URL. Data feeds can be anything available via a URL, including an existing data standard (CDS, WZDx, CWZ, GTFS, GBFS, MDS, etc), a custom feed, API, document, web page, report, etc. +An External Reference object describes a specific feature from an external data source that is relevant to a part of MDS data. This allows MDS users to reference other data sources that impact or provide information about an MDS object, and see more details at an external URL. Data sources can be anything available via a URL, including an existing data standard (CDS, WZDx, CWZ, GTFS, GBFS, MDS, etc), a custom feed, API, document, web page, report, etc. An `external_reference` is a JSON *array* with the following fields within objects: From 07401ed2ccf9d1a974a933e62eaedb9560553352 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 31 Jul 2025 10:31:30 -0400 Subject: [PATCH 040/168] data_source_url update Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- data-types.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/data-types.md b/data-types.md index d77809855..3dffb9754 100644 --- a/data-types.md +++ b/data-types.md @@ -310,10 +310,10 @@ An `external_reference` is a JSON *array* with the following fields within objec | Name | Type | Required/Optional | Description | | ------ | ------ | ------------------- | ------------- | -| `data_source_url` | URL | Required | A web-accessible identifier for the source of the publicly or privately accessible data feed, document, website, or URL. This MUST be a full HTTPS URL pointing to a location which contains more information impacting or explaining the location, event, or policy. | +| `data_source_url` | URL | Required | A web-accessible identifier for the source of the publicly or privately accessible data source URL. This MUST be a full HTTPS URL pointing to a location which contains more information impacting or explaining the location, event, policy, etc. | | `name` | String | Optional | Name of the data source for reference. E.g. "WZDx", "CWZ", "CDS", "GBFS", "GTFS", "MDS". | -| `public` | Boolean | Optional | Is this data feed able to be viewed with out any sort of authentication? If `true`, the `data_feed_url` is public. If `false`, the `data_feed_url` requires some sort of authentication, authorization, or API key to access. This is an informational field to set access expectations for the data source user, and does not provide any credentials directly unless explicitly contained in the `data_feed_url` URL string. | -| `identifier_name` | String | Optional | The name of the data source identifier or object that is referenced by the unique `ids`. E.g. "id", "report_id", "trip_id", "vehicle_id", "RoadEventFeature", etc, if relevant and available in the URL. | +| `public` | Boolean | Optional | Is this data source able to be viewed with out any sort of authentication? If `true`, the `data_feed_url` is public. If `false`, the `data_source_url` requires some sort of authentication, authorization, or API key to access. This is an informational field to set access expectations for the data source user, and does not provide any credentials directly unless explicitly contained in the `data_source_url` URL string. | +| `identifier_name` | String | Optional | The name of the data field identifier or object that is referenced by the unique `ids`. E.g. "id", "report_id", "trip_id", "vehicle_id", "RoadEventFeature", etc, if relevant and available in the URL. | | `ids` | Array of Strings | Optional | An array of one or more **ids** from the data sources that impacts the use of or relationship to part of MDS, e.g. Trips, Events, Stops, etc. The **ids** and their details are be found in the referenced `data_source_url`. | [Top][toc] From b26ebae5806971d0fabf914f8022e2846253e5d2 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 31 Jul 2025 10:43:23 -0400 Subject: [PATCH 041/168] Added geography note Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- policy/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/policy/README.md b/policy/README.md index d52a616cd..8e280b5f9 100644 --- a/policy/README.md +++ b/policy/README.md @@ -198,6 +198,8 @@ See [Responses][responses], [Bulk Responses][bulk-responses], and [schema][schem Allows agencies to push a newly created policies to operators, similar to the Agency API. This push method creates the opportunity for near real-time communication of policy changes. +Note that once an update is communicated via a policy push, the agency should pull from the relevant [Geography API](../geography) endpoint to see if there are new or changed geographic areas. + Endpoint producers **SHALL** provide authorization for API endpoints via a bearer token based auth system specified in the MDS [Authorization section](/general-information.md#authorization), to allow handshake communication and response confirmation. **Endpoint**: `/policies/` From be85b6ecd279aa4343f925b57dbc902ea4e6523f Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 31 Jul 2025 11:59:44 -0400 Subject: [PATCH 042/168] Update name to reference_url Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- data-types.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/data-types.md b/data-types.md index 3dffb9754..4b5d8bda1 100644 --- a/data-types.md +++ b/data-types.md @@ -310,11 +310,11 @@ An `external_reference` is a JSON *array* with the following fields within objec | Name | Type | Required/Optional | Description | | ------ | ------ | ------------------- | ------------- | -| `data_source_url` | URL | Required | A web-accessible identifier for the source of the publicly or privately accessible data source URL. This MUST be a full HTTPS URL pointing to a location which contains more information impacting or explaining the location, event, policy, etc. | +| `reference_url` | URL | Required | A web-accessible identifier for the source of the publicly or privately accessible data source URL. This MUST be a full HTTPS URL pointing to a location which contains more information impacting or explaining the location, event, policy, etc. | | `name` | String | Optional | Name of the data source for reference. E.g. "WZDx", "CWZ", "CDS", "GBFS", "GTFS", "MDS". | -| `public` | Boolean | Optional | Is this data source able to be viewed with out any sort of authentication? If `true`, the `data_feed_url` is public. If `false`, the `data_source_url` requires some sort of authentication, authorization, or API key to access. This is an informational field to set access expectations for the data source user, and does not provide any credentials directly unless explicitly contained in the `data_source_url` URL string. | +| `public` | Boolean | Optional | Is this data source able to be viewed with out any sort of authentication? If `true`, the `reference_url` is public. If `false`, the `reference_url` requires some sort of authentication, authorization, or API key to access. This is an informational field to set access expectations for the data source user, and does not provide any credentials directly unless explicitly contained in the `data_source_url` URL string. | | `identifier_name` | String | Optional | The name of the data field identifier or object that is referenced by the unique `ids`. E.g. "id", "report_id", "trip_id", "vehicle_id", "RoadEventFeature", etc, if relevant and available in the URL. | -| `ids` | Array of Strings | Optional | An array of one or more **ids** from the data sources that impacts the use of or relationship to part of MDS, e.g. Trips, Events, Stops, etc. The **ids** and their details are be found in the referenced `data_source_url`. | +| `ids` | Array of Strings | Optional | An array of one or more **ids** from the data sources that impacts the use of or relationship to part of MDS, e.g. Trips, Events, Stops, etc. The **ids** and their details are be found in the referenced `reference_url`. | [Top][toc] From 6ee8cfaa7faea925d95719a62eefc495ed970ffd Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 31 Jul 2025 14:09:02 -0400 Subject: [PATCH 043/168] Link to Ext Ref Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- data-types.md | 1 + 1 file changed, 1 insertion(+) diff --git a/data-types.md b/data-types.md index 4b5d8bda1..c05f803f6 100644 --- a/data-types.md +++ b/data-types.md @@ -320,6 +320,7 @@ An `external_reference` is a JSON *array* with the following fields within objec [costs-and-currencies]: /general-information.md#costs-and-currencies [event-times]: #event-times +[external-reference]: ../data-types.md#external-reference [gbfs-station-info]: https://github.com/NABSA/gbfs/blob/master/gbfs.md#station_informationjson [gbfs-station-status]: https://github.com/NABSA/gbfs/blob/master/gbfs.md#station_statusjson [geography-driven-events]: /general-information.md#geography-driven-events From a142e190b4cffa698f264d4495c03cc1529436c5 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 31 Jul 2025 14:13:02 -0400 Subject: [PATCH 044/168] Added links to Optional definitions Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- data-types.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/data-types.md b/data-types.md index c05f803f6..a4e82b1f9 100644 --- a/data-types.md +++ b/data-types.md @@ -117,7 +117,7 @@ Events represent changes in vehicle status. | `stop_id` | UUID | [Required if Applicable](./general-information.md#required-if-applicable-fields) | Stop that the vehicle is currently located at. See [Stops][stops] | | `associated_ticket` | String | [Optional](./general-information.md#optional-fields) | Identifier for an associated ticket inside an Agency-maintained 311 or CRM system | | `gtfs_stop_id` | String | [Optional](./general-information.md#optional-fields) | A unique stop ID to be recorded when a vehicle makes a stop event at a location. Matches [GTFS](https://gtfs.org/documentation/schedule/reference/) `stop_id` | -| `external_references` | Array of [External Reference][external-reference] objects | Optional | One or more references impacting or related to this Event. | +| `external_references` | Array of [External Reference][external-reference] objects | [Optional](./general-information.md#optional-fields) | One or more references impacting or related to this Event. | ### Event Times @@ -189,7 +189,7 @@ Stops describe vehicle trip start and end locations in a pre-designated physical | `parent_stop` | UUID | [Optional](./general-information.md#optional-fields) | Describe a basic hierarchy of stops (e.g.a stop inside of a greater stop) | | `devices` | UUID[] | [Conditionally Required](./general-information.md#conditionally-required-fields) | List of device_ids for vehicles which are currently at this stop. Required if the program has station based availability requirements or service level agreements pertaining to stations. | | `image_url` | URL | [Optional](./general-information.md#optional-fields) | Link to an image, photo, or diagram of the stop. Could be used by providers to help riders find or use the stop. | -| `external_references` | Array of [External Reference][external-reference] objects | Optional | One or more references impacting or related to this Stop. | +| `external_references` | Array of [External Reference][external-reference] objects | [Optional](./general-information.md#optional-fields) | One or more references impacting or related to this Stop. | [Top][toc] @@ -245,7 +245,7 @@ A Trip is defined by the following structure: | `currency` | String | [Optional](./general-information.md#optional-fields), USD cents is implied if null.| An [ISO 4217 Alphabetic Currency Code][iso4217] representing the currency of the payee (see [Costs & Currencies][costs-and-currencies]) | | `gtfs_trip_id` | String | Required if Applicable | A unique trip ID for the associated scheduled GTFS route-trip. Matches [GTFS](https://gtfs.org/documentation/schedule/reference/) `trip_id` in the trips.txt and other files.| | `gtfs_api_url` | URL | Required if Applicable | Full URL to the location where the associated [GTFS](https://gtfs.org/documentation/schedule/reference/) dataset zip files are located. | -| `external_references` | Array of [External Reference][external-reference] objects | Optional | One or more references impacting or related to this Trip. | +| `external_references` | Array of [External Reference][external-reference] objects | [Optional](./general-information.md#optional-fields) | One or more references impacting or related to this Trip. | [Top][toc] @@ -311,10 +311,10 @@ An `external_reference` is a JSON *array* with the following fields within objec | Name | Type | Required/Optional | Description | | ------ | ------ | ------------------- | ------------- | | `reference_url` | URL | Required | A web-accessible identifier for the source of the publicly or privately accessible data source URL. This MUST be a full HTTPS URL pointing to a location which contains more information impacting or explaining the location, event, policy, etc. | -| `name` | String | Optional | Name of the data source for reference. E.g. "WZDx", "CWZ", "CDS", "GBFS", "GTFS", "MDS". | -| `public` | Boolean | Optional | Is this data source able to be viewed with out any sort of authentication? If `true`, the `reference_url` is public. If `false`, the `reference_url` requires some sort of authentication, authorization, or API key to access. This is an informational field to set access expectations for the data source user, and does not provide any credentials directly unless explicitly contained in the `data_source_url` URL string. | -| `identifier_name` | String | Optional | The name of the data field identifier or object that is referenced by the unique `ids`. E.g. "id", "report_id", "trip_id", "vehicle_id", "RoadEventFeature", etc, if relevant and available in the URL. | -| `ids` | Array of Strings | Optional | An array of one or more **ids** from the data sources that impacts the use of or relationship to part of MDS, e.g. Trips, Events, Stops, etc. The **ids** and their details are be found in the referenced `reference_url`. | +| `name` | String | [Optional](./general-information.md#optional-fields) | Name of the data source for reference. E.g. "WZDx", "CWZ", "CDS", "GBFS", "GTFS", "MDS". | +| `public` | Boolean | [Optional](./general-information.md#optional-fields) | Is this data source able to be viewed with out any sort of authentication? If `true`, the `reference_url` is public. If `false`, the `reference_url` requires some sort of authentication, authorization, or API key to access. This is an informational field to set access expectations for the data source user, and does not provide any credentials directly unless explicitly contained in the `data_source_url` URL string. | +| `identifier_name` | String | [Optional](./general-information.md#optional-fields) | The name of the data field identifier or object that is referenced by the unique `ids`. E.g. "id", "report_id", "trip_id", "vehicle_id", "RoadEventFeature", etc, if relevant and available in the URL. | +| `ids` | Array of Strings | [Optional](./general-information.md#optional-fields) | An array of one or more **ids** from the data sources that impacts the use of or relationship to part of MDS, e.g. Trips, Events, Stops, etc. The **ids** and their details are be found in the referenced `reference_url`. | [Top][toc] From cbcfae96e98f8dfbe82b16156ba7f6f6b3508721 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 5 Aug 2025 13:38:34 -0400 Subject: [PATCH 045/168] Added authenticated option on get policy Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- policy/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/policy/README.md b/policy/README.md index 9d6631601..10e3b4cd5 100644 --- a/policy/README.md +++ b/policy/README.md @@ -152,7 +152,7 @@ See the [Responses section][responses] for information on valid MDS response cod **Endpoint**: `/policies/{policy_id}` **Method**: `GET` **Schema:** See [`mds-openapi`](https://github.com/openmobilityfoundation/mds-openapi) repository for schema. -**Authorization**: public +**Authorization**: public _or_ authenticated (see [Authorization](#authorization)) **`data` Payload**: `{ "policies": [] }`, an array of objects with the structure [outlined below](#policy). _Path Parameters:_ @@ -201,7 +201,7 @@ See [Responses][responses], [Bulk Responses][bulk-responses], and [schema][schem **Endpoint**: `/requirements/` **Method**: `GET` **[Beta feature](/general-information.md#beta-features)**: *No (as of 2.0.0)*. -**Authorization**: public +**Authorization**: public **Schema:** See [`mds-openapi`](https://github.com/openmobilityfoundation/mds-openapi) repository for schema. **`data` Payload**: `{ requirements: [] }`, JSON objects that follow the schema [outlined here](#requirement). From a432c9362f3470dc500cf1fd2287cea99fd304f4 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 5 Aug 2025 13:39:51 -0400 Subject: [PATCH 046/168] Formatting Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- policy/README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/policy/README.md b/policy/README.md index 10e3b4cd5..ed55e92e9 100644 --- a/policy/README.md +++ b/policy/README.md @@ -151,9 +151,9 @@ See the [Responses section][responses] for information on valid MDS response cod **Endpoint**: `/policies/{policy_id}` **Method**: `GET` -**Schema:** See [`mds-openapi`](https://github.com/openmobilityfoundation/mds-openapi) repository for schema. -**Authorization**: public _or_ authenticated (see [Authorization](#authorization)) -**`data` Payload**: `{ "policies": [] }`, an array of objects with the structure [outlined below](#policy). +**Schema:** See [`mds-openapi`](https://github.com/openmobilityfoundation/mds-openapi) repository for schema. +**Authorization**: public _or_ authenticated (see [Authorization](#authorization)) +**`data` Payload**: `{ "policies": [] }`, an array of objects with the structure [outlined below](#policy). _Path Parameters:_ @@ -200,8 +200,8 @@ See [Responses][responses], [Bulk Responses][bulk-responses], and [schema][schem **Endpoint**: `/requirements/` **Method**: `GET` -**[Beta feature](/general-information.md#beta-features)**: *No (as of 2.0.0)*. -**Authorization**: public +**[Beta feature](/general-information.md#beta-features)**: *No (as of 2.0.0)*. +**Authorization**: public **Schema:** See [`mds-openapi`](https://github.com/openmobilityfoundation/mds-openapi) repository for schema. **`data` Payload**: `{ requirements: [] }`, JSON objects that follow the schema [outlined here](#requirement). From 7a5865b285413c20b10eb3112002c721b3c41fd6 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 5 Aug 2025 13:50:32 -0400 Subject: [PATCH 047/168] Add Push for Geography Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- geography/README.md | 45 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/geography/README.md b/geography/README.md index 968d2c7af..31f0794b9 100644 --- a/geography/README.md +++ b/geography/README.md @@ -24,6 +24,7 @@ Geographical data will be stored as GeoJSON and read from either `geographies.js - [Endpoints](#endpoints) - [Geography](#geography) - [Geographies](#geographies) + - [Geographies - Create](#geographies---create) - [Examples](#examples) ## General Information @@ -180,6 +181,7 @@ The Geography API consists of the following endpoints: **Endpoint**: `/geographies/{geography_id}` **Method**: `GET` **Schema:** See [`mds-openapi`](https://github.com/openmobilityfoundation/mds-openapi) repository for schema. +**Authorization**: public #### Path Parameters @@ -225,6 +227,7 @@ See [Responses][responses], [Bulk Responses][bulk-responses], and [schema][schem **Endpoint**: `/geographies` **Method**: `GET` **Schema:** See [`mds-openapi`](https://github.com/openmobilityfoundation/mds-openapi) repository for schema. +**Authorization**: public Returns: All geography objects @@ -257,6 +260,48 @@ See [Responses][responses], [Bulk Responses][bulk-responses], and [schema][schem [Top][toc] +### Geographies - Create + +Allows agencies to push a newly created policies to geographies, similar to the Agency API. This push method creates the opportunity for near real-time communication of geography changes. + +Note that once an update is communicated via a policy push, the agency should pull from the relevant [Geography API](../geography) endpoint to see if there are new or changed geographic areas. + +Endpoint producers **SHALL** provide authorization for API endpoints via a bearer token based auth system specified in the MDS [Authorization section](/general-information.md#authorization), to allow handshake communication and response confirmation. + +**Endpoint**: `/geographies/` +**Method:** `POST` +**Authorization**: required +**Payload:** An array of [Geography](#schema) objects + +_Optional endpoint, as required by public agencies; if not implemented, the server should reply with `501 Not Implemented` if possible._ + +#### Responses + +_Possible HTTP Status Codes_: +201, +400, +401, +406, +409, +500, +501 + +See [Responses][responses], [Bulk Responses][bulk-responses], and [schema][schema] for details. + +[Top][toc] + +#### Error Codes: + +| `error` | `error_description` | `error_details`[] | +| -------------------- | -----------------------------------------------| ------------------------------- | +| `bad_param` | A validation error occurred | Array of parameters with errors | +| `missing_param` | A required parameter is missing | Array of missing parameters | +| `already_created` | A geography with `geography_id` is already created | | + +Note that you may only create a new MDS Policy. Retired policies are simply referenced in `prev_policies`. See [Updating or Ending Policies](#updating-or-ending-policies) for details. + +[Top][toc] + ## Examples See the [Geography Examples](examples/README.md) for ways these can be implemented and geometry previews. From ea91a5bed7c13c83f2fafc79dfed8fde319d3a31 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 5 Aug 2025 13:51:12 -0400 Subject: [PATCH 048/168] Policy push formatting Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- policy/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/policy/README.md b/policy/README.md index 8e280b5f9..75898c605 100644 --- a/policy/README.md +++ b/policy/README.md @@ -198,7 +198,7 @@ See [Responses][responses], [Bulk Responses][bulk-responses], and [schema][schem Allows agencies to push a newly created policies to operators, similar to the Agency API. This push method creates the opportunity for near real-time communication of policy changes. -Note that once an update is communicated via a policy push, the agency should pull from the relevant [Geography API](../geography) endpoint to see if there are new or changed geographic areas. +Note that once an update is communicated via a policy push, the agency should push or pull from the relevant [Geography API](../geography) endpoint to get the latest information on new or changed geographic areas. Endpoint producers **SHALL** provide authorization for API endpoints via a bearer token based auth system specified in the MDS [Authorization section](/general-information.md#authorization), to allow handshake communication and response confirmation. @@ -207,7 +207,7 @@ Endpoint producers **SHALL** provide authorization for API endpoints via a beare **Authorization**: required **Payload:** An array of [Policy](#policy) objects -_Optional endpoint, as required by public agencies; if not implemented, the server should reply with `501 Not Implemented`._ +_Optional endpoint, as required by public agencies; if not implemented, the server should reply with `501 Not Implemented` if possible._ **Responses** From fb3e173a748de1b43a9967dd960a60d9e06f3660 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 5 Aug 2025 13:53:23 -0400 Subject: [PATCH 049/168] Clarified prev geographies Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- geography/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/geography/README.md b/geography/README.md index 31f0794b9..91b12b513 100644 --- a/geography/README.md +++ b/geography/README.md @@ -296,9 +296,9 @@ See [Responses][responses], [Bulk Responses][bulk-responses], and [schema][schem | -------------------- | -----------------------------------------------| ------------------------------- | | `bad_param` | A validation error occurred | Array of parameters with errors | | `missing_param` | A required parameter is missing | Array of missing parameters | -| `already_created` | A geography with `geography_id` is already created | | +| `already_created` | A geography with `geography_id` is already created | | -Note that you may only create a new MDS Policy. Retired policies are simply referenced in `prev_policies`. See [Updating or Ending Policies](#updating-or-ending-policies) for details. +Note that you may only create a new MDS Geography. Retired geographies are simply referenced in `prev_geographies`. See [Distribution](#distribution) for details. [Top][toc] From f18caff4ed697c15441370b5cb137fa685db472e Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 5 Aug 2025 13:54:56 -0400 Subject: [PATCH 050/168] Note for referencing policies Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- geography/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/geography/README.md b/geography/README.md index 91b12b513..5b1fec79f 100644 --- a/geography/README.md +++ b/geography/README.md @@ -264,7 +264,7 @@ See [Responses][responses], [Bulk Responses][bulk-responses], and [schema][schem Allows agencies to push a newly created policies to geographies, similar to the Agency API. This push method creates the opportunity for near real-time communication of geography changes. -Note that once an update is communicated via a policy push, the agency should pull from the relevant [Geography API](../geography) endpoint to see if there are new or changed geographic areas. +Note that when an update is communicated via a geography push, the agency should pull or push from the relevant [Policy API](../policy) endpoint to see if there are new or changed policies related to this geographic area. Endpoint producers **SHALL** provide authorization for API endpoints via a bearer token based auth system specified in the MDS [Authorization section](/general-information.md#authorization), to allow handshake communication and response confirmation. From f11625b2c7eb3ceb5d406df076fe71cb458febd5 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 5 Aug 2025 15:54:37 -0400 Subject: [PATCH 051/168] Update Ext Ref field descriptions Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- data-types.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/data-types.md b/data-types.md index a4e82b1f9..b646d542f 100644 --- a/data-types.md +++ b/data-types.md @@ -310,10 +310,10 @@ An `external_reference` is a JSON *array* with the following fields within objec | Name | Type | Required/Optional | Description | | ------ | ------ | ------------------- | ------------- | -| `reference_url` | URL | Required | A web-accessible identifier for the source of the publicly or privately accessible data source URL. This MUST be a full HTTPS URL pointing to a location which contains more information impacting or explaining the location, event, policy, etc. | +| `reference_url` | URL | Required | A web-accessible identifier URL for the source of the publicly or privately accessible data feed, document, website, etc. This MUST be a full HTTPS URL pointing to a location which contains more information impacting or explaining the location, event, or policy, etc. | | `name` | String | [Optional](./general-information.md#optional-fields) | Name of the data source for reference. E.g. "WZDx", "CWZ", "CDS", "GBFS", "GTFS", "MDS". | -| `public` | Boolean | [Optional](./general-information.md#optional-fields) | Is this data source able to be viewed with out any sort of authentication? If `true`, the `reference_url` is public. If `false`, the `reference_url` requires some sort of authentication, authorization, or API key to access. This is an informational field to set access expectations for the data source user, and does not provide any credentials directly unless explicitly contained in the `data_source_url` URL string. | -| `identifier_name` | String | [Optional](./general-information.md#optional-fields) | The name of the data field identifier or object that is referenced by the unique `ids`. E.g. "id", "report_id", "trip_id", "vehicle_id", "RoadEventFeature", etc, if relevant and available in the URL. | +| `public` | Boolean | [Optional](./general-information.md#optional-fields) | Is this data source able to be viewed with out any sort of authentication? If `true`, the `reference_url` is public. If `false`, the `reference_url` requires some sort of authentication, authorization, or API key to access. This is an informational field to set access expectations for the data source user, and does not provide any credentials directly unless explicitly contained in the `reference_url`. | +| `identifier_name` | String | [Optional](./general-information.md#optional-fields) | The name of the data field identifier or object that is referenced by the unique `ids`. E.g. "id", "report_id", "trip_id", "vehicle_id", "RoadEventFeature", etc, if relevant and available in `reference_url`. | | `ids` | Array of Strings | [Optional](./general-information.md#optional-fields) | An array of one or more **ids** from the data sources that impacts the use of or relationship to part of MDS, e.g. Trips, Events, Stops, etc. The **ids** and their details are be found in the referenced `reference_url`. | [Top][toc] From 37d76f06be39e199036fea43eaec5b6db6a22038 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 22 Aug 2025 11:52:32 -0400 Subject: [PATCH 052/168] Create SECURITY.md Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- SECURITY.md | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 SECURITY.md diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 000000000..c80200120 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,11 @@ +# Security Policy + +## Supported Versions + +The most recent version and/or any version 2 years old or newer is supported. Other versions are not recommended and not supported. + +See our [MDS Releases](https://github.com/openmobilityfoundation/governance/wiki/Releases) page for full details and list of supported releases by version number. + +## Reporting a Vulnerability or Issue + +If you find a vulnerability or issue with a supported version of the specification, open an [Issue](https://github.com/openmobilityfoundation/mobility-data-specification/issues) to let us know and start a discussion on how to fix it in a future release. From 8cf5179370bdb1fc8f52648a4ee97ca040cce0ee Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 22 Aug 2025 11:55:26 -0400 Subject: [PATCH 053/168] Create LIABILITY Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- LIABILITY | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 LIABILITY diff --git a/LIABILITY b/LIABILITY new file mode 100644 index 000000000..8804ce537 --- /dev/null +++ b/LIABILITY @@ -0,0 +1,25 @@ +Liability for Deliverables + +All Open Mobility Foundation deliverables are provided "AS IS", without warranty of any +kind, express or implied, and OMF, as well as all of its Members and Contributors, +expressly disclaim any warranty of merchantability, fitness for a particular or intended +purpose, accuracy, completeness, non-infringement of third party rights, or any other +warranty. + +In no event shall OMF or any of its officers, directors, agents or Members be liable to +any other person or entity for any loss of profits, loss of use, direct, indirect, incidental, +consequential, punitive, or special damages, whether under contract, tort, warranty, or +otherwise, arising in any way out of this Policy, whether or not such party had advance +notice of the possibility of such damages. Limitations to the liability of OMF +Contributors as Contributors are set forth in their Contributor License Agreements. + +In addition, except for grossly negligent or intentionally fraudulent acts, OMF and its +officers, directors, agents, Members and Contributors (and their respective +representatives) shall not be liable to any other person or entity for any loss of profits, +loss of use, direct, indirect, incidental, consequential, punitive, or special damages, +whether under contract, tort, warranty, or otherwise, arising in any way out of this +Policy, whether or not such party had advance notice of the possibility of such damages. + +OMF assumes no responsibility to compile, confirm, update or make public any +assertions of intellectual property rights or claims that might be infringed by an +implementation of an OMF Deliverable. From db567de8e7cf4b126fd76333bf07f72f730170b4 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 16 Sep 2025 12:08:10 -0400 Subject: [PATCH 054/168] Updated language based on some CDS verbiage Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- policy/README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/policy/README.md b/policy/README.md index ed55e92e9..b4dfe60c8 100644 --- a/policy/README.md +++ b/policy/README.md @@ -80,7 +80,9 @@ See the [MDS Policy Examples](https://github.com/openmobilityfoundation/mobility ### Authorization -In most cases, the Policy endpoints should be made public. Authorization is not required in such cases. Agencies may make reasonable accommodations to manage their endpoints, for example, using an API key that has a clear, public way to obtain - this can be useful for rate limiting requests, ensure proper use, tracking access per requestor, and/or customization of the Policy tailored to the requestor. +In most cases, the Policy endpoints should be made public. Authorization is not required in such cases, as this information should be made public and easily accessible. + +Agencies may make reasonable accommodations to manage their endpoints by, for example, using a free to acquire API key that has a clear, public way to obtain. This can be useful for rate limiting requests, prevent abuse, ensure proper use, tracking access per requestor, for certain mobility programs or pilots, and/or customization of the Policy tailored to the requestor. In some cases though, it can be justified to use Authorization for the Policy API (some agencies may decide to make it authenticated for privacy programs or functional purposes). Authorization may then be used for the Policy API. It should then rely on the standard [Authorization](../general-information.md#authorization) methods used in other MDS APIs. From eb2c1eed7546f824d1e9a0a7fccce020ad989f44 Mon Sep 17 00:00:00 2001 From: Matt Davis Date: Fri, 19 Sep 2025 14:14:54 -0700 Subject: [PATCH 055/168] Clarify which vehicles should be included in /vehicles I'm trying to make it explicit that when calling the /vehicles endpoint without specifying a vehicle it must include all vehicles returned by calling the /vehicles/status at the same time without specifying a vehicle. (It may also include additional vehicles as appropriate, but the response must include all vehicles from /vehicles/status.) I think the existing documentation says this implicitly, but I've encountered some confusion in the wild and would like to make it explicit. --- provider/README.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/provider/README.md b/provider/README.md index 361fafafa..35bc38828 100644 --- a/provider/README.md +++ b/provider/README.md @@ -181,9 +181,12 @@ As with other MDS APIs, the vehicles endpoints are intended for use by regulator The `/vehicles` endpoint returns the specified vehicle (if a `device_id` is provided) or a list of vehicles. It contains vehicle properties that do not change often. -When `/vehicles` is called without specifying a device ID it should return every vehicle that has +When `/vehicles` is called without specifying a device ID it must return every vehicle that has been deployed in an agency's [Jurisdiction](/general-information.md#definitions) and/or area of agency responsibility -in the last 30 days. +in the last 30 days and it must include every vehicle included when calling the `/vehicles/status` +endpoint at the same time without specifying a specific vehicle. (In other words, if someone +retrieves `/vehicles/status` and `/vehicles` at the same time, they must be able to find every +vehicle in the `/vehicles/status` response in the `/vehicles` response.) Vehicle information about all device IDs present in other MDS endpoints must be acessible via the `/vehicles/{device_id}` style call regardless of when they were deployed. From 316d9efa18bbbb4336f687e98c8fc0cbff9f531e Mon Sep 17 00:00:00 2001 From: Marcus V Date: Fri, 26 Sep 2025 14:04:13 -0700 Subject: [PATCH 056/168] Updated providers.csv SFMTA adding a new data provider Signed-off-by: Marcus V --- providers.csv | 1 + 1 file changed, 1 insertion(+) diff --git a/providers.csv b/providers.csv index c0d4168d6..0ca9c3a61 100644 --- a/providers.csv +++ b/providers.csv @@ -77,3 +77,4 @@ Swoop,passenger-services,08ad2b21-8115-4d18-874f-48082e8e50fb,https://www.swoopa GoSharing,micromobility,1f859479-4427-4f52-8220-05c786436314,https://www.binbin.tech/,https://complianceapi.binbinapp.com/api/mds/,https://complianceapi.binbinapp.com/api/gbfs/ Mosaic Global,passenger-services,74ba2b64-c44f-474a-afbd-c2030fe162a6,https://mosaicglobaltransportation.com/,, Code3,passenger-services,b49a32d7-a418-4a6a-9f81-b5227d6c7ef8,https://code3transportation.com/,, +Track My Shuttle,passenger-services,dd7db795-09c0-402f-9441-360235da3025, https://trackmyshuttle.com/,, From 60adf850f8756413a3f1cdc3561eda60dc9376a5 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 13 Oct 2025 11:43:02 -0400 Subject: [PATCH 057/168] Remove space Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- providers.csv | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/providers.csv b/providers.csv index 0ca9c3a61..17cf5035f 100644 --- a/providers.csv +++ b/providers.csv @@ -77,4 +77,4 @@ Swoop,passenger-services,08ad2b21-8115-4d18-874f-48082e8e50fb,https://www.swoopa GoSharing,micromobility,1f859479-4427-4f52-8220-05c786436314,https://www.binbin.tech/,https://complianceapi.binbinapp.com/api/mds/,https://complianceapi.binbinapp.com/api/gbfs/ Mosaic Global,passenger-services,74ba2b64-c44f-474a-afbd-c2030fe162a6,https://mosaicglobaltransportation.com/,, Code3,passenger-services,b49a32d7-a418-4a6a-9f81-b5227d6c7ef8,https://code3transportation.com/,, -Track My Shuttle,passenger-services,dd7db795-09c0-402f-9441-360235da3025, https://trackmyshuttle.com/,, +Track My Shuttle,passenger-services,dd7db795-09c0-402f-9441-360235da3025,https://trackmyshuttle.com/,, From efef884606100a583777d8553f75524b62e4606a Mon Sep 17 00:00:00 2001 From: Bruno Cardenas <62057961+bruno-cardenas@users.noreply.github.com> Date: Wed, 22 Oct 2025 17:31:06 +0200 Subject: [PATCH 058/168] Add Sixt car-share provider to providers.csv Signed-off-by: Bruno Cardenas <62057961+bruno-cardenas@users.noreply.github.com> --- providers.csv | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/providers.csv b/providers.csv index 642cc0e5a..efd0d1bf5 100644 --- a/providers.csv +++ b/providers.csv @@ -75,4 +75,4 @@ Tripshot,passenger-services,e154cf80-df89-4d7e-b5e7-2ee8050a6e9c,https://www.tri Trakk,passenger-services,6a907d9d-1e3c-4cb6-991c-f9738d30337b,https://gettrakk.com/,, Swoop,passenger-services,08ad2b21-8115-4d18-874f-48082e8e50fb,https://www.swoopapp.com/,, GoSharing,micromobility,1f859479-4427-4f52-8220-05c786436314,https://www.binbin.tech/,https://complianceapi.binbinapp.com/api/mds/,https://complianceapi.binbinapp.com/api/gbfs/ - +Sixt,car-share,df72d104-372f-4d98-a4c3-9b001967990e,https://sixt.com/,https://api.orange.sixt.com/v1/share-third-party-sources/mds,https://api.orange.sixt.com/v1/share-third-party-sources/gbfs From bf38920096975c02320f9f9cfe03ad6942dd9462 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Wed, 22 Oct 2025 13:25:14 -0400 Subject: [PATCH 059/168] First pass at Delivery mode updates Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/delivery-robots.md | 29 +++++++++++++++++------------ 1 file changed, 17 insertions(+), 12 deletions(-) diff --git a/modes/delivery-robots.md b/modes/delivery-robots.md index d170a91c3..9f5dc67ed 100644 --- a/modes/delivery-robots.md +++ b/modes/delivery-robots.md @@ -1,14 +1,14 @@ -# Mobility Data Specification: **Delivery Robots** +# Mobility Data Specification: **Delivery** MDS Modes - Delivery Robots -**Delivery Robots** refers to autonomous and remotely driven goods delivery devices. There can be one or multiple orders on different trips at the same time. The state machine tracks the trip states of the orders separately from the vehicle state. +**Delivery** refers to human, autonomous, and remotely driven goods, food, and freight delivery devices, vehicles, and services. No human passengers are transported in this mode. -See the [modes overview](/modes) for how the mode specific information below applies across MDS. +There can be one or multiple orders on different trips at the same time, connected via the journey identifier. The state machine tracks the trip states of the orders separately from the vehicle state. -## Robots Vs Other Delivery Types +See the [modes overview](/modes) for how the mode specific information below applies across MDS. -Autonomous and remotely piloted delivery robots do not require a driver, whereas other forms of deliveries may, e.g. in a commercial or private car, truck, bike, etc. For this MDS release, this mode is limited to deliveries where a human driver is not on board the vehicle doing the delivery, and human passengers are not being transported. +_Note: Any refences in the specification code or links to only "Delivery Robots" will be updated to the broader "Delivery" scope in the next MDS 3.0 release._ ## Table of Contents @@ -34,7 +34,7 @@ Autonomous and remotely piloted delivery robots do not require a driver, whereas ### Mode ID -The short name identifier for deliveries used across MDS is `delivery-robots`. +The short name identifier for deliveries used across MDS is `delivery-robots`. _To be `delivery` in the next breaking release._ [Top][toc] @@ -55,8 +55,9 @@ The `journey_id` field shall have a consistent value in overlapping trips. Journ ### Journey Attributes -The `journey_attributes` object is not used in this mode. +The `journey_attributes` object **may** have the following key value pairs: +- `shift_id` (UUID, optional): unique identifier for an entire driver's work shift, tied across multiple journeys and therefore trips. [Top][toc] @@ -64,8 +65,6 @@ The `journey_attributes` object is not used in this mode. Events require a valid `trip_id` in events where `event_types` contains `reservation_start`, `reservation_stop`, `trip_start`, `trip_pause`, `trip_resume`, `trip_end`,`trip_cancel`, `customer_cancellation`, `provider_cancellation`, or `driver_cancellation`. -For the robots, the notion of driver does not exist, even when remotely operated. - Additionally, `trip_id` is required if `event_types` contains a `trip_enter_jurisdiction` or `trip_leave_jurisdiction` event pertaining to a trip. ### Trip Type @@ -79,6 +78,7 @@ The `trip_type` field **must** have one of the following enumerated values: - `advertising`: displaying advertising and not making a delivery - `mapping`: mapping the environment and not making a delivery - `roaming`: moving in right of way but not in another trip_type +- `testing`: vehicle is making a test trip [Top][toc] @@ -87,9 +87,12 @@ The `trip_type` field **must** have one of the following enumerated values: The `trip_attributes` object **may** have the following key value pairs: - `driver_type` (enum, required): type of driver operating the device: `human`, `semi_autonomous`, `autonomous` -- `driver_id` (UUID, [Optional](../general-information.md#optional-fields)): consistent unique identifier of the primary driver. Could be based on software version or an internal human driver id. +- `driver_id` (UUID, [Optional](../general-information.md#optional-fields)): consistent unique identifier of the primary driver. Universal identifier of a specific driver, static across operators, like a driver's license number. Could also be used as a lookup in an agency's internal driver system. For autonomous or remote operations, could be based on software version, or an internal remote human driver id. +- `permit_number` (string, [Optional](../general-information.md#optional-fields)) - The permit number of the individual or organization that is operating the vehicle - `app_name` (text, [Optional](../general-information.md#optional-fields)): name of the app used to reserve the trip which could be provider's app or 3rd party app - `requested_time` ([Timestamp][ts], [Optional](../general-information.md#optional-fields)): when the customer requested the trip +- `pickup_address` (text, [Optional](../general-information.md#optional-fields)): street address where the trip originated from +- `dropoff_address` (text, [Optional](../general-information.md#optional-fields)): street address where the trip ended - `has_payload` (boolean, [Optional](../general-information.md#optional-fields)): is there any payload for any delivery included in the device at trip start. 1 = loaded, 0 = empty - `range` (integer, [Optional](../general-information.md#optional-fields)): estimated range in meters based on energy levels in device at trip start - `identification_required` (boolean, [Optional](../general-information.md#optional-fields)): does the cargo require providing customer identification before trip start or upon delivery? @@ -102,6 +105,8 @@ The `fare_attributes` object **may** have the following key value pairs: - `payment_type` (enumerated, [Optional](../general-information.md#optional-fields)): `account_number`, `cash`, `credit_card`, `mobile_app`, `no payment`, `phone`, `voucher`, `test` - `price` (currency, [Optional](../general-information.md#optional-fields)): Total price of the order +- `tip` (currency, [Optional](../general-information.md#optional-fields)) - amount of tip paid by customer +- `taxes` (currency, [Optional](../general-information.md#optional-fields)) - amount of taxes paid for the trip [Top][toc] @@ -259,9 +264,9 @@ This is the list of `vehicle_state` and `event_type` pairings that constitute th This *State Machine Diagram* shows how `vehicle_state` and `event_type` relate to each other and how vehicles can transition between states. See [Google Slides](https://docs.google.com/presentation/d/1fHdq1efbN5GSFDLF4en-oA_BYPXQKbbIbHff6iROJKA/edit#slide=id.g207ec9d0152_0_0) for the source file. -![Delivery Robots State Machine Diagram](delivery-robots-state-machine-diagram.svg) +![Delivery State Machine Diagram](delivery-robots-state-machine-diagram.svg) -#### Delivery Robots State Notes +#### Delivery State Notes When there is only one trip ongoing, `trip_state == vehicle_state` From 1de9548087a95f237d6cf5d17ab24ef906a1f127 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 23 Oct 2025 10:25:04 -0400 Subject: [PATCH 060/168] Updated delivery mode description Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modes/README.md b/modes/README.md index 26187fc7d..f797ec381 100644 --- a/modes/README.md +++ b/modes/README.md @@ -42,13 +42,13 @@ MDS is intended to be used for multiple transportation modes, including its orig - **[Micromobility](/modes/micromobility.md)** (`micromobility`) - dockless or docked small devices such as e-scooters and bikes. - **[Passenger services](/modes/passenger-services.md)** (`passenger-services`) - transporting individuals with a vehicle driven by another entity, including taxis, TNCs, and microtransit - **[Car share](/modes/car-share.md)** (`car-share`) - shared point-to-point and station-based multi-passenger vehicles. -- **[Delivery robots](/modes/delivery-robots.md)** (`delivery-robots`) - autonomous and remotely driven goods delivery devices +- **[Delivery](/modes/delivery-robots.md)** (`delivery-robots`) - human, autonomous, and remotely driven goods, food, and freight delivery devices, vehicles, and services.

MDS Mode - Micromobility       MDS Mode - Passenger Services       MDS Mode - Car Share       -MDS Mode - Delivery Robots +MDS Mode - Delivery


From 06e1bd9bd3116c0e8336dbb7cff8f899e993f4e1 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 23 Oct 2025 10:26:47 -0400 Subject: [PATCH 061/168] Update home page modes descriptions Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index b7c6fccfd..f309c8608 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ # About -The Mobility Data Specification (**MDS**), a project of the [Open Mobility Foundation](http://www.openmobilityfoundation.org) (**OMF**), is a set of Application Programming Interfaces (APIs) that helps cities better manage transportation in the public right of way, standardizing communication and data-sharing between cities and mobility providers, allowing cities to share and validate policy digitally, and enabling vehicle management and better outcomes for residents. Inspired in part by projects like [GTFS](https://developers.google.com/transit/gtfs/reference/) and [GBFS](https://github.com/MobilityData/gbfs), MDS is focused on managing mobility services such as dockless scooters, bicycles, mopeds, car share, delivery robots, fixed route services and shuttles, fleets, and passenger services. +The Mobility Data Specification (**MDS**), a project of the [Open Mobility Foundation](http://www.openmobilityfoundation.org) (**OMF**), is a set of Application Programming Interfaces (APIs) that helps cities better manage transportation in the public right of way, standardizing communication and data-sharing between cities and mobility providers, allowing cities to share and validate policy digitally, and enabling vehicle management and better outcomes for residents. Inspired in part by projects like [GTFS](https://developers.google.com/transit/gtfs/reference/) and [GBFS](https://github.com/MobilityData/gbfs), MDS is focused on managing mobility services such as dockless scooters, bicycles, mopeds, car share, food and goods delivery, sidewalk robots, fixed route services and shuttles, fleets, busses, and passenger services. **MDS** is a key piece of digital infrastructure that supports the effective implementation of mobility policies in cities around the world. For a high level overview and visuals, see the [About MDS](https://www.openmobilityfoundation.org/about-mds/) page on the OMF website. @@ -83,7 +83,7 @@ You can read more in our **[Understanding the different MDS APIs](https://github ## GBFS Requirement -All MDS compatible Provider and/or Agency feeds must also expose a public [GBFS](https://github.com/MobilityData/gbfs) feed for the micromobility and car share [modes](/modes) (passenger services and delivery robots may be optionally supported at the discretion of the agency running the program). Compatibility with [GBFS 3.0](https://github.com/MobilityData/gbfs/blob/v3.0/gbfs.md) or greater is advised, or the version recommended per MobilityData's [supported releases](https://github.com/MobilityData/gbfs?tab=readme-ov-file#current-version-recommended) guidance. Read MobilityData's RFP recommendations and required files list in their [GBFS and Shared Mobility Data Policy guide](https://gbfs.org/learn/data-policy/). +All MDS compatible Provider and/or Agency feeds must also expose a public [GBFS](https://github.com/MobilityData/gbfs) feed for the micromobility and car share [modes](/modes) (passenger services and delivery may be optionally supported at the discretion of the agency running the program). Compatibility with [GBFS 3.0](https://github.com/MobilityData/gbfs/blob/v3.0/gbfs.md) or greater is advised, or the version recommended per MobilityData's [supported releases](https://github.com/MobilityData/gbfs?tab=readme-ov-file#current-version-recommended) guidance. Read MobilityData's RFP recommendations and required files list in their [GBFS and Shared Mobility Data Policy guide](https://gbfs.org/learn/data-policy/). See our [MDS Vehicles Guide](https://github.com/openmobilityfoundation/mobility-data-specification/wiki/MDS-Vehicles) for how MDS Provider/Agency `/vehicles` can be used by regulators instead of the public GBFS `/vehicle_status` (formerly `/free_bike_status`). Additional information on MDS and GBFS can be found in this [guidance document](https://github.com/openmobilityfoundation/governance/blob/main/technical/GBFS_and_MDS.md). @@ -96,13 +96,13 @@ MDS supports multiple "modes", defined as a distinct regulatory framework for a - **[Micromobility](/modes/micromobility.md)** - dockless or docked small devices such as e-scooters and bikes. - **[Passenger services](/modes/passenger-services.md)** - transporting individuals with a vehicle driven by another entity, including taxis, TNCs, and microtransit - **[Car share](/modes/car-share.md)** - shared point-to-point and station-based multi-passenger vehicles. -- **[Delivery robots](/modes/delivery-robots.md)** - autonomous and remotely driven goods delivery devices +- **[Delivery](/modes/delivery-robots.md)** - human, autonomous, and remotely driven goods, food, and freight delivery devices, vehicles, and services.

MDS Mode - Micromobility       MDS Mode - Passenger Services       MDS Mode - Car Share       -MDS Mode - Delivery Robots +MDS Mode - Delivery


From 0fb78f9a2f1fbc473ae4933f959dac46f7f0de16 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 23 Oct 2025 11:09:44 -0400 Subject: [PATCH 062/168] Optional fields for city delivery needs Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/delivery-robots.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/modes/delivery-robots.md b/modes/delivery-robots.md index 9f5dc67ed..45dd1cff3 100644 --- a/modes/delivery-robots.md +++ b/modes/delivery-robots.md @@ -8,7 +8,7 @@ There can be one or multiple orders on different trips at the same time, connect See the [modes overview](/modes) for how the mode specific information below applies across MDS. -_Note: Any refences in the specification code or links to only "Delivery Robots" will be updated to the broader "Delivery" scope in the next MDS 3.0 release._ +_Note: Any references in the specification code or links to only "Delivery Robots" will be updated to the broader "Delivery" scope in the next MDS 3.0 release._ ## Table of Contents @@ -57,7 +57,7 @@ The `journey_id` field shall have a consistent value in overlapping trips. Journ The `journey_attributes` object **may** have the following key value pairs: -- `shift_id` (UUID, optional): unique identifier for an entire driver's work shift, tied across multiple journeys and therefore trips. +- `shift_id` (UUID, optional): unique identifier for a driver or operator's working shift, tied across multiple journeys and therefore trips. [Top][toc] @@ -92,8 +92,12 @@ The `trip_attributes` object **may** have the following key value pairs: - `app_name` (text, [Optional](../general-information.md#optional-fields)): name of the app used to reserve the trip which could be provider's app or 3rd party app - `requested_time` ([Timestamp][ts], [Optional](../general-information.md#optional-fields)): when the customer requested the trip - `pickup_address` (text, [Optional](../general-information.md#optional-fields)): street address where the trip originated from +- `origin_type` (string, [Optional](../general-information.md#optional-fields)): the name of the origin type for this delivery, e.g. ghost kitchen, individual restaurant, retail store, private delivery-courier, etc. - `dropoff_address` (text, [Optional](../general-information.md#optional-fields)): street address where the trip ended +- `destination_type` (string, [Optional](../general-information.md#optional-fields)): the name of the destination type for this delivery, e.g. restaurant, residential, commerical, etc. +- `destination_ - `has_payload` (boolean, [Optional](../general-information.md#optional-fields)): is there any payload for any delivery included in the device at trip start. 1 = loaded, 0 = empty +- `payload_type` (string, [Optional](../general-information.md#optional-fields)): the type or cargo or payload for this delivery, e.g. prepared food, parcel, medical, alcohol, grocery, etc. Could affect `fees`. - `range` (integer, [Optional](../general-information.md#optional-fields)): estimated range in meters based on energy levels in device at trip start - `identification_required` (boolean, [Optional](../general-information.md#optional-fields)): does the cargo require providing customer identification before trip start or upon delivery? @@ -107,6 +111,7 @@ The `fare_attributes` object **may** have the following key value pairs: - `price` (currency, [Optional](../general-information.md#optional-fields)): Total price of the order - `tip` (currency, [Optional](../general-information.md#optional-fields)) - amount of tip paid by customer - `taxes` (currency, [Optional](../general-information.md#optional-fields)) - amount of taxes paid for the trip +- `fees` (currency, [Optional](../general-information.md#optional-fields)): any additional fees (positive) or incentives/discounts (negative) for this trip [Top][toc] @@ -123,8 +128,9 @@ The `vehicle_attributes` object **may** have the following key value pairs: - `model` (string, [Optional](../general-information.md#optional-fields)) - `color` (string, [Optional](../general-information.md#optional-fields)) - `inspection_date` (date YYYY-MM-DD, [Optional](../general-information.md#optional-fields)): the date of the last inspection of the vehicle +- `software_version` (string, [Optional](../general-information.md#optional-fields)): the version of the software being used on this trip - `equipped_cameras` (integer, [Optional](../general-information.md#optional-fields)): number of cameras equipped on device -- `equipped_lighting` (integer, [Optional](../general-information.md#optional-fields)): number of lights used to illuminate the environment on the the device +- `equipped_lighting` (integer, [Optional](../general-information.md#optional-fields)): number of lights used to illuminate the environment on the device - `wheel_count` (integer, [Optional](../general-information.md#optional-fields)): number of wheels on the device - `width` (integer, [Optional](../general-information.md#optional-fields)): width in meters of the device - `length` (integer, [Optional](../general-information.md#optional-fields)): length in meters of the device @@ -248,7 +254,7 @@ This is the list of `vehicle_state` and `event_type` pairings that constitute th | `reserved` | `available` | N/A | `driver_cancellation` | The driver has canceled the reservation | | `reserved` | `available` | N/A | `provider_cancellation` | The provider has canceled the reservation | | `reserved` | `elsewhere` | N/A | `trip_leave_jurisdiction` | The vehicle has left the jurisdiction while in a reservation | -| `reserved` | `non_contactable` | N/A | `comms_lost` | The vehicle has gone of comms while being reserved by a customer | +| `reserved` | `non_contactable` | N/A | `comms_lost` | The vehicle has gone out of comms while being reserved by a customer | | `reserved` | `stopped` | `stopped` | `reservation_stop` | The vehicle has stopped to pickup reservation | | `stopped` | `available` | N/A | `customer_cancellation` | The customer has canceled the trip while the vehicle is waiting | | `stopped` | `available` | N/A | `driver_cancellation` | The driver has canceled the trip while waiting | From 6832e32207f30a201d5936357019ce9889add390 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 23 Oct 2025 11:17:32 -0400 Subject: [PATCH 063/168] Added statistical_areas option in Events Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- data-types.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/data-types.md b/data-types.md index 6e9b175af..81768fde8 100644 --- a/data-types.md +++ b/data-types.md @@ -111,7 +111,8 @@ Events represent changes in vehicle status. | `timestamp` | [Timestamp][ts] | Required | Date/time that event occurred at. See [Event Times][event-times] | | `publication_time` | [Timestamp][ts] | [Optional](./general-information.md#optional-fields) | Date/time that event became available through the status changes endpoint | | `location` | [GPS][gps] | Required | See also [Telemetry][telemetry]. | -| `event_geographies` | UUID[] | [Optional](./general-information.md#optional-fields) | **[Beta feature](/general-information.md#beta-features):** *Yes (as of 2.0.0)*. Array of Geography UUIDs consisting of every Geography that contains the location of the status change. See [Geography Driven Events][geography-driven-events]. Required if `location` is not present. | +| `event_geographies` | UUID[] | [Optional](./general-information.md#optional-fields) | **[Beta feature](/general-information.md#beta-features):** *Yes (as of 2.0.0)*. Array of Geography UUIDs consisting of every Geography that contains the location of the status change. See [Geography Driven Events][geography-driven-events]. Required if `location` and `statistical_area_ids` are not present. | +| `statistical_areas` | String | [Optional](./general-information.md#optional-fields) | Statistical area identifier(s) where the event occurred. e.g. US census area ids (tract, block group, block, etc), Canadian dissemination blocks or areas, UK output areas, etc, or any other pre-defined standard district, area, sector, neighborhood, etc. Details of the type and meaning of these identifiers are communicated between the public agency and operator outside of MDS. Note that custom geographic areas can be defined with `event_geographies`. Required if `location` and `event_geographies` are not present. | | `battery_percent` | Integer | [Required if Applicable](./general-information.md#required-if-applicable-fields) | Percent battery charge of vehicle, expressed between 0 and 100 | | `fuel_percent` | Integer | [Required if Applicable](./general-information.md#required-if-applicable-fields) | Percent fuel in vehicle, expressed between 0 and 100 | | `trip_ids` | UUID[] | [Required if Applicable](./general-information.md#required-if-applicable-fields) | Trip UUIDs (foreign key to /trips endpoint), required if `event_types` contains `trip_start`, `trip_end`, `trip_cancel`, `trip_enter_jurisdiction`, or `trip_leave_jurisdiction` | From 17765d207c607e303c125f961fb371acec1136db Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 23 Oct 2025 11:21:58 -0400 Subject: [PATCH 064/168] Fixed typos Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/delivery-robots.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/modes/delivery-robots.md b/modes/delivery-robots.md index 45dd1cff3..05b98cd86 100644 --- a/modes/delivery-robots.md +++ b/modes/delivery-robots.md @@ -77,7 +77,7 @@ The `trip_type` field **must** have one of the following enumerated values: - `return`: returning to home location or next trip start - `advertising`: displaying advertising and not making a delivery - `mapping`: mapping the environment and not making a delivery -- `roaming`: moving in right of way but not in another trip_type +- `roaming`: moving in right of way but not in another `trip_type` - `testing`: vehicle is making a test trip [Top][toc] @@ -89,13 +89,12 @@ The `trip_attributes` object **may** have the following key value pairs: - `driver_type` (enum, required): type of driver operating the device: `human`, `semi_autonomous`, `autonomous` - `driver_id` (UUID, [Optional](../general-information.md#optional-fields)): consistent unique identifier of the primary driver. Universal identifier of a specific driver, static across operators, like a driver's license number. Could also be used as a lookup in an agency's internal driver system. For autonomous or remote operations, could be based on software version, or an internal remote human driver id. - `permit_number` (string, [Optional](../general-information.md#optional-fields)) - The permit number of the individual or organization that is operating the vehicle -- `app_name` (text, [Optional](../general-information.md#optional-fields)): name of the app used to reserve the trip which could be provider's app or 3rd party app +- `app_name` (string, [Optional](../general-information.md#optional-fields)): name of the app used to reserve the trip which could be provider's app or 3rd party app - `requested_time` ([Timestamp][ts], [Optional](../general-information.md#optional-fields)): when the customer requested the trip -- `pickup_address` (text, [Optional](../general-information.md#optional-fields)): street address where the trip originated from +- `pickup_address` (string, [Optional](../general-information.md#optional-fields)): street address where the trip originated from - `origin_type` (string, [Optional](../general-information.md#optional-fields)): the name of the origin type for this delivery, e.g. ghost kitchen, individual restaurant, retail store, private delivery-courier, etc. -- `dropoff_address` (text, [Optional](../general-information.md#optional-fields)): street address where the trip ended +- `dropoff_address` (string, [Optional](../general-information.md#optional-fields)): street address where the trip ended - `destination_type` (string, [Optional](../general-information.md#optional-fields)): the name of the destination type for this delivery, e.g. restaurant, residential, commerical, etc. -- `destination_ - `has_payload` (boolean, [Optional](../general-information.md#optional-fields)): is there any payload for any delivery included in the device at trip start. 1 = loaded, 0 = empty - `payload_type` (string, [Optional](../general-information.md#optional-fields)): the type or cargo or payload for this delivery, e.g. prepared food, parcel, medical, alcohol, grocery, etc. Could affect `fees`. - `range` (integer, [Optional](../general-information.md#optional-fields)): estimated range in meters based on energy levels in device at trip start From 25a3608e16b215bd4a41f8c5b7a43ad6f311337c Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 23 Oct 2025 11:32:51 -0400 Subject: [PATCH 065/168] Delivery icon draft Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/delivery-robots.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modes/delivery-robots.md b/modes/delivery-robots.md index 05b98cd86..3d28e056f 100644 --- a/modes/delivery-robots.md +++ b/modes/delivery-robots.md @@ -1,6 +1,6 @@ # Mobility Data Specification: **Delivery** -MDS Modes - Delivery Robots +MDS Modes - Delivery Robots **Delivery** refers to human, autonomous, and remotely driven goods, food, and freight delivery devices, vehicles, and services. No human passengers are transported in this mode. From fbb4ef422681ce3077038943d2fdb86828fb536d Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 23 Oct 2025 11:33:28 -0400 Subject: [PATCH 066/168] Delivery icon draft Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modes/README.md b/modes/README.md index f797ec381..d0f93a8cf 100644 --- a/modes/README.md +++ b/modes/README.md @@ -48,7 +48,7 @@ MDS is intended to be used for multiple transportation modes, including its orig MDS Mode - Micromobility       MDS Mode - Passenger Services       MDS Mode - Car Share       -MDS Mode - Delivery +MDS Mode - Delivery


From 89639c109785594257b7593084d2f09a0dc30f73 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 23 Oct 2025 11:34:16 -0400 Subject: [PATCH 067/168] Delivery icon update Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modes/README.md b/modes/README.md index d0f93a8cf..c4415b078 100644 --- a/modes/README.md +++ b/modes/README.md @@ -48,7 +48,7 @@ MDS is intended to be used for multiple transportation modes, including its orig MDS Mode - Micromobility       MDS Mode - Passenger Services       MDS Mode - Car Share       -MDS Mode - Delivery +MDS Mode - Delivery


From c2c9f9ba5f346b5552a5c1966bf9d658462b3ddc Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 23 Oct 2025 11:34:42 -0400 Subject: [PATCH 068/168] Delivery icon draft Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index f309c8608..8dd8ffa34 100644 --- a/README.md +++ b/README.md @@ -102,7 +102,7 @@ MDS supports multiple "modes", defined as a distinct regulatory framework for a MDS Mode - Micromobility       MDS Mode - Passenger Services       MDS Mode - Car Share       -MDS Mode - Delivery +MDS Mode - Delivery


From 59920bda0156356b89d5837e701e9393bfbb5b16 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 14 Nov 2025 16:11:40 -0800 Subject: [PATCH 069/168] Clarified all modes and Delivery Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- README.md | 23 +++++++++++------------ 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 8dd8ffa34..23d0c60ca 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,7 @@ - [Modularity](#modularity) - [GBFS Requirement](#gbfs-requirement) - [Modes](#modes) + - [Future Modes](#future-modes) - [Versions](#versions) - [Technical Information](#technical-information) - [Data Validation](#data-validation) @@ -93,18 +94,16 @@ See our [MDS Vehicles Guide](https://github.com/openmobilityfoundation/mobility- MDS supports multiple "modes", defined as a distinct regulatory framework for a type of mobility service. See the [modes overview](/modes) or get started with a specific mode: -- **[Micromobility](/modes/micromobility.md)** - dockless or docked small devices such as e-scooters and bikes. -- **[Passenger services](/modes/passenger-services.md)** - transporting individuals with a vehicle driven by another entity, including taxis, TNCs, and microtransit -- **[Car share](/modes/car-share.md)** - shared point-to-point and station-based multi-passenger vehicles. -- **[Delivery](/modes/delivery-robots.md)** - human, autonomous, and remotely driven goods, food, and freight delivery devices, vehicles, and services. - -

-MDS Mode - Micromobility       -MDS Mode - Passenger Services       -MDS Mode - Car Share       -MDS Mode - Delivery -

-
+- **[Micromobility](/modes/micromobility.md)** - customer operated dockless or docked small devices moving customers and goods, such as scooters, bikeshare, cargo bikes, adaptive scooters, docked bikes, mopeds, trikes, and quadracycles. +- **[Passenger](/modes/passenger-services.md)** - employees and contractors, autonomous, and remotely operated transporting individuals or goods with a vehicle driven by another entity, including taxis, AV robotaxis, busses, transportation network companies (TNCs), commercial transport apps (CTAs), and private hire vehicles (PHVs), shuttles, paratransit, on demand vehicles, limosines, and microtransit. +- **[Fleet](/modes/car-share.md)** - customer, employees and contractors, autonomous, and remotely operated shared point-to-point, station-based, or free-floating multi-passenger or cargo vehicles like consumer car share, sanitation vehicles (garbage, recycling), city fleets, vehicle rentals, street sweepers, snow plows, utility services, construction, emergency response (police, fire, ambulance), tree maintenance, inspection and permitting vehicles, mobile health clinics, and heavy maintenance vehicles. +- **[Delivery](/modes/delivery-robots.md)** - employees and contractors, autonomous, and remotely operated sidewalk robots, app delivery, packages, freight, goods, food, private hire vehicles, postal service, medicine, and other delivery services. + +MDS Modes: Micromobility, Passenger, Fleet, Delivery + +## Future Modes + +Support for other shared modes, services, programs, and vehicles has been discussed for MDS, and could be created by public agencies and company requests in the future with non-breaking modifications in new MDS versions, for drone delivery, EVTOL air taxis, ferries, gondolas, subway, trolleys, trains, water taxis, helicopters, and planes. If interested, browse our [current conversations](https://github.com/openmobilityfoundation/mobility-data-specification/issues) or [start your own](https://github.com/openmobilityfoundation/mobility-data-specification/issues/new?template=feature-request---proposal.md). [Top][toc] From dd76c159091d87f41ab2217b12634df50aff9ed1 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 14 Nov 2025 16:21:54 -0800 Subject: [PATCH 070/168] Update Delivery icon Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/delivery-robots.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modes/delivery-robots.md b/modes/delivery-robots.md index 3d28e056f..341192193 100644 --- a/modes/delivery-robots.md +++ b/modes/delivery-robots.md @@ -1,8 +1,8 @@ # Mobility Data Specification: **Delivery** -MDS Modes - Delivery Robots +MDS Modes - Delivery Robots -**Delivery** refers to human, autonomous, and remotely driven goods, food, and freight delivery devices, vehicles, and services. No human passengers are transported in this mode. +**Delivery** refers to employees and contractors, autonomous, and remotely operated sidewalk robots, app delivery, packages, freight, goods, food, private hire vehicles, postal service, medicine, and other delivery services. There can be one or multiple orders on different trips at the same time, connected via the journey identifier. The state machine tracks the trip states of the orders separately from the vehicle state. From 0caf26c2a6f0c6dbf7d98203a39223ee1c6e4b17 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Sat, 15 Nov 2025 23:30:10 -0500 Subject: [PATCH 071/168] Update Modes page with mode details Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/README.md | 18 ++++++------------ 1 file changed, 6 insertions(+), 12 deletions(-) diff --git a/modes/README.md b/modes/README.md index c4415b078..a0c95907f 100644 --- a/modes/README.md +++ b/modes/README.md @@ -39,18 +39,12 @@ MDS is intended to be used for multiple transportation modes, including its orig ## List of Supported Modes -- **[Micromobility](/modes/micromobility.md)** (`micromobility`) - dockless or docked small devices such as e-scooters and bikes. -- **[Passenger services](/modes/passenger-services.md)** (`passenger-services`) - transporting individuals with a vehicle driven by another entity, including taxis, TNCs, and microtransit -- **[Car share](/modes/car-share.md)** (`car-share`) - shared point-to-point and station-based multi-passenger vehicles. -- **[Delivery](/modes/delivery-robots.md)** (`delivery-robots`) - human, autonomous, and remotely driven goods, food, and freight delivery devices, vehicles, and services. - -

-MDS Mode - Micromobility       -MDS Mode - Passenger Services       -MDS Mode - Car Share       -MDS Mode - Delivery -

-
+- **[Micromobility](/modes/micromobility.md)** (`micromobility`) - customer operated dockless or docked small devices moving customers and goods, such as scooters, bikeshare, cargo bikes, adaptive scooters, docked bikes, mopeds, trikes, and quadracycles. +- **[Passenger](/modes/passenger-services.md)** (`passenger-services`) - employees and contractors, autonomous, and remotely operated transporting individuals or goods with a vehicle driven by another entity, including taxis, AV robotaxis, busses, transportation network companies (TNCs), commercial transport apps (CTAs), and private hire vehicles (PHVs), shuttles, paratransit, on demand vehicles, limosines, and microtransit. _Note: this will use the `passenger` short name in the next breaking release._ +- **[Fleet](/modes/car-share.md)** (`car-share`) - customer, employees and contractors, autonomous, and remotely operated shared point-to-point, station-based, or free-floating multi-passenger or cargo vehicles like consumer car share, sanitation vehicles (garbage, recycling), city fleets, vehicle rentals, street sweepers, snow plows, utility services, construction, emergency response (police, fire, ambulance), tree maintenance, inspection and permitting vehicles, mobile health clinics, and heavy maintenance vehicles. _Note: this will use the `fleet` short name in the next breaking release._ +- **[Delivery](/modes/delivery-robots.md)** (`delivery-robots`) - employees and contractors, autonomous, and remotely operated sidewalk robots, app delivery, packages, freight, goods, food, private hire vehicles, postal service, medicine, and other delivery services. _Note: this will use the `delivery` short name in the next breaking release._ + +MDS Modes: Micromobility, Passenger, Fleet, Delivery [Top][toc] From b10994644dabfc89e65da17073bacba0a5a89905 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Sat, 15 Nov 2025 23:32:27 -0500 Subject: [PATCH 072/168] Reduce mode icon detail on home page Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- README.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 23d0c60ca..0574571bd 100644 --- a/README.md +++ b/README.md @@ -99,7 +99,13 @@ MDS supports multiple "modes", defined as a distinct regulatory framework for a - **[Fleet](/modes/car-share.md)** - customer, employees and contractors, autonomous, and remotely operated shared point-to-point, station-based, or free-floating multi-passenger or cargo vehicles like consumer car share, sanitation vehicles (garbage, recycling), city fleets, vehicle rentals, street sweepers, snow plows, utility services, construction, emergency response (police, fire, ambulance), tree maintenance, inspection and permitting vehicles, mobile health clinics, and heavy maintenance vehicles. - **[Delivery](/modes/delivery-robots.md)** - employees and contractors, autonomous, and remotely operated sidewalk robots, app delivery, packages, freight, goods, food, private hire vehicles, postal service, medicine, and other delivery services. -MDS Modes: Micromobility, Passenger, Fleet, Delivery +

+MDS Mode - Micromobility       +MDS Mode - Passenger       +MDS Mode - Fleet       +MDS Mode - Delivery +

+
## Future Modes From 16d4e44c49dcf1a4431cf9423541cf20f54465be Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Sat, 15 Nov 2025 23:36:40 -0500 Subject: [PATCH 073/168] Update car-share to fleet Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/car-share.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/modes/car-share.md b/modes/car-share.md index 9cea3484e..6a018b2ee 100644 --- a/modes/car-share.md +++ b/modes/car-share.md @@ -1,11 +1,13 @@ -# Mobility Data Specification: **Car Share** +# Mobility Data Specification: **Fleet** -MDS Modes - Car Share +MDS Modes - Fleet -**Car Share** refers to shared point-to-point and station-based mutli-passenger vehicles. Car Share typically has a driver who is the customer, and possibly one or more passengers or cargo. +**Fleet** refers to shared customer, employees and contractors, autonomous, and remotely operated shared point-to-point, station-based, or free-floating multi-passenger or cargo vehicles like consumer car share, sanitation vehicles (garbage, recycling), city fleets, vehicle rentals, street sweepers, snow plows, utility services, construction, emergency response (police, fire, ambulance), tree maintenance, inspection and permitting vehicles, mobile health clinics, and heavy maintenance vehicles. See the [modes overview](/modes) for how the mode specific information below applies across MDS. +_Note: Formerly called "Car Share". Any references in the specification code or links to only "Car Share" will be updated to the broader "Fleet" scope in the next MDS 3.0 release._ + ## Table of Contents - [Mode Attributes](#mode-attributes) @@ -30,7 +32,7 @@ See the [modes overview](/modes) for how the mode specific information below app ### Mode ID -The short name identifier for Car Share used across MDS is `car-share`. +The short name identifier for Fleet used across MDS is `car-share`. In a future release this will be updated to `fleet`. [Top][toc] @@ -54,7 +56,7 @@ The `journey_id` field shall have a consistent value in overlapping trips for a The `journey_attributes` object **may** have the following key value pairs: -- `reservation_id` (UUID, [Optional](../general-information.md#optional-fields)): unique identifier for an entire car share reservation, tied across multiple journeys and therefore trips. +- `reservation_id` (UUID, [Optional](../general-information.md#optional-fields)): unique identifier for an entire vehicle reservation, tied across multiple journeys and therefore trips. [Top][toc] @@ -154,7 +156,7 @@ This `accessibility_attributes` enum represents the accessibility attributes ava ### Vehicle States -Valid car share vehicle states are +Valid fleet vehicle states are - `removed` - `available` @@ -171,7 +173,7 @@ See [Vehicle States][vehicle-states] for descriptions. ### Event Types -Valid car share vehicle event types are +Valid fleet vehicle event types are - `charging_start` - `charging_end` @@ -262,7 +264,7 @@ This is the list of `vehicle_state` and `event_type` pairings that constitute th This *State Machine Diagram* shows how `vehicle_state` and `event_type` relate to each other and how vehicles can transition between states. See [Google Slides](https://docs.google.com/presentation/d/1fHdq1efbN5GSFDLF4en-oA_BYPXQKbbIbHff6iROJKA/edit#slide=id.g2072486e468_1_300) for the source file. -![Car Share State Machine Diagram](car-share-state-machine-diagram.svg) +![Fleet State Machine Diagram](car-share-state-machine-diagram.svg) [Top][toc] From acce9fafdc16d40a64a6eff9c89f3e6d25ef7d96 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Sat, 15 Nov 2025 23:41:37 -0500 Subject: [PATCH 074/168] Updates to Passenger mode Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/passenger-services.md | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/modes/passenger-services.md b/modes/passenger-services.md index 180c552a5..5c3e86838 100644 --- a/modes/passenger-services.md +++ b/modes/passenger-services.md @@ -1,14 +1,16 @@ -# Mobility Data Specification: **Passenger Services** +# Mobility Data Specification: **Passenger** -MDS Modes - Passenger Services +MDS Modes - Passenger -**Passenger Services** refers to taxis, transportation network companies (TNCs), commercial transport apps (CTAs), and private hire vehicles (PHVs). Passenger Services typically have a driver, one or more passengers, and multiple passengers may be on different trips. The state machine tracks the trip states of the passengers separately from the vehicle state. +**Passenger** refers to taxis, transportation network companies (TNCs), commercial transport apps (CTAs), and private hire vehicles (PHVs). Passenger services typically have a driver, one or more passengers, and multiple passengers may be on different trips. The state machine tracks the trip states of the passengers separately from the vehicle state. See the [modes overview](/modes) for how the mode specific information below applies across MDS. -## Taxi vs. TNC implementation differences +_Note: Formerly called "Passenger Services". Any references in the specification code or links to "Passenger Services" will be updated to the shorter "Passenger" scope in the next MDS 3.0 release._ -Taxis typically require explicit tracking of maintenance while TNCs typically do not. Public agency regulations, legal authority, differ based on local, state, and federal laws and jurisdictions between taxis, TNCs, CTAs, PHV, etc. +## Implementation differences + +Taxis and similar traditionally regulated services typically require explicit tracking of maintenance and labor, while TNCs or other contract driver services may not. Public agency regulations, legal authority, differ based on local, state, and federal laws and jurisdictions between taxis, TNCs, CTAs, PHV, AVs, etc. ## Table of Contents @@ -34,7 +36,7 @@ Taxis typically require explicit tracking of maintenance while TNCs typically do ### Mode ID -The short name identifier for Passenger Services used across MDS is `passenger-services`. +The short name identifier for Passenger mode used across MDS is `passenger-services`. In a future release this will be updated to `passenger`. [Top][toc] @@ -156,7 +158,7 @@ This `accessibility_attributes` enum represents the accessibility attributes ava ### Vehicle States -Valid passenger services vehicle states are +Valid passenger vehicle states are - `removed` - `available` @@ -173,7 +175,7 @@ See [Vehicle States][vehicle-states] for descriptions. ### Event Types -Valid passenger services vehicle event types are +Valid passenger vehicle event types are - `comms_lost` - `comms_restored` @@ -255,11 +257,11 @@ This is the list of `vehicle_state` and `event_type` pairings that constitute th This *State Machine Diagram* shows how `vehicle_state` and `event_type` relate to each other and how vehicles can transition between states. See [Google Slides](https://docs.google.com/presentation/d/1fHdq1efbN5GSFDLF4en-oA_BYPXQKbbIbHff6iROJKA/edit#slide=id.g2072486e468_1_19) for the source file. -![Passenger Services State Machine Diagram](passenger-services-state-machine-diagram.svg) +![Passenger State Machine Diagram](passenger-services-state-machine-diagram.svg) [Top][toc] -#### Passenger Services State Notes +#### Passenger State Notes When there is only one trip ongoing, `trip_state == vehicle_state` From ccfeb5b60d3e53f17abb89a0f04672ba41bbb9d5 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Sat, 15 Nov 2025 23:43:36 -0500 Subject: [PATCH 075/168] Update micromobility description Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/micromobility.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/modes/micromobility.md b/modes/micromobility.md index d1adb14e5..f8bc4f883 100644 --- a/modes/micromobility.md +++ b/modes/micromobility.md @@ -1,11 +1,13 @@ # Mobility Data Specification: **Micromobility** -MDS Modes - Micromobility +MDS Modes - Micromobility -"**Micromobility**" refers to single-occupancy modes of docked or dockless transportation such as e-scooters, e-bikes, and human-powered bikes. +"**Micromobility**" refers to customer operated dockless or docked small devices moving customers and goods, such as scooters, bikeshare, cargo bikes, adaptive scooters, docked bikes, mopeds, trikes, and quadracycles. See the [modes overview](/modes) for how the mode specific information below applies across MDS. +  + ## Table of Contents - [Mode Attributes](#mode-attributes) From 41e852f1efb6dc22936842b0ec17e783478c7f5f Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Sat, 15 Nov 2025 23:44:20 -0500 Subject: [PATCH 076/168] Passenger summary description update Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/passenger-services.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modes/passenger-services.md b/modes/passenger-services.md index 5c3e86838..34e4e0db5 100644 --- a/modes/passenger-services.md +++ b/modes/passenger-services.md @@ -2,7 +2,7 @@ MDS Modes - Passenger -**Passenger** refers to taxis, transportation network companies (TNCs), commercial transport apps (CTAs), and private hire vehicles (PHVs). Passenger services typically have a driver, one or more passengers, and multiple passengers may be on different trips. The state machine tracks the trip states of the passengers separately from the vehicle state. +**Passenger** refers to employees and contractors, autonomous, and remotely operated transporting individuals or goods with a vehicle driven by another entity, including taxis, AV robotaxis, busses, transportation network companies (TNCs), commercial transport apps (CTAs), and private hire vehicles (PHVs), shuttles, paratransit, on demand vehicles, limosines, and microtransit. See the [modes overview](/modes) for how the mode specific information below applies across MDS. From 03118c1a7c339a80bdc8aa52f8c086f03a18d06d Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Sat, 15 Nov 2025 23:45:45 -0500 Subject: [PATCH 077/168] Update delivery icon size Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/delivery-robots.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modes/delivery-robots.md b/modes/delivery-robots.md index 341192193..8955c801c 100644 --- a/modes/delivery-robots.md +++ b/modes/delivery-robots.md @@ -1,6 +1,6 @@ # Mobility Data Specification: **Delivery** -MDS Modes - Delivery Robots +MDS Modes - Delivery Robots **Delivery** refers to employees and contractors, autonomous, and remotely operated sidewalk robots, app delivery, packages, freight, goods, food, private hire vehicles, postal service, medicine, and other delivery services. @@ -8,7 +8,7 @@ There can be one or multiple orders on different trips at the same time, connect See the [modes overview](/modes) for how the mode specific information below applies across MDS. -_Note: Any references in the specification code or links to only "Delivery Robots" will be updated to the broader "Delivery" scope in the next MDS 3.0 release._ +_Note: Formerly called "Delivery Robots". Any references in the specification code or links to only "Delivery Robots" will be updated to the broader "Delivery" scope in the next MDS 3.0 release._ ## Table of Contents From 7f401dff303a7ef3c05a76b032291d15fe2138cc Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 17 Nov 2025 15:46:15 -0500 Subject: [PATCH 078/168] Added MDS Overview diagram Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- README.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 0574571bd..48627797e 100644 --- a/README.md +++ b/README.md @@ -24,11 +24,15 @@ The Mobility Data Specification (**MDS**), a project of the [Open Mobility Foundation](http://www.openmobilityfoundation.org) (**OMF**), is a set of Application Programming Interfaces (APIs) that helps cities better manage transportation in the public right of way, standardizing communication and data-sharing between cities and mobility providers, allowing cities to share and validate policy digitally, and enabling vehicle management and better outcomes for residents. Inspired in part by projects like [GTFS](https://developers.google.com/transit/gtfs/reference/) and [GBFS](https://github.com/MobilityData/gbfs), MDS is focused on managing mobility services such as dockless scooters, bicycles, mopeds, car share, food and goods delivery, sidewalk robots, fixed route services and shuttles, fleets, busses, and passenger services. +![MDS Main Logo](https://i.imgur.com/AiUedl3.png) + **MDS** is a key piece of digital infrastructure that supports the effective implementation of mobility policies in cities around the world. For a high level overview and visuals, see the [About MDS](https://www.openmobilityfoundation.org/about-mds/) page on the OMF website. -![MDS Main Logo](https://i.imgur.com/AiUedl3.png) +![MDS Overview Diagram](https://i.imgur.com/YsrCHPX.png) + +### History -**MDS** is an open-source project originally created by the [Los Angeles Department of Transportation](http://ladot.io) (LADOT). In November 2019, stewardship of MDS and the ownership of this repository were transferred to the [Open Mobility Foundation](http://www.openmobilityfoundation.org). GitHub automatically redirects any links to this repository from the `CityOfLosAngeles` organization to the `openmobilityfoundation` instead. MDS continues to be used by LADOT and [many other municipalities](#cities-using-mds) and companies. +**MDS** is an open-source project originally created by the [Los Angeles Department of Transportation](http://ladot.io) (LADOT). In November 2019, stewardship of MDS and the ownership of this repository were transferred to the [Open Mobility Foundation](http://www.openmobilityfoundation.org). GitHub automatically redirects any links to this repository from the `CityOfLosAngeles` organization to the `openmobilityfoundation` instead. MDS continues to be used by LADOT and [many other municipalities](#cities-using-mds) and companies (confirmed over 200 mobility operators, operating in over 1,000 cities globally, and 2 billion trips sent). [Top][toc] From 11d039380cb180762db39ff10a97b116e41d6424 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Wed, 19 Nov 2025 09:53:21 -0500 Subject: [PATCH 079/168] Added route_id and clarified connections with shifts, journeys Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/delivery-robots.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/modes/delivery-robots.md b/modes/delivery-robots.md index 8955c801c..148e48fcc 100644 --- a/modes/delivery-robots.md +++ b/modes/delivery-robots.md @@ -44,7 +44,7 @@ _See more available trip and fare attributes for any mode used in the [trips obj ### Journey ID -The `journey_id` field shall have a consistent value in overlapping trips. Journeys may be point-to-point, multi-segment, or multi-segment overlapping. +The `journey_id` field shall have a consistent value in overlapping trips. Journeys may be point-to-point, multi-segment, or multi-segment overlapping. Note that multiple journeys can be tied together with `shift_id` or `route_id` in [Journey Attributes](#journey-attributes). - **Example 1**: delivery to a single location, then return - **Example 2**: three overlapping delivery trips in the same journey @@ -58,6 +58,9 @@ The `journey_id` field shall have a consistent value in overlapping trips. Journ The `journey_attributes` object **may** have the following key value pairs: - `shift_id` (UUID, optional): unique identifier for a driver or operator's working shift, tied across multiple journeys and therefore trips. +- `route_id` (UUID, optional): unique identifier for a planned delivery or passenger route, tied across multiple journeys and therefore trips. + +Shifts and routes are made up of journeys, and journeys are made up of trips, so these can be connected in various ways as needed. [Top][toc] From 5488df3d63d29029bba29fda28e8ec20d974b15d Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Wed, 19 Nov 2025 10:08:08 -0500 Subject: [PATCH 080/168] Added `order` and `fare_order` arrays for individual order info Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/delivery-robots.md | 31 +++++++++++++++++-------------- 1 file changed, 17 insertions(+), 14 deletions(-) diff --git a/modes/delivery-robots.md b/modes/delivery-robots.md index 148e48fcc..d89d13b10 100644 --- a/modes/delivery-robots.md +++ b/modes/delivery-robots.md @@ -89,19 +89,21 @@ The `trip_type` field **must** have one of the following enumerated values: The `trip_attributes` object **may** have the following key value pairs: -- `driver_type` (enum, required): type of driver operating the device: `human`, `semi_autonomous`, `autonomous` +- `driver_type` (enum, required): type of driver operating the device: `human`, `semi_autonomous`, `autonomous`, `remote` - `driver_id` (UUID, [Optional](../general-information.md#optional-fields)): consistent unique identifier of the primary driver. Universal identifier of a specific driver, static across operators, like a driver's license number. Could also be used as a lookup in an agency's internal driver system. For autonomous or remote operations, could be based on software version, or an internal remote human driver id. - `permit_number` (string, [Optional](../general-information.md#optional-fields)) - The permit number of the individual or organization that is operating the vehicle -- `app_name` (string, [Optional](../general-information.md#optional-fields)): name of the app used to reserve the trip which could be provider's app or 3rd party app -- `requested_time` ([Timestamp][ts], [Optional](../general-information.md#optional-fields)): when the customer requested the trip -- `pickup_address` (string, [Optional](../general-information.md#optional-fields)): street address where the trip originated from -- `origin_type` (string, [Optional](../general-information.md#optional-fields)): the name of the origin type for this delivery, e.g. ghost kitchen, individual restaurant, retail store, private delivery-courier, etc. -- `dropoff_address` (string, [Optional](../general-information.md#optional-fields)): street address where the trip ended -- `destination_type` (string, [Optional](../general-information.md#optional-fields)): the name of the destination type for this delivery, e.g. restaurant, residential, commerical, etc. - `has_payload` (boolean, [Optional](../general-information.md#optional-fields)): is there any payload for any delivery included in the device at trip start. 1 = loaded, 0 = empty -- `payload_type` (string, [Optional](../general-information.md#optional-fields)): the type or cargo or payload for this delivery, e.g. prepared food, parcel, medical, alcohol, grocery, etc. Could affect `fees`. - `range` (integer, [Optional](../general-information.md#optional-fields)): estimated range in meters based on energy levels in device at trip start -- `identification_required` (boolean, [Optional](../general-information.md#optional-fields)): does the cargo require providing customer identification before trip start or upon delivery? +- `order` (Array, [Optional](../general-information.md#optional-fields)): Array of one or more orders with details for this trip: + - `order_id` (string, [Optional](../general-information.md#optional-fields)): identifier for this order, which could be used to cross reference in external system + - `app_name` (string, [Optional](../general-information.md#optional-fields)): name of the app used to reserve the trip which could be provider's app or 3rd party app + - `requested_time` ([Timestamp][ts], [Optional](../general-information.md#optional-fields)): when the customer requested the trip + - `pickup_address` (string, [Optional](../general-information.md#optional-fields)): street address where the trip originated from + - `origin_type` (string, [Optional](../general-information.md#optional-fields)): the name of the origin type for this delivery, e.g. ghost kitchen, individual restaurant, retail store, private delivery-courier, etc. + - `dropoff_address` (string, [Optional](../general-information.md#optional-fields)): street address where the trip ended + - `payload_type` (string, [Optional](../general-information.md#optional-fields)): the type or cargo or payload for this delivery, e.g. prepared food, parcel, medical, alcohol, grocery, etc. Could affect `fees`. + - `identification_required` (boolean, [Optional](../general-information.md#optional-fields)): does the cargo require providing customer identification before trip start or upon delivery? + - `destination_type` (string, [Optional](../general-information.md#optional-fields)): the name of the destination type for this delivery, e.g. restaurant, residential, commerical, etc. [Top][toc] @@ -109,11 +111,12 @@ The `trip_attributes` object **may** have the following key value pairs: The `fare_attributes` object **may** have the following key value pairs: -- `payment_type` (enumerated, [Optional](../general-information.md#optional-fields)): `account_number`, `cash`, `credit_card`, `mobile_app`, `no payment`, `phone`, `voucher`, `test` -- `price` (currency, [Optional](../general-information.md#optional-fields)): Total price of the order -- `tip` (currency, [Optional](../general-information.md#optional-fields)) - amount of tip paid by customer -- `taxes` (currency, [Optional](../general-information.md#optional-fields)) - amount of taxes paid for the trip -- `fees` (currency, [Optional](../general-information.md#optional-fields)): any additional fees (positive) or incentives/discounts (negative) for this trip +- `fare_order` (Array, [Optional](../general-information.md#optional-fields)): Array of one or more orders with details for this trip: + - `payment_type` (enumerated, [Optional](../general-information.md#optional-fields)): `account_number`, `cash`, `credit_card`, `mobile_app`, `no payment`, `phone`, `voucher`, `test` + - `price` (currency, [Optional](../general-information.md#optional-fields)): Total price of the order + - `tip` (currency, [Optional](../general-information.md#optional-fields)) - amount of tip paid by customer + - `taxes` (currency, [Optional](../general-information.md#optional-fields)) - amount of taxes paid for the trip + - `fees` (currency, [Optional](../general-information.md#optional-fields)): any additional fees (positive) or incentives/discounts (negative) for this trip [Top][toc] From 5bd3e59a95b34de394a9481fc9fba43b8fdb1fae Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Wed, 19 Nov 2025 10:15:26 -0500 Subject: [PATCH 081/168] Clarified that `statistical_areas` is an array Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- data-types.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/data-types.md b/data-types.md index 81768fde8..7ed34b9a5 100644 --- a/data-types.md +++ b/data-types.md @@ -112,7 +112,7 @@ Events represent changes in vehicle status. | `publication_time` | [Timestamp][ts] | [Optional](./general-information.md#optional-fields) | Date/time that event became available through the status changes endpoint | | `location` | [GPS][gps] | Required | See also [Telemetry][telemetry]. | | `event_geographies` | UUID[] | [Optional](./general-information.md#optional-fields) | **[Beta feature](/general-information.md#beta-features):** *Yes (as of 2.0.0)*. Array of Geography UUIDs consisting of every Geography that contains the location of the status change. See [Geography Driven Events][geography-driven-events]. Required if `location` and `statistical_area_ids` are not present. | -| `statistical_areas` | String | [Optional](./general-information.md#optional-fields) | Statistical area identifier(s) where the event occurred. e.g. US census area ids (tract, block group, block, etc), Canadian dissemination blocks or areas, UK output areas, etc, or any other pre-defined standard district, area, sector, neighborhood, etc. Details of the type and meaning of these identifiers are communicated between the public agency and operator outside of MDS. Note that custom geographic areas can be defined with `event_geographies`. Required if `location` and `event_geographies` are not present. | +| `statistical_areas` | Strings[] | [Optional](./general-information.md#optional-fields) | Array of statistical area identifier(s) where the event occurred. e.g. US census area IDs (tract, block group, block, etc), Canadian dissemination blocks or areas, UK output areas, etc, or any other pre-defined standard district, area, sector, neighborhood, etc. Details of the type and meaning of these identifiers are communicated between the public agency and operator outside of MDS. Note that instead of these pre-defined areas, custom geographic areas can be defined using `event_geographies`. Required if `location` and `event_geographies` are not present. | | `battery_percent` | Integer | [Required if Applicable](./general-information.md#required-if-applicable-fields) | Percent battery charge of vehicle, expressed between 0 and 100 | | `fuel_percent` | Integer | [Required if Applicable](./general-information.md#required-if-applicable-fields) | Percent fuel in vehicle, expressed between 0 and 100 | | `trip_ids` | UUID[] | [Required if Applicable](./general-information.md#required-if-applicable-fields) | Trip UUIDs (foreign key to /trips endpoint), required if `event_types` contains `trip_start`, `trip_end`, `trip_cancel`, `trip_enter_jurisdiction`, or `trip_leave_jurisdiction` | From 2be8286916fd5e3bbb2b5a3ae93a5d4eae3f7887 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Wed, 19 Nov 2025 13:34:40 -0500 Subject: [PATCH 082/168] Added the `enforcement` object for Incidents Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- data-types.md | 36 +++++++++++++++++++++++++++++++++++- 1 file changed, 35 insertions(+), 1 deletion(-) diff --git a/data-types.md b/data-types.md index 7ed34b9a5..d6380ebef 100644 --- a/data-types.md +++ b/data-types.md @@ -264,7 +264,7 @@ A Trip is defined by the following structure: | Field | Type | Required/Optional | Comments | | ---- | ---- | ---- | ---- | | `incident_id` | UUID | Required | ID used for uniquely identifying an Incident. | -| `incident_type` | Enum | Required | The type of incident. One of `unplanned_stop`, `remote_takeover`, `ads_engaged` (Automated Driving System), `ads_disengaged`, `tip_over`, `harsh_stopping` (e.g. braking), `harsh_starting` (e.g. acceleration), `near_miss`, `vandalism`, `theft`, `crash`. Exact definitions, and when and if which incident types are sent, come from the agency. | +| `incident_type` | Enum | Required | The type of incident. One of `unplanned_stop`, `remote_takeover`, `ads_engaged` (Automated Driving System), `ads_disengaged`, `tip_over`, `harsh_stopping` (e.g. braking), `harsh_starting` (e.g. acceleration), `near_miss`, `vandalism`, `theft`, `violation`, `crash`. Exact definitions, and when and if which incident types are sent, come from the public agency. | | `incident_time` | [Timestamp][ts] | Required | Date/time that incident first occurred. Note that this timestamp of the incident first occurance is independent of one or more Telemetry timestamps referenced via `incident_id`. Note that more frequent telemetry data points may be required when an incident is first discovered and occuring. | | `discovery_time` | [Timestamp][ts] | Required | Date/time that incident was first discovered by the operator. This may be at the same moment of the `incident_time`, or may have been discovered later. | | `publication_time` | [Timestamp][ts] | Required | Date/time that incident became first available to an agency through an Incident endpoint. | @@ -275,6 +275,7 @@ A Trip is defined by the following structure: | `medical_transport` | Boolean | Optional | If `true`, one or more individuals was transported via an ambulance or emergency response vehicle because of the incident. | | `report_id` | String | Optional | Identifier of an external report, from a police report, citation, internal system, service request, etc. The report source is communicated by the operator to the agency outside of MDS. | | `report_type` | String | Optional | Description of the type of report referenced by the `report_id`, eg. police, customer, remote operator, 311 call, etc. | +| `enforcement` | [Enforcement](#enforcement) | Optional | Enforcement and violation information related to this incident. Can be used for any `incident_type`. | | `external_references` | Array of [External Reference][external-reference] objects | Optional | One or more references to external data feeds, links, reports, or documents impacting or related to this Incident, as they become available. | | `contact_info` | String | Optional | Description of any relevant contact information about the incident the operator can provide. | | `preliminary` | Boolean | Optional | If `true`, then this information in this Incident is only preliminary, with more details and/or validation coming at a later date. If `false`, the information provided here is deemed valed with no more updates expected. | @@ -334,6 +335,39 @@ Other special group types may be added in future MDS releases as relevant agency [Top][toc] +## Enforcement + +The Enforcement object describes a specific set of features relevant to an enforcement [Incident](#incident). + +Where a citation could represent multiple violations, an enforcement object contains an array that enumerates the violations for a single citation. Where a citation can only represent a single violation, multiple Incidents may be published, each with a single violation in the array. + +The `enforcement` object is a JSON *object* with the following fields: + +| Name | Type | Required/Optional | Description | +| ---------------- | ------- | ----------------- | ------------- | +| `enforcement_id` | UUID | Required | An identifier unique to the enforcement incident, generated the first time an enforcement event is recorded, and referenced in future related enforcement events. Multiple Incidents (ex: `crash`, `violation`, or `vandalism`) that relate to the same enforcement activity can share the same `enforcement_id`. | +| `citation_id` | String | Optional | A unique id which represents a single citation. | +| `is_warning` | Boolean | Optional | A boolean value to indicate if the enforcement action is being processed as a warning. | +| `action_taken` | String | Optional | Indicates how the violation was enforced. Typical well-known values are `citation_registered`, `citation_posted`, `citation_served`, or `citation_emailed`. | +| `citation_cost` | String | Optional | The total cost of all violations associated to this enforcement action. | +| `violations` | Array of [Violations](#violations) | Optional | An array of Violation objects that indicate the one-to-many violations associated to this enforcement event. | + +[Top][toc] + +### Violations + +The Violations object describes the violations associated to an enforcement action that can occur as part of a [Enforcement](#enforcement) on an [Incident](#incident). + +The `violations` object is a JSON *object* with the following fields: + +| Name | Type | Required/Optional | Description | +| ---------------- | ------ | ----------------- | ------------- | +| `violation_code` | String | Optional | The unique code created by the municipality, city, county, state, federal, or enforcement agency to identify the type of rule being enforced. | +| `violation_name` | String | Optional | The city/municipal, county, state, provincial, or federal code that was violated. | +| `violation_cost` | String | Optional | The original cost associated with the violation. | + +[Top][toc] + ## External Reference An External Reference object describes a specific feature from an external data source that is relevant to a part of MDS data. This allows MDS users to reference other data sources that impact or provide information about an MDS object, and see more details at an external URL. Data sources can be anything available via a URL, including an existing data standard (CDS, WZDx, CWZ, GTFS, GBFS, MDS, etc), a custom feed, API, document, web page, report, etc. From fa0c520e3c2ae87d7e1841c5ece88088da1f6e28 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Wed, 19 Nov 2025 13:35:25 -0500 Subject: [PATCH 083/168] Added Enforcement and Violations to TOC Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- data-types.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/data-types.md b/data-types.md index d6380ebef..e6d4cdecc 100644 --- a/data-types.md +++ b/data-types.md @@ -17,6 +17,8 @@ This MDS data types page catalogs the objects (fields, types, requirements, desc - [Trips](#trips) - [Incidents](#incidents) - [Reports](#reports) +- [Enforcement](#enforcement) + - [Violations](#violations) - [External Reference](#external-reference) ## Vehicles From 80cfd3dfc09a9366013085780ffe1c6cd02f09bd Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Wed, 19 Nov 2025 13:36:18 -0500 Subject: [PATCH 084/168] Fixed Incidents links Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- data-types.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/data-types.md b/data-types.md index e6d4cdecc..bc715d9e7 100644 --- a/data-types.md +++ b/data-types.md @@ -339,7 +339,7 @@ Other special group types may be added in future MDS releases as relevant agency ## Enforcement -The Enforcement object describes a specific set of features relevant to an enforcement [Incident](#incident). +The Enforcement object describes a specific set of features relevant to an enforcement [Incident](#incidents). Where a citation could represent multiple violations, an enforcement object contains an array that enumerates the violations for a single citation. Where a citation can only represent a single violation, multiple Incidents may be published, each with a single violation in the array. @@ -358,7 +358,7 @@ The `enforcement` object is a JSON *object* with the following fields: ### Violations -The Violations object describes the violations associated to an enforcement action that can occur as part of a [Enforcement](#enforcement) on an [Incident](#incident). +The Violations object describes the violations associated to an enforcement action that can occur as part of a [Enforcement](#enforcement) on an [Incident](#incidents). The `violations` object is a JSON *object* with the following fields: From 9339b25fa217af9cce92d0a9ad7c0073aa090fcb Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Wed, 19 Nov 2025 15:37:35 -0500 Subject: [PATCH 085/168] Added gantt chart journey/order examples Using mermaid code Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/delivery-robots.md | 61 ++++++++++++++++++++++++++++++++++++++-- 1 file changed, 58 insertions(+), 3 deletions(-) diff --git a/modes/delivery-robots.md b/modes/delivery-robots.md index d89d13b10..a353de523 100644 --- a/modes/delivery-robots.md +++ b/modes/delivery-robots.md @@ -46,10 +46,65 @@ _See more available trip and fare attributes for any mode used in the [trips obj The `journey_id` field shall have a consistent value in overlapping trips. Journeys may be point-to-point, multi-segment, or multi-segment overlapping. Note that multiple journeys can be tied together with `shift_id` or `route_id` in [Journey Attributes](#journey-attributes). -- **Example 1**: delivery to a single location, then return -- **Example 2**: three overlapping delivery trips in the same journey +```mermaid +gantt + title Example 1: delivery to a single location, then return + dateFormat HH:mm + axisFormat %H:%M + + section Journey + Journey Start : vert, v1, 17:00, 2m + Journey : active, a, 17:00, 40m + Trip, delivery : b, 17:00, 20m + Trip, return : b, 17:20, 20m + + Journey End : vert, v1, 17:40, 5m +``` + +```mermaid +gantt + title Example 2: three overlapping delivery trips in the same journey + dateFormat HH:mm + axisFormat %H:%M + + section Journey + Journey Start : vert, v1, 17:00, 2m + Journey : active, a, 17:00, 50m + Trip, delivery : b, 17:00, 10m + Trip, delivery : b, 17:10, 20m + Trip, delivery : b, 17:30, 15m + Trip, return : b, 17:45, 5m + + Journey End : vert, v1, 17:50, 5m +``` -![Journey Diagram](https://i.imgur.com/Mx8jVQq.png) +```mermaid +gantt + title Example 3: delivery trips (w/ multiple orders) and journeys in the same longer route + dateFormat HH:mm + axisFormat %H:%M + + section Route + Route Start : vert, v1, 17:00, 2m + Route : done, a, 17:00, 70m + + section Journey 1 + Journey : active, a, 17:00, 50m + Trip, delivery : b, 17:00, 10m + Trip, delivery : b, 17:10, 15m + Trip, delivery : b, 17:25, 20m + Order 1: crit, done, c, 17:35, 5m + Order 2: crit, done, c, 17:40, 3m + Order 3: crit, done, c, 17:40, 5m + Trip, return : b, 17:45, 5m + + section Journey 2 + Journey : active, a, 17:50, 20m + Trip, delivery : b, 17:50, 10m + Trip, return : b, 18:00, 10m + + Route End : vert, v1, 18:10, 5m +``` [Top][toc] From 5ceea181a3976eb267c9a88c28be2f550913f318 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Wed, 19 Nov 2025 16:09:50 -0500 Subject: [PATCH 086/168] Shift to example 3 chart Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/delivery-robots.md | 29 ++++++++++++++++++----------- 1 file changed, 18 insertions(+), 11 deletions(-) diff --git a/modes/delivery-robots.md b/modes/delivery-robots.md index a353de523..73f45da25 100644 --- a/modes/delivery-robots.md +++ b/modes/delivery-robots.md @@ -80,30 +80,37 @@ gantt ```mermaid gantt - title Example 3: delivery trips (w/ multiple orders) and journeys in the same longer route + title Example 3: delivery trips (w/ multiple orders) and journeys in 2 routes and 1 driver shift dateFormat HH:mm axisFormat %H:%M - section Route - Route Start : vert, v1, 17:00, 2m - Route : done, a, 17:00, 70m + section Routes + Shift Start : vert, v1, 17:00, 2m + Shift : active, crit, a, 17:00, 90m + Route 1 : done, a, 17:00, 70m + Route 2: done, a, 18:10, 20m section Journey 1 Journey : active, a, 17:00, 50m Trip, delivery : b, 17:00, 10m - Trip, delivery : b, 17:10, 15m - Trip, delivery : b, 17:25, 20m - Order 1: crit, done, c, 17:35, 5m - Order 2: crit, done, c, 17:40, 3m - Order 3: crit, done, c, 17:40, 5m - Trip, return : b, 17:45, 5m + Trip, delivery : b, 17:10, 10m + Trip, delivery : b, 17:20, 20m + Order 1: crit, done, c, 17:25, 5m + Order 2: crit, done, c, 17:30, 5m + Order 3: crit, done, c, 17:30, 10m + Trip, return : b, 17:40, 10m section Journey 2 Journey : active, a, 17:50, 20m Trip, delivery : b, 17:50, 10m Trip, return : b, 18:00, 10m - Route End : vert, v1, 18:10, 5m + section Journey 3 + Journey : active, a, 18:10, 20m + Trip, delivery : b, 18:10, 12m + Trip, return : b, 18:22, 8m + + Shift End : vert, v1, 18:30, 5m ``` [Top][toc] From f0178799851fa080374ed1d446bf460179e0c397 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Wed, 19 Nov 2025 16:16:01 -0500 Subject: [PATCH 087/168] Added `delivery_time` field Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/delivery-robots.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/modes/delivery-robots.md b/modes/delivery-robots.md index 73f45da25..eb13c7894 100644 --- a/modes/delivery-robots.md +++ b/modes/delivery-robots.md @@ -159,7 +159,8 @@ The `trip_attributes` object **may** have the following key value pairs: - `order` (Array, [Optional](../general-information.md#optional-fields)): Array of one or more orders with details for this trip: - `order_id` (string, [Optional](../general-information.md#optional-fields)): identifier for this order, which could be used to cross reference in external system - `app_name` (string, [Optional](../general-information.md#optional-fields)): name of the app used to reserve the trip which could be provider's app or 3rd party app - - `requested_time` ([Timestamp][ts], [Optional](../general-information.md#optional-fields)): when the customer requested the trip + - `requested_time` ([Timestamp][ts], [Optional](../general-information.md#optional-fields)): when the customer requested the order + - `delivery_time` ([Timestamp][ts], [Optional](../general-information.md#optional-fields)): when the order was delivered (e.g. customer received their order, package was left, etc). - `pickup_address` (string, [Optional](../general-information.md#optional-fields)): street address where the trip originated from - `origin_type` (string, [Optional](../general-information.md#optional-fields)): the name of the origin type for this delivery, e.g. ghost kitchen, individual restaurant, retail store, private delivery-courier, etc. - `dropoff_address` (string, [Optional](../general-information.md#optional-fields)): street address where the trip ended From ca8bad9265754f355163c0a459f47099b229e52c Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Wed, 19 Nov 2025 16:18:26 -0500 Subject: [PATCH 088/168] Added `unload_time` field Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/delivery-robots.md | 1 + 1 file changed, 1 insertion(+) diff --git a/modes/delivery-robots.md b/modes/delivery-robots.md index eb13c7894..3ad30eac6 100644 --- a/modes/delivery-robots.md +++ b/modes/delivery-robots.md @@ -160,6 +160,7 @@ The `trip_attributes` object **may** have the following key value pairs: - `order_id` (string, [Optional](../general-information.md#optional-fields)): identifier for this order, which could be used to cross reference in external system - `app_name` (string, [Optional](../general-information.md#optional-fields)): name of the app used to reserve the trip which could be provider's app or 3rd party app - `requested_time` ([Timestamp][ts], [Optional](../general-information.md#optional-fields)): when the customer requested the order + - `unload_time` ([Timestamp][ts], [Optional](../general-information.md#optional-fields)): when the order was unloaded from the vehicle to finish delivery - `delivery_time` ([Timestamp][ts], [Optional](../general-information.md#optional-fields)): when the order was delivered (e.g. customer received their order, package was left, etc). - `pickup_address` (string, [Optional](../general-information.md#optional-fields)): street address where the trip originated from - `origin_type` (string, [Optional](../general-information.md#optional-fields)): the name of the origin type for this delivery, e.g. ghost kitchen, individual restaurant, retail store, private delivery-courier, etc. From 0beffc938827ad5d94d4aa43f2a8b6aca7c64c78 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Wed, 19 Nov 2025 20:30:05 -0500 Subject: [PATCH 089/168] More trip variety in examples Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/delivery-robots.md | 47 +++++++++++++++++++++++----------------- 1 file changed, 27 insertions(+), 20 deletions(-) diff --git a/modes/delivery-robots.md b/modes/delivery-robots.md index 3ad30eac6..b845189f1 100644 --- a/modes/delivery-robots.md +++ b/modes/delivery-robots.md @@ -52,28 +52,35 @@ gantt dateFormat HH:mm axisFormat %H:%M - section Journey - Journey Start : vert, v1, 17:00, 2m - Journey : active, a, 17:00, 40m - Trip, delivery : b, 17:00, 20m - Trip, return : b, 17:20, 20m + Start : vert, v1, 17:00, 2m - Journey End : vert, v1, 17:40, 5m + Trip - delivery : b, 17:00, 20m + Trip - return : b, 17:20, 20m + + End : vert, v1, 17:40, 5m ``` ```mermaid gantt - title Example 2: three overlapping delivery trips in the same journey + title Example 2: four overlapping delivery trips in the same journey dateFormat HH:mm axisFormat %H:%M section Journey Journey Start : vert, v1, 17:00, 2m + Journey : active, a, 17:00, 50m - Trip, delivery : b, 17:00, 10m - Trip, delivery : b, 17:10, 20m - Trip, delivery : b, 17:30, 15m - Trip, return : b, 17:45, 5m + Trip - delivery : b, 17:00, 10m + Stop 1 : vert, v1, 17:10, 2m + Trip - roaming : b, 17:10, 10m + Stop 2 : vert, v1, 17:20, 2m + Trip - delivery : b, 17:20, 15m + Trip - delivery : b, 17:20, 20m + Trip - delivery : b, 17:20, 25m + Stop 3 : vert, v1, 17:35, 2m + Stop 4 : vert, v1, 17:40, 2m + Stop 5 : vert, v1, 17:45, 2m + Trip - return : b, 17:45, 5m Journey End : vert, v1, 17:50, 5m ``` @@ -92,25 +99,25 @@ gantt section Journey 1 Journey : active, a, 17:00, 50m - Trip, delivery : b, 17:00, 10m - Trip, delivery : b, 17:10, 10m - Trip, delivery : b, 17:20, 20m + Trip - delivery : b, 17:00, 10m + Trip - delivery : b, 17:10, 10m + Trip - delivery : b, 17:20, 20m Order 1: crit, done, c, 17:25, 5m Order 2: crit, done, c, 17:30, 5m Order 3: crit, done, c, 17:30, 10m - Trip, return : b, 17:40, 10m + Trip - return : b, 17:40, 10m section Journey 2 Journey : active, a, 17:50, 20m - Trip, delivery : b, 17:50, 10m - Trip, return : b, 18:00, 10m + Trip - delivery : b, 17:50, 10m + Trip - return : b, 18:00, 10m section Journey 3 Journey : active, a, 18:10, 20m - Trip, delivery : b, 18:10, 12m - Trip, return : b, 18:22, 8m + Trip - delivery : b, 18:10, 12m + Trip - return : b, 18:22, 8m - Shift End : vert, v1, 18:30, 5m + Shift End : vert, v1, 18:30, 10m ``` [Top][toc] From e10f6a7ebe75448e58ee58921d6c46772bb2ecdd Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 25 Nov 2025 15:36:34 -0500 Subject: [PATCH 090/168] OMF styling on charts Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/delivery-robots.md | 60 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 59 insertions(+), 1 deletion(-) diff --git a/modes/delivery-robots.md b/modes/delivery-robots.md index b845189f1..919b8f14a 100644 --- a/modes/delivery-robots.md +++ b/modes/delivery-robots.md @@ -47,6 +47,25 @@ _See more available trip and fare attributes for any mode used in the [trips obj The `journey_id` field shall have a consistent value in overlapping trips. Journeys may be point-to-point, multi-segment, or multi-segment overlapping. Note that multiple journeys can be tied together with `shift_id` or `route_id` in [Journey Attributes](#journey-attributes). ```mermaid +--- +config: + theme: 'base' + themeVariables: + 'activeTaskBkgColor': '#155654' + 'activeTaskBorderColor': '#2AF1BE' + 'critBorderColor': '#2AF1BE' + 'doneTaskBkgColor': '#299c90' + 'doneTaskBorderColor': '#373737' + 'taskBkgColor': '#2AF1BE' + 'taskBorderColor': '#373737' + 'taskTextColor': '#373737' + 'taskTextDarkColor': 'white' + 'taskTextLightColor': '#373737' + 'vertLineColor': '#155654' + 'sectionBkgColor': '#ddd' + 'altSectionBkgColor': '#aaa' + 'sectionBkgColor2': '#777' +--- gantt title Example 1: delivery to a single location, then return dateFormat HH:mm @@ -61,6 +80,26 @@ gantt ``` ```mermaid +--- +displayMode: compact +config: + theme: 'base' + themeVariables: + 'activeTaskBkgColor': '#155654' + 'activeTaskBorderColor': '#2AF1BE' + 'critBorderColor': '#2AF1BE' + 'doneTaskBkgColor': '#299c90' + 'doneTaskBorderColor': '#373737' + 'taskBkgColor': '#2AF1BE' + 'taskBorderColor': '#373737' + 'taskTextColor': '#373737' + 'taskTextDarkColor': 'white' + 'taskTextLightColor': '#373737' + 'vertLineColor': '#155654' + 'sectionBkgColor': '#ddd' + 'altSectionBkgColor': '#aaa' + 'sectionBkgColor2': '#777' +--- gantt title Example 2: four overlapping delivery trips in the same journey dateFormat HH:mm @@ -86,6 +125,25 @@ gantt ``` ```mermaid +--- +config: + theme: 'base' + themeVariables: + 'activeTaskBkgColor': '#155654' + 'activeTaskBorderColor': '#2AF1BE' + 'critBorderColor': '#2AF1BE' + 'doneTaskBkgColor': '#299c90' + 'doneTaskBorderColor': '#373737' + 'taskBkgColor': '#2AF1BE' + 'taskBorderColor': '#373737' + 'taskTextColor': '#373737' + 'taskTextDarkColor': 'white' + 'taskTextLightColor': '#373737' + 'vertLineColor': '#155654' + 'sectionBkgColor': '#ddd' + 'altSectionBkgColor': '#aaa' + 'sectionBkgColor2': '#777' +--- gantt title Example 3: delivery trips (w/ multiple orders) and journeys in 2 routes and 1 driver shift dateFormat HH:mm @@ -94,7 +152,7 @@ gantt section Routes Shift Start : vert, v1, 17:00, 2m Shift : active, crit, a, 17:00, 90m - Route 1 : done, a, 17:00, 70m + Route 1: done, a, 17:00, 70m Route 2: done, a, 18:10, 20m section Journey 1 From 3e57c3354186f5321023aa0126e9758c66f8e6a3 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 1 Dec 2025 12:36:37 -0500 Subject: [PATCH 091/168] Add Greenwheels, update nextbike Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- providers.csv | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/providers.csv b/providers.csv index 17cf5035f..bd3bdba45 100644 --- a/providers.csv +++ b/providers.csv @@ -50,7 +50,7 @@ Whoosh,micromobility,3f8908a7-86fa-450d-8889-5d49077e06cd,https://whoosh.bike,ht Telofun,micromobility,3dd253d3-557c-4fcb-98da-9af3edeaaae6,https://www.tel-o-fun.co.il/,https://mds.fsmctmobility.com/api/mds/v1/, Gbike,micromobility,a50b796e-bca2-11ed-afa1-0242ac120002,https://gcoo.io/,https://mds.gcoo.io/,https://mds.gcoo.io/gbfs SURF,micromobility,66c43ccb-f9f9-4f70-9707-37301b9f49a8,https://www.surfingscooters.com,https://api.app.surf/mds,https://api.app.surf/gbfs/en -Nextbike,micromobility,31e54f5a-66c4-4a4c-bb6e-236351c90312,https://www.nextbike.de,https://platform-services.tier-services.io/data-sharing/mds/,https://api.nextbike.net/maps/gbfs/ +Nextbike,micromobility,31e54f5a-66c4-4a4c-bb6e-236351c90312,https://www.nextbike.de,https://mds-provider-api.nextbike.net,https://api.nextbike.net/maps/gbfs/ Scooty,micromobility,f4ac8ed2-d6c3-4e6f-b000-f69050e8a616,https://www.otoride.co/,https://oto-api.otoride.co/api/v2/mds/, Starship Technologies,delivery-robots,4a1524f3-8182-4b55-90c2-023c0cac84b9,https://www.starship.xyz/,https://mds-provider.starship.xyz/api/v1/mds/, Deutsche Bahn Connect,micromobility,dcd47d65-b290-4bd6-adf2-24578fbd9110,https://www.deutschebahnconnect.com/,https://bike-prod.msp.dbrent.net/mds/,https://apis.deutschebahn.com/db-api-marketplace/apis/shared-mobility-gbfs/2-2/de/CallABike/gbfs/ @@ -78,3 +78,4 @@ GoSharing,micromobility,1f859479-4427-4f52-8220-05c786436314,https://www.binbin. Mosaic Global,passenger-services,74ba2b64-c44f-474a-afbd-c2030fe162a6,https://mosaicglobaltransportation.com/,, Code3,passenger-services,b49a32d7-a418-4a6a-9f81-b5227d6c7ef8,https://code3transportation.com/,, Track My Shuttle,passenger-services,dd7db795-09c0-402f-9441-360235da3025,https://trackmyshuttle.com/,, +Greenwheels,car-share,5f88cd9e-2c7e-477a-a531-f68143121876,https://www.greenwheels.nl,, From c12db4b4df069591b9536823cf4aff5ec8e92073 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 5 Dec 2025 08:26:43 -0500 Subject: [PATCH 092/168] Added parcel counts, pickup location name Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/delivery-robots.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/modes/delivery-robots.md b/modes/delivery-robots.md index 919b8f14a..a612039e0 100644 --- a/modes/delivery-robots.md +++ b/modes/delivery-robots.md @@ -220,17 +220,20 @@ The `trip_attributes` object **may** have the following key value pairs: - `driver_id` (UUID, [Optional](../general-information.md#optional-fields)): consistent unique identifier of the primary driver. Universal identifier of a specific driver, static across operators, like a driver's license number. Could also be used as a lookup in an agency's internal driver system. For autonomous or remote operations, could be based on software version, or an internal remote human driver id. - `permit_number` (string, [Optional](../general-information.md#optional-fields)) - The permit number of the individual or organization that is operating the vehicle - `has_payload` (boolean, [Optional](../general-information.md#optional-fields)): is there any payload for any delivery included in the device at trip start. 1 = loaded, 0 = empty +- `parcel_count` (integer, [Optional](../general-information.md#optional-fields)) - count of individial parcels in the vehicle during this trip - `range` (integer, [Optional](../general-information.md#optional-fields)): estimated range in meters based on energy levels in device at trip start - `order` (Array, [Optional](../general-information.md#optional-fields)): Array of one or more orders with details for this trip: - `order_id` (string, [Optional](../general-information.md#optional-fields)): identifier for this order, which could be used to cross reference in external system - `app_name` (string, [Optional](../general-information.md#optional-fields)): name of the app used to reserve the trip which could be provider's app or 3rd party app - `requested_time` ([Timestamp][ts], [Optional](../general-information.md#optional-fields)): when the customer requested the order - `unload_time` ([Timestamp][ts], [Optional](../general-information.md#optional-fields)): when the order was unloaded from the vehicle to finish delivery - - `delivery_time` ([Timestamp][ts], [Optional](../general-information.md#optional-fields)): when the order was delivered (e.g. customer received their order, package was left, etc). - - `pickup_address` (string, [Optional](../general-information.md#optional-fields)): street address where the trip originated from + - `delivery_time` ([Timestamp][ts], [Optional](../general-information.md#optional-fields)): when the order was delivered (e.g. customer received their order, package was left, etc). + - `pickup_location_name` (string, [Optional](../general-information.md#optional-fields)): name of the location where the order originated from + - `pickup_address` (string, [Optional](../general-information.md#optional-fields)): street address where the order originated from - `origin_type` (string, [Optional](../general-information.md#optional-fields)): the name of the origin type for this delivery, e.g. ghost kitchen, individual restaurant, retail store, private delivery-courier, etc. - `dropoff_address` (string, [Optional](../general-information.md#optional-fields)): street address where the trip ended - - `payload_type` (string, [Optional](../general-information.md#optional-fields)): the type or cargo or payload for this delivery, e.g. prepared food, parcel, medical, alcohol, grocery, etc. Could affect `fees`. + - `payload_type` (string, [Optional](../general-information.md#optional-fields)): the primary type or cargo or payload for this delivery, e.g. prepared food, parcel, medical, alcohol, grocery, etc. Could affect `fees`. + - `parcel_count` (integer, [Optional](../general-information.md#optional-fields)) - count of parcels in this order - `identification_required` (boolean, [Optional](../general-information.md#optional-fields)): does the cargo require providing customer identification before trip start or upon delivery? - `destination_type` (string, [Optional](../general-information.md#optional-fields)): the name of the destination type for this delivery, e.g. restaurant, residential, commerical, etc. From 83acbf219c084981f4671e3a5b2a7624bce65626 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 8 Dec 2025 14:47:41 -0500 Subject: [PATCH 093/168] Added order_pickup_time and order_acceptance_time Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/delivery-robots.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/modes/delivery-robots.md b/modes/delivery-robots.md index a612039e0..943cff706 100644 --- a/modes/delivery-robots.md +++ b/modes/delivery-robots.md @@ -226,6 +226,8 @@ The `trip_attributes` object **may** have the following key value pairs: - `order_id` (string, [Optional](../general-information.md#optional-fields)): identifier for this order, which could be used to cross reference in external system - `app_name` (string, [Optional](../general-information.md#optional-fields)): name of the app used to reserve the trip which could be provider's app or 3rd party app - `requested_time` ([Timestamp][ts], [Optional](../general-information.md#optional-fields)): when the customer requested the order + - `order_acceptance_time` ([Timestamp][ts], [Optional](../general-information.md#optional-fields)): when the driver has accepted the order, either in person or virtually + - `order_pickup_time` ([Timestamp][ts], [Optional](../general-information.md#optional-fields)): when the driver has physicaly picked up the order - `unload_time` ([Timestamp][ts], [Optional](../general-information.md#optional-fields)): when the order was unloaded from the vehicle to finish delivery - `delivery_time` ([Timestamp][ts], [Optional](../general-information.md#optional-fields)): when the order was delivered (e.g. customer received their order, package was left, etc). - `pickup_location_name` (string, [Optional](../general-information.md#optional-fields)): name of the location where the order originated from From c9fa81a4817ce77daa6e4142aaf6b1c88ae807c1 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 9 Dec 2025 10:59:43 -0500 Subject: [PATCH 094/168] Note about default trip types Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- data-types.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/data-types.md b/data-types.md index bc715d9e7..6b295e7a8 100644 --- a/data-types.md +++ b/data-types.md @@ -237,7 +237,7 @@ A Trip is defined by the following structure: | `journey_id` | UUID | [Optional](./general-information.md#optional-fields) | A unique [journey ID](/modes#journey-id) for associating collections of trips for its [mode][modes] | | `journey_attributes` | Map | [Optional](./general-information.md#optional-fields) | **[Mode](/modes#list-of-supported-modes) Specific**. [Journey attributes](/modes#journey-attributes) given as unordered key-value pairs | | `trip_id` | UUID | Required | A unique ID for each trip | -| `trip_type` | Enum | [Optional](./general-information.md#optional-fields) | **[Mode](/modes#list-of-supported-modes) Specific**. The [trip type](/modes#trip-type) describing the purpose of a trip segment | +| `trip_type` | Enum | [Optional](./general-information.md#optional-fields) | **[Mode](/modes#list-of-supported-modes) Specific**. The [trip type](/modes#trip-type) describing the purpose of a trip segment. _Note: if not provided, only send trips of the **default** `trip_type`, as marked for each mode._ | | `trip_attributes` | Map | [Optional](./general-information.md#optional-fields) | **[Mode](/modes#list-of-supported-modes) Specific**. [Trip attributes](/modes#trip-attributes) given as unordered key-value pairs | | `fare_attributes` | Map | [Optional](./general-information.md#optional-fields) | **[Mode](/modes#list-of-supported-modes) Specific**. [Fare attributes](/modes#fare-attributes) given as unordered key-value pairs | | `start_time` | [Timestamp][ts] | Required | Start of the passenger/driver trip | From 9d37e41d0d1169f95505ab0ec6a7a64a928bbb03 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 9 Dec 2025 11:00:49 -0500 Subject: [PATCH 095/168] Default micro trip type Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/micromobility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modes/micromobility.md b/modes/micromobility.md index f8bc4f883..678e441a7 100644 --- a/modes/micromobility.md +++ b/modes/micromobility.md @@ -62,7 +62,7 @@ Required in events if `event_types` contains `trip_start`, `trip_end`, `trip_can The `trip_type` field **may** have one of the following values: -- `rider`: a single rider is taking a trip +- `rider` (_default_): a single rider is taking a trip - `rebalance`: vehicle ridden by operator to rebalance - `maintenance`: vehicles ridden by operator to perform maintenance or check operation From c55e9265520eb6e4b9b095b663399e7d51d3df07 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 9 Dec 2025 11:01:12 -0500 Subject: [PATCH 096/168] Default passenger trip type Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/passenger-services.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modes/passenger-services.md b/modes/passenger-services.md index 34e4e0db5..f1fe2d0e7 100644 --- a/modes/passenger-services.md +++ b/modes/passenger-services.md @@ -75,7 +75,7 @@ Additionally, `trip_id` is required if `event_types` contains a `trip_enter_juri The `trip_type` field **must** have one of the following enumerated values: -- `private`: a private trip made by one paying customer with one or more guests +- `private` (_default_): a private trip made by one paying customer with one or more guests - `shared`: a shared or pooled trip with more than one paying customer - `reservation`: en route to pickup a customer who has made a reservation, with no passengers in the vehicle - `empty`: vehicle movement with no passengers (outside of other `trip_type` values) that may need to be reported, e.g. for deadheading From 828c4774feaea9e8c01d834a1572db148a2933c3 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 9 Dec 2025 11:01:36 -0500 Subject: [PATCH 097/168] Default fleet trip type Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/car-share.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modes/car-share.md b/modes/car-share.md index 6a018b2ee..d7de703a1 100644 --- a/modes/car-share.md +++ b/modes/car-share.md @@ -72,7 +72,7 @@ Additionally, `trip_id` is required if `event_types` contains a `trip_enter_juri The `trip_type` field **must** have one of the following enumerated values: -- `private`: a private trip made by one paying customer with one or more guests +- `private` (_default_): a private trip made by one paying customer with one or more guests - `reservation`: en route to pickup a customer who has made a reservation, with no passengers in the vehicle - `empty`: vehicle movement with no customer (outside of other `trip_type` values) that may need to be reported, e.g. for maintenance From 43fd64e576c44b5bf88603edcbe3e25e2d1f3e40 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 9 Dec 2025 11:02:01 -0500 Subject: [PATCH 098/168] Default delivery trip type Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/delivery-robots.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modes/delivery-robots.md b/modes/delivery-robots.md index 943cff706..e9562c31c 100644 --- a/modes/delivery-robots.md +++ b/modes/delivery-robots.md @@ -203,7 +203,7 @@ The `trip_type` field is used to describe the trip itself. The `trip_type` field **must** have one of the following enumerated values: -- `delivery`: making a delivery +- `delivery` (_default_): making a delivery - `return`: returning to home location or next trip start - `advertising`: displaying advertising and not making a delivery - `mapping`: mapping the environment and not making a delivery From 15b7059af95be7e21d85f65b4c409543776487e7 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Wed, 10 Dec 2025 20:21:24 -0500 Subject: [PATCH 099/168] Update passenger example charts Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/passenger-services.md | 89 +++++++++++++++++++++++++++++++++++-- 1 file changed, 85 insertions(+), 4 deletions(-) diff --git a/modes/passenger-services.md b/modes/passenger-services.md index f1fe2d0e7..ee63c70ce 100644 --- a/modes/passenger-services.md +++ b/modes/passenger-services.md @@ -2,7 +2,7 @@ MDS Modes - Passenger -**Passenger** refers to employees and contractors, autonomous, and remotely operated transporting individuals or goods with a vehicle driven by another entity, including taxis, AV robotaxis, busses, transportation network companies (TNCs), commercial transport apps (CTAs), and private hire vehicles (PHVs), shuttles, paratransit, on demand vehicles, limosines, and microtransit. +**Passenger** refers to employees and contractors, autonomous, and remotely operated transporting individuals or goods with a vehicle driven by another entity, including taxis, AV robotaxis, busses, transportation network companies (TNCs), commercial transport apps (CTAs), and private hire vehicles (PHVs), shuttles, paratransit, on demand vehicles, limousines, and microtransit. See the [modes overview](/modes) for how the mode specific information below applies across MDS. @@ -48,10 +48,91 @@ _See more available trip and fare attributes for any mode used in the [trips obj The `journey_id` field shall have a consistent value in overlapping trips, e.g. "pooled" or "shared" rides with different start and/or end locations. Journeys may be point-to-point, multi-segment, or multi-segment overlapping. -- **Example 1**: one private trip with reservation, then return to depot -- **Example 2**: three shared trips, some overlapping +```mermaid +--- +config: + theme: 'base' + themeVariables: + 'activeTaskBkgColor': '#155654' + 'activeTaskBorderColor': '#2AF1BE' + 'critBorderColor': '#2AF1BE' + 'doneTaskBkgColor': '#299c90' + 'doneTaskBorderColor': '#373737' + 'taskBkgColor': '#2AF1BE' + 'taskBorderColor': '#373737' + 'taskTextColor': '#373737' + 'taskTextDarkColor': 'white' + 'taskTextLightColor': '#373737' + 'vertLineColor': '#155654' + 'sectionBkgColor': '#ddd' + 'altSectionBkgColor': '#aaa' + 'sectionBkgColor2': '#777' +--- +gantt + title Example 1: one private trip with reservation, then return to depot + dateFormat HH:mm + axisFormat %H:%M + + section Journey + Journey Start : vert, v1, 17:00, 2m + + Journey : active, a, 17:00, 55m + + Trip - reservation : b, 17:00, 10m + Trip - private : b, 17:10, 30m + Trip - empty : b, 17:40, 15m + + Journey End : vert, v1, 17:55, 5m +``` + + +```mermaid +--- +config: + theme: 'base' + themeVariables: + 'activeTaskBkgColor': '#155654' + 'activeTaskBorderColor': '#2AF1BE' + 'critBorderColor': '#2AF1BE' + 'doneTaskBkgColor': '#299c90' + 'doneTaskBorderColor': '#373737' + 'taskBkgColor': '#2AF1BE' + 'taskBorderColor': '#373737' + 'taskTextColor': '#373737' + 'taskTextDarkColor': 'white' + 'taskTextLightColor': '#373737' + 'vertLineColor': '#155654' + 'sectionBkgColor': '#ddd' + 'altSectionBkgColor': '#aaa' + 'sectionBkgColor2': '#777' +--- +gantt + title Example 2: three shared trips, some overlapping + dateFormat HH:mm + axisFormat %H:%M + + section Journey + + Journey : active, a, 17:00, 80m + + Trip 1 - reservation : b, 17:00, 10m + Trip 1 - shared : b, 17:10, 30m + Trip 2 - reservation : b, 17:20, 10m + Trip 2 - shared : b, 17:30, 30m + Trip 3 - reservation : b, 17:50, 20m + Trip 3 - private : b, 18:10, 10m + + Reserve Trip 1 : vert, v1, 17:00, 2m + Pickup Trip 1 : vert, v1, 17:10, 5m + Reserve Trip 2 : vert, v1, 17:20, 2m + Pickup Trip 2: vert, v1, 17:30, 5m + Dropoff Trip 1 : vert, v1, 17:40, 5m + Reserve Trip 3 : vert, v1, 17:50, 2m + Dropoff Trip 2 : vert, v1, 18:00, 5m + Pickup Trip 3 : vert, v1, 18:10, 5m + Dropoff Trip 3 : vert, v1, 18:20, 5m +``` -![Journey Diagram](https://i.imgur.com/ciNnDKC.png) [Top][toc] From eb6cc16149524e6b89af3f6a0cf78828e66290cd Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 11 Dec 2025 15:12:32 -0500 Subject: [PATCH 100/168] Formatting on examples Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/passenger-services.md | 23 +++++++++++------------ 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/modes/passenger-services.md b/modes/passenger-services.md index ee63c70ce..5a33cadd5 100644 --- a/modes/passenger-services.md +++ b/modes/passenger-services.md @@ -107,30 +107,29 @@ config: 'sectionBkgColor2': '#777' --- gantt - title Example 2: three shared trips, some overlapping + title Example 2: three shared trips, some overlapping, from airport to hotels dateFormat HH:mm axisFormat %H:%M section Journey - Journey : active, a, 17:00, 80m - + Journey - airport to hotels : active, a, 17:00, 80m Trip 1 - reservation : b, 17:00, 10m + Reserve Trip 1 : vert, v1, 17:00, 2m Trip 1 - shared : b, 17:10, 30m + Pickup Trip 1 : vert, v1, 17:10, 1m Trip 2 - reservation : b, 17:20, 10m + Reserve Trip 2 : vert, v1, 17:20, 2m Trip 2 - shared : b, 17:30, 30m + Pickup Trip 2: vert, v1, 17:30, 2m + Dropoff Trip 1 : vert, v1, 17:40, 2m Trip 3 - reservation : b, 17:50, 20m - Trip 3 - private : b, 18:10, 10m - - Reserve Trip 1 : vert, v1, 17:00, 2m - Pickup Trip 1 : vert, v1, 17:10, 5m - Reserve Trip 2 : vert, v1, 17:20, 2m - Pickup Trip 2: vert, v1, 17:30, 5m - Dropoff Trip 1 : vert, v1, 17:40, 5m Reserve Trip 3 : vert, v1, 17:50, 2m - Dropoff Trip 2 : vert, v1, 18:00, 5m - Pickup Trip 3 : vert, v1, 18:10, 5m + Dropoff Trip 2 : vert, v1, 18:00, 2m + Trip 3 - private : b, 18:10, 10m + Pickup Trip 3 : vert, v1, 18:10, 2m Dropoff Trip 3 : vert, v1, 18:20, 5m + ``` From 99f3de1c75ffd6c9066d9fa3bde7c0aac20ef0ef Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 11 Dec 2025 19:59:24 -0500 Subject: [PATCH 101/168] Car share example updates Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/car-share.md | 133 ++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 126 insertions(+), 7 deletions(-) diff --git a/modes/car-share.md b/modes/car-share.md index d7de703a1..bc57abd01 100644 --- a/modes/car-share.md +++ b/modes/car-share.md @@ -44,11 +44,129 @@ _See more available trip and fare attributes for any mode used in the [trips obj The `journey_id` field shall have a consistent value in overlapping trips for a single reservation period, e.g. trips taken by a customer between ignition states over the duration of their reservation. A reservation is the duration the customer has continuous exclusive access to the vehicle whether parked or in motion. Journeys may be point-to-point or multi-segment. -- **Example 1**: customer makes a reservation and company delivers vehicle to customer, then one trip point-to-point by customer, ending reservation at destination -- **Example 2**: customer reservation for multiple days with trips for errands, gas, entertainment, etc -- **Example 3**: one trip point-to-point with an employee moving the vehicle to a new location for maintenance +```mermaid +--- +config: + theme: 'base' + themeVariables: + 'activeTaskBkgColor': '#155654' + 'activeTaskBorderColor': '#2AF1BE' + 'critBorderColor': '#2AF1BE' + 'doneTaskBkgColor': '#299c90' + 'doneTaskBorderColor': '#373737' + 'taskBkgColor': '#2AF1BE' + 'taskBorderColor': '#373737' + 'taskTextColor': '#373737' + 'taskTextDarkColor': 'white' + 'taskTextLightColor': '#373737' + 'vertLineColor': '#155654' + 'sectionBkgColor': '#ddd' + 'altSectionBkgColor': '#aaa' + 'sectionBkgColor2': '#777' +--- +gantt + title Example 1: car share single journey, company delivers vehicle to customer, one trip point-to-point by customer + dateFormat HH:mm + axisFormat %H:%M + + section Journey + Journey Start : vert, v1, 17:00, 2m + + Journey : active, a, 17:00, 55m + + Trip - reservation : b, 17:00, 10m + Trip - private : b, 17:10, 45m + + Journey End : vert, v1, 17:55, 5m + +``` + +```mermaid +--- +config: + theme: 'base' + themeVariables: + 'activeTaskBkgColor': '#155654' + 'activeTaskBorderColor': '#2AF1BE' + 'critBorderColor': '#2AF1BE' + 'doneTaskBkgColor': '#299c90' + 'doneTaskBorderColor': '#373737' + 'taskBkgColor': '#2AF1BE' + 'taskBorderColor': '#373737' + 'taskTextColor': '#373737' + 'taskTextDarkColor': 'white' + 'taskTextLightColor': '#373737' + 'vertLineColor': '#155654' + 'sectionBkgColor': '#ddd' + 'altSectionBkgColor': '#aaa' + 'sectionBkgColor2': '#777' +--- +gantt + title Example 2: customer car share reservation for 4 days with a trip daily for errands, gas, entertainment, etc + dateFormat MM-DD + + section Reservation + Reservation Start : vert, v1, 03-20, 2m + + Reservation : done, a, 03-20, 4d + + Trip - private : b, 03-20, 1d + Trip - private : b, 03-21, 1d + Trip - private : b, 03-22, 1d + Trip - private : b, 03-23, 1d + + Reservation End : vert, v1, 03-24, 12h +``` + +```mermaid +--- +config: + theme: 'base' + themeVariables: + 'activeTaskBkgColor': '#155654' + 'activeTaskBorderColor': '#2AF1BE' + 'critBorderColor': '#2AF1BE' + 'doneTaskBkgColor': '#299c90' + 'doneTaskBorderColor': '#373737' + 'taskBkgColor': '#2AF1BE' + 'taskBorderColor': '#373737' + 'taskTextColor': '#373737' + 'taskTextDarkColor': 'white' + 'taskTextLightColor': '#373737' + 'vertLineColor': '#155654' + 'sectionBkgColor': '#ddd' + 'altSectionBkgColor': '#aaa' + 'sectionBkgColor2': '#777' +--- +gantt + title Example 3: a shift of a city snow plow driver, showing journeys from a central location, and trips inside the journeys + dateFormat HH:mm + axisFormat %H:%M + + section Shift + Shift Start : vert, v1, 17:00, 2m + Shift : done, a, 17:00, 90m + + section Journey 1 + Journey 1 : active, a, 17:00, 50m + Trip - private : b, 17:00, 10m + Trip - private : b, 17:10, 10m + Trip - private : b, 17:20, 20m + Trip - empty : b, 17:40, 10m + + section Journey 2 + Journey 2 : active, a, 17:50, 20m + Trip - private : b, 17:50, 10m + Trip - empty : b, 18:00, 10m + + section Journey 3 + Journey 3 : active, a, 18:10, 20m + Trip - private : b, 18:10, 12m + Trip - empty : b, 18:22, 8m + + Shift End : vert, v1, 18:30, 10m +``` -![Journey Diagram](https://i.imgur.com/FHxQLps.png) [Top][toc] @@ -57,6 +175,7 @@ The `journey_id` field shall have a consistent value in overlapping trips for a The `journey_attributes` object **may** have the following key value pairs: - `reservation_id` (UUID, [Optional](../general-information.md#optional-fields)): unique identifier for an entire vehicle reservation, tied across multiple journeys and therefore trips. +- `shift_id` (UUID, [Optional](../general-information.md#optional-fields)): unique identifier for a driver or operator's working shift, tied across multiple journeys and therefore trips. [Top][toc] @@ -72,9 +191,9 @@ Additionally, `trip_id` is required if `event_types` contains a `trip_enter_juri The `trip_type` field **must** have one of the following enumerated values: -- `private` (_default_): a private trip made by one paying customer with one or more guests -- `reservation`: en route to pickup a customer who has made a reservation, with no passengers in the vehicle -- `empty`: vehicle movement with no customer (outside of other `trip_type` values) that may need to be reported, e.g. for maintenance +- `private` (_default_): a private trip made by one paying customer with one or more guests, or a driver using the vehicle +- `reservation`: en route to pickup a customer who has made a reservation, or movement before starting an official task +- `empty`: vehicle movement with no customer or work (outside of other `trip_type` values) that may need to be reported, e.g. for maintenance, returning, etc [Top][toc] From 55e77b51b77146e920a709de25f53c36a3f72c01 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 12 Dec 2025 10:17:32 -0500 Subject: [PATCH 102/168] Update optional link Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/delivery-robots.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/modes/delivery-robots.md b/modes/delivery-robots.md index e9562c31c..d412404d7 100644 --- a/modes/delivery-robots.md +++ b/modes/delivery-robots.md @@ -81,7 +81,7 @@ gantt ```mermaid --- -displayMode: compact + config: theme: 'base' themeVariables: @@ -184,8 +184,8 @@ gantt The `journey_attributes` object **may** have the following key value pairs: -- `shift_id` (UUID, optional): unique identifier for a driver or operator's working shift, tied across multiple journeys and therefore trips. -- `route_id` (UUID, optional): unique identifier for a planned delivery or passenger route, tied across multiple journeys and therefore trips. +- `shift_id` (UUID, [Optional](../general-information.md#optional-fields)): unique identifier for a driver or operator's working shift, tied across multiple journeys and therefore trips. +- `route_id` (UUID, [Optional](../general-information.md#optional-fields)): unique identifier for a planned delivery or passenger route, tied across multiple journeys and therefore trips. Shifts and routes are made up of journeys, and journeys are made up of trips, so these can be connected in various ways as needed. From fa2d09f258214216386e3f7815fbe7df62cbab34 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 12 Dec 2025 10:18:38 -0500 Subject: [PATCH 103/168] Update optional links Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/passenger-services.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modes/passenger-services.md b/modes/passenger-services.md index 5a33cadd5..33e99b859 100644 --- a/modes/passenger-services.md +++ b/modes/passenger-services.md @@ -139,7 +139,7 @@ gantt The `journey_attributes` object **may** have the following key value pairs: -- `shift_id` (UUID, optional): unique identifier for an entire driver's work shift, tied across multiple journeys and therefore trips. +- `shift_id` (UUID, [Optional](../general-information.md#optional-fields)): unique identifier for an entire driver's work shift, tied across multiple journeys and therefore trips. [Top][toc] @@ -167,7 +167,7 @@ The `trip_type` field **must** have one of the following enumerated values: The `trip_attributes` object **may** have the following key value pairs: - `hail_type` (enumerated, required): `street_hail`, `phone_dispatch`, `phone`, `text`, `app` -- `app_name` (text, optional): name of the app used to reserve the trip which could be provider's app or 3rd party app +- `app_name` (text, [Optional](../general-information.md#optional-fields)): name of the app used to reserve the trip which could be provider's app or 3rd party app - `passenger_count` (integer, required): unique count of passengers transported during trip duration - `requested_time` ([Timestamp][ts], required): when the passenger requested the trip - `requested_trip_start_location` ([GPS](gps), [Conditionally Required](../general-information.md#conditionally-required-fields)): Location where the customer requested the trip to start (required if this is within jurisdictional boundaries) From 192011ba39b1efed59ad728b39dbbabdc1873520 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 12 Dec 2025 13:12:18 -0500 Subject: [PATCH 104/168] Update to mode overview images Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modes/README.md b/modes/README.md index a0c95907f..d245557a4 100644 --- a/modes/README.md +++ b/modes/README.md @@ -44,7 +44,7 @@ MDS is intended to be used for multiple transportation modes, including its orig - **[Fleet](/modes/car-share.md)** (`car-share`) - customer, employees and contractors, autonomous, and remotely operated shared point-to-point, station-based, or free-floating multi-passenger or cargo vehicles like consumer car share, sanitation vehicles (garbage, recycling), city fleets, vehicle rentals, street sweepers, snow plows, utility services, construction, emergency response (police, fire, ambulance), tree maintenance, inspection and permitting vehicles, mobile health clinics, and heavy maintenance vehicles. _Note: this will use the `fleet` short name in the next breaking release._ - **[Delivery](/modes/delivery-robots.md)** (`delivery-robots`) - employees and contractors, autonomous, and remotely operated sidewalk robots, app delivery, packages, freight, goods, food, private hire vehicles, postal service, medicine, and other delivery services. _Note: this will use the `delivery` short name in the next breaking release._ -MDS Modes: Micromobility, Passenger, Fleet, Delivery +MDS Modes: Micromobility, Passenger, Fleet, Delivery [Top][toc] From 0ae8aff653783c3a4bd63cfbdaeea93de1dd8ceb Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 8 Jan 2026 09:21:39 -0500 Subject: [PATCH 105/168] Moving GDE out of beta Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- data-types.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/data-types.md b/data-types.md index 6b295e7a8..3129ea1a4 100644 --- a/data-types.md +++ b/data-types.md @@ -113,7 +113,7 @@ Events represent changes in vehicle status. | `timestamp` | [Timestamp][ts] | Required | Date/time that event occurred at. See [Event Times][event-times] | | `publication_time` | [Timestamp][ts] | [Optional](./general-information.md#optional-fields) | Date/time that event became available through the status changes endpoint | | `location` | [GPS][gps] | Required | See also [Telemetry][telemetry]. | -| `event_geographies` | UUID[] | [Optional](./general-information.md#optional-fields) | **[Beta feature](/general-information.md#beta-features):** *Yes (as of 2.0.0)*. Array of Geography UUIDs consisting of every Geography that contains the location of the status change. See [Geography Driven Events][geography-driven-events]. Required if `location` and `statistical_area_ids` are not present. | +| `event_geographies` | UUID[] | [Optional](./general-information.md#optional-fields) | Array of Geography UUIDs consisting of every Geography that contains the location of the status change. See [Geography Driven Events][geography-driven-events]. Required if `location` and `statistical_area_ids` are not present. | | `statistical_areas` | Strings[] | [Optional](./general-information.md#optional-fields) | Array of statistical area identifier(s) where the event occurred. e.g. US census area IDs (tract, block group, block, etc), Canadian dissemination blocks or areas, UK output areas, etc, or any other pre-defined standard district, area, sector, neighborhood, etc. Details of the type and meaning of these identifiers are communicated between the public agency and operator outside of MDS. Note that instead of these pre-defined areas, custom geographic areas can be defined using `event_geographies`. Required if `location` and `event_geographies` are not present. | | `battery_percent` | Integer | [Required if Applicable](./general-information.md#required-if-applicable-fields) | Percent battery charge of vehicle, expressed between 0 and 100 | | `fuel_percent` | Integer | [Required if Applicable](./general-information.md#required-if-applicable-fields) | Percent fuel in vehicle, expressed between 0 and 100 | From b0916fc6b1535c4f798fff5f344728b817c81312 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 8 Jan 2026 09:22:55 -0500 Subject: [PATCH 106/168] Moving GDE Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- general-information.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/general-information.md b/general-information.md index 21a37cbb8..20ea6782a 100644 --- a/general-information.md +++ b/general-information.md @@ -165,8 +165,6 @@ For the purposes of this specification, the intersection of two geographic datat ## Geography-Driven Events -**[Beta feature](/general-information.md#beta-features):** _Yes (as of 1.1.0)_. [Leave feedback](https://github.com/openmobilityfoundation/mobility-data-specification/issues/670) - Geography-Driven Events (GDE) is an MDS feature for Agencies to perform complete Policy compliance monitoring without precise location data. Geography-Driven Events describe individual vehicles in realtime – not just aggregate data. However, rather than receiving the exact location of a vehicle, Agencies receive information about the vehicle's current geographic region. The regions used for Geography-Driven Events correspond to the Geographies in an Agency's current Policy. In this way, the data-shared using Geography-Driven Events is matched to an Agency's particular regulatory needs. See [this example](/policy/examples/requirements.md#geography-driven-events) for how to implement GDE using [Policy Requirements](/policy#requirement). @@ -187,8 +185,6 @@ Here's how it works in practice: Agencies that wish to use Geography-Driven Events do so by requiring a new `event_geographies` field in status events. When an Agency is using Geography-Driven Events, Providers must emit a new `changed_geographies` status event whenever a vehicle in a trip enters or leaves a Geography managed by a Policy. -During the Beta period for this feature, location and telemetry data remain required fields. This allows Agencies to test Geography-Driven Events, measuring its accuracy and efficacy against regulatory systems based on precise location data. After the beta period, if Geography-Driven Events is deemed by the OMF to be accurate and effective, the specification will evolve to allow cities to use Geography-Driven Events in lieu of location or telemetry data. - [Top][toc] ## Responses From a4e0ed1583ba5f6b4f3fddb0d75e275efb49dcc9 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 8 Jan 2026 09:24:21 -0500 Subject: [PATCH 107/168] Moving Jurisdiction out of beta Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- jurisdiction/README.md | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/jurisdiction/README.md b/jurisdiction/README.md index 64c64d4d9..471925cdf 100644 --- a/jurisdiction/README.md +++ b/jurisdiction/README.md @@ -7,7 +7,6 @@ This specification details the purpose, use cases, and schema for Jurisdictions. ## Table of Contents - [Background](#background) -- [Beta Feature](#beta-feature) - [Authorization](#authorization) - [Use Cases](#use-cases) - [Distribution](#distribution) @@ -37,14 +36,6 @@ A jurisdiction is: [Top][toc] -## Beta Feature - -The Jurisdictions API and all of its endpoints are marked as a [beta feature](https://github.com/openmobilityfoundation/mobility-data-specification/blob/feature-metrics/general-information.md#beta-features) starting in the 1.1.0 release. It has not been tested in real world scenarios, and may be adjusted in future releases. - -**[Beta feature](https://github.com/openmobilityfoundation/mobility-data-specification/blob/feature-metrics/general-information.md#beta-features)**: _Yes (as of 1.1.0)_. [Leave feedback](https://github.com/openmobilityfoundation/mobility-data-specification/issues/673) - -[Top][toc] - ### Authorization This endpoint should be made public. Authorization is not required. @@ -144,7 +135,6 @@ Gets all of an agency's Jurisdictions. Served by agencies. **Endpoint:** `/jurisdictions/` **Method:** `GET` -**[Beta feature][beta]:** _Yes (as of 1.1.0)_. [Leave feedback](https://github.com/openmobilityfoundation/mobility-data-specification/issues/673) **Schema:** [`jurisdiction` schema](#schema) **`data` Payload:** `{ "jurisdiction": [] }`, an array of [jurisdiction](#schema) objects @@ -173,7 +163,6 @@ Gets a single Jurisdictions. Served by agencies. **Endpoint:** `/jurisdictions/{jurisdiction_id}` **Method:** `GET` -**[Beta feature][beta]:** _Yes (as of 1.1.0)_. [Leave feedback](https://github.com/openmobilityfoundation/mobility-data-specification/issues/673) **Schema:** [`jurisdiction` schema](#schema) **`data` Payload:** `{ "jurisdiction": [] }`, an array of [jurisdiction](#schema) objects From 3c066f5831b89afb2b5fdfa818668c208dae7b59 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 8 Jan 2026 09:25:14 -0500 Subject: [PATCH 108/168] Moving Metrics out of beta Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- metrics/README.md | 11 +---------- 1 file changed, 1 insertion(+), 10 deletions(-) diff --git a/metrics/README.md b/metrics/README.md index 1ae397750..7d1cc7a0c 100644 --- a/metrics/README.md +++ b/metrics/README.md @@ -12,7 +12,6 @@ The Metrics API endpoints are intended to be implemented by regulatory agencies, - [Implementation](#implementation) - [Authorization](#authorization) - [Data Requirements](#data-requirements) -- [Beta Feature](#beta-feature) - [Date and Time Format](#date-and-time-format) - [Data Schema](#data-schema) - [Data Redaction](#data-redaction) @@ -83,14 +82,6 @@ Metrics may be a supplement for other more granular MDS data, and may be used to [Top][toc] -## Beta Feature - -**[Beta feature](https://github.com/openmobilityfoundation/mobility-data-specification/blob/feature-metrics/general-information.md#beta-features)**: _Yes (as of 1.0.0)_. [Leave feedback](https://github.com/openmobilityfoundation/mobility-data-specification/issues/671) - -The Metrics API and all of its endpoints are marked as a [beta feature](https://github.com/openmobilityfoundation/mobility-data-specification/blob/feature-metrics/general-information.md#beta-features). It has not been tested in real world scenarios, and may be adjusted in future releases. - -[Top][toc] - ## Date and Time Format All dates and times (datetime) are [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) formatted strings (YYYY-MM-DDTHHMM), with minute granularity supported and time zone (default UTC) or included offset. Dates and times may also be specified using a numeric *Unix epoch/timestamp* @@ -111,7 +102,7 @@ Some combinations of dimensions, filters, time, and geography may return a small **If the query returns fewer than `10` trips in a count, then that row's count value is returned as "-1".** Note "0" values are also returned as "-1" since the goal is to group both low and no count values together for privacy. -The OMF suggests a k-value of 10 is an appropriate starting point for safe anonymization, absent analysis and a further decision from the agency. As Metrics is in [beta](#beta-feature), this value may be adjusted in future releases and/or may become dynamic to account for specific categories of use cases and users. To improve the specification and to inform future guidance, beta users are encouraged to share their feedback and questions about k-values on this [discussion thread](https://github.com/openmobilityfoundation/mobility-data-specification/discussions/622). +The OMF suggests a k-value of 10 is an appropriate starting point for safe anonymization, absent analysis and a further decision from the agency. This value may be adjusted in future releases and/or may become dynamic to account for specific categories of use cases and users. To improve the specification and to inform future guidance, users are encouraged to share their feedback and questions about k-values on this [discussion thread](https://github.com/openmobilityfoundation/mobility-data-specification/discussions/622). The k-value being used is always returned in the Metrics Query API [response](/metrics#response-1) to provide important context for the data consumer on the data redaction that is occurring. From c3a46e6a4d577fda39e86e64b38e4c1fc8c7a249 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 8 Jan 2026 09:26:55 -0500 Subject: [PATCH 109/168] Moving Stops out of beta Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- provider/README.md | 7 ------- 1 file changed, 7 deletions(-) diff --git a/provider/README.md b/provider/README.md index 35bc38828..dea447e48 100644 --- a/provider/README.md +++ b/provider/README.md @@ -192,7 +192,6 @@ Vehicle information about all device IDs present in other MDS endpoints must be **Endpoint:** `/vehicles/{device_id}` **Method:** `GET` -**[Beta feature][beta]:** No (as of 1.2.0) **Schema:** See [`mds-openapi`](https://github.com/openmobilityfoundation/mds-openapi) repository for schema. **Payload:** `{ "vehicles": [] }`, an array of [Vehicle][vehicles] objects @@ -251,7 +250,6 @@ In addition to the standard [Provider payload wrapper](#response-format), respon **Endpoint:** `/vehicles/status/{device_id}` **Method:** `GET` -**[Beta feature][beta]:** No (as of 1.2.0) **Schema:** See [`mds-openapi`](https://github.com/openmobilityfoundation/mds-openapi) repository for schema. **Payload:** `{ "vehicles_status": [] }`, an array of [Vehicle Status][vehicle-status] objects @@ -300,7 +298,6 @@ Unless stated otherwise by the municipality, the trips endpoint must return all **Endpoint:** `/trips` **Method:** `GET` -**[Beta feature][beta]:** No **Schema:** See [`mds-openapi`](https://github.com/openmobilityfoundation/mds-openapi) repository for schema. **Payload:** `{ "trips": [] }`, an array of [Trip][trips] objects @@ -402,7 +399,6 @@ Unless stated otherwise by the municipality, this endpoint must return only thos **Endpoint:** `/events/historical` **Method:** `GET` -**[Beta feature][beta]:** No **Schema:** See [`mds-openapi`](https://github.com/openmobilityfoundation/mds-openapi) repository for schema. **Payload:** `{ "events": [] }`, an array of [Events](/data-types.md#events) object @@ -464,7 +460,6 @@ See also [Telemetry][telemetry]. **Endpoint:** `/events/recent` **Method:** `GET` -**[Beta feature][beta]:** No (as of 1.0.0) **Schema:** See [`mds-openapi`](https://github.com/openmobilityfoundation/mds-openapi) repository for schema. **Payload:** `{ "events": [] }`, an array of [Events](/data-types.md#events) object objects @@ -511,7 +506,6 @@ In addition to the standard [Provider payload wrapper](#response-format), respon **Endpoint:** `/stops/{stop_id}` **Method:** `GET` -**[Beta feature][beta]:** Yes (as of 1.0.0). [Leave feedback](https://github.com/openmobilityfoundation/mobility-data-specification/issues/638) **Schema:** See [`mds-openapi`](https://github.com/openmobilityfoundation/mds-openapi) repository for schema. **Payload:** `{ "stops": [] }`, an array of [Stops][stops] @@ -581,7 +575,6 @@ The authenticated reports are monthly, historic flat files that may be pre-gener **Endpoint:** `/reports` **Method:** `GET` -**[Beta feature][beta]:** No (as of 2.0.0). [Leave feedback](https://github.com/openmobilityfoundation/mobility-data-specification/issues/672) **Usage note:** This endpoint uses media-type `text/vnd.mds+csv` instead of `application/vnd.mds+json`, see [Versioning][versioning]. **Schema:** See [`mds-openapi`](https://github.com/openmobilityfoundation/mds-openapi) repository for schema. **Filename:** monthly file named by year and month, e.g. `/reports/YYYY-MM.csv` From f8030254f60c447f798604ad48e8613669ad45a7 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 8 Jan 2026 09:29:26 -0500 Subject: [PATCH 110/168] Cleaning up beta references Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- policy/README.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/policy/README.md b/policy/README.md index 6c7e32a46..b1ff89833 100644 --- a/policy/README.md +++ b/policy/README.md @@ -250,7 +250,6 @@ Note that you may only create a new MDS Policy. Retired policies are simply refe **Endpoint**: `/requirements/` **Method**: `GET` -**[Beta feature](/general-information.md#beta-features)**: *No (as of 2.0.0)*. **Authorization**: public **Schema:** See [`mds-openapi`](https://github.com/openmobilityfoundation/mds-openapi) repository for schema. **`data` Payload**: `{ requirements: [] }`, JSON objects that follow the schema [outlined here](#requirement). @@ -442,8 +441,6 @@ An individual `Rule` object is defined by the following fields: Rate-related properties can currently be specified on all rule types except `user`, i.e. any rule that can be measured. -**[Beta feature](/general-information.md#beta-features)**: *No (as of 2.0.0)*. - #### Rate Amounts The amount of a rate applied when this rule applies, if applicable (default zero). A positive integer rate amount represents a fee, while a negative integer represents a subsidy. Rate amounts are given in the `currency` defined in the [Policy](#policy). @@ -704,7 +701,7 @@ Contains metadata applicable to the agency and at the top of its [Requirement](# Contains information about an agency's programs, with links to policy documents, and a list of providers and data specs/APIs/endpoints/fields that the program applies to over a certain time frame in its [Requirement](#requirement) data feed in the `required_data_specs` section. -Unique combinations for data specs, specific providers, vehicle types, policies, and dates (past, current, or future) can be defined. For example an agency can define MDS version 1.2.0 and GBFS 2.2 for Provider #1 in a pilot with beta endpoints and optional fields, MDS version 1.2.0 for other providers without beta features starting a month from now, and MDS version 1.1.0 for Provider #2 with docked bikeshare. +Unique combinations for data specs, specific providers, vehicle types, policies, and dates (past, current, or future) can be defined. For example an agency can define MDS version 1.2.0 and GBFS 2.2 for Provider #1 in a pilot with testing endpoints and optional fields, MDS version 1.2.0 for other providers without testing features starting a month from now, and MDS version 1.1.0 for Provider #2 with docked bikeshare. ```jsonc // ... From 8eab6ea29906ab3a2823f0c17093a9d39be6b267 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 8 Jan 2026 09:30:23 -0500 Subject: [PATCH 111/168] Moving GDE from beta Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/micromobility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modes/micromobility.md b/modes/micromobility.md index 678e441a7..a9df92b30 100644 --- a/modes/micromobility.md +++ b/modes/micromobility.md @@ -212,7 +212,7 @@ Vehicles can exit the `missing` state to any other state with the following even | `non_operational` | `available` | `on_hours` | The vehicle has entered operating hours (per the regulator or per the provider) | | `non_operational` | `available` | `system_resume` | The vehicle is available because e.g. weather suspension or temporary regulations ended | | `non_operational`, `non_contactable`, `missing` | `available` | `unspecified` | The vehicle became available, but the provider cannot definitively (yet) specify the reason. Generally, regulator Service-Level Agreements will limit the amount of time a vehicle's last event type may be `unspecified`. | -| `on_trip` | `on_trip ` | `changed_geographies` | **[Beta feature](/general-information.md#beta-features):** *Yes (as of 1.1.0)*. The vehicle has entered or left one or more Geographies managed by a Policy. See [Geography Driven Events](#geography-driven-events). | +| `on_trip` | `on_trip ` | `changed_geographies` | The vehicle has entered or left one or more Geographies managed by a Policy. See [Geography Driven Events](#geography-driven-events). | | `on_trip` | `available` | `trip_cancel` | A trip was initiated, then canceled prior to moving any distance | | `on_trip` | `available` | `trip_end` | A trip has ended, and the vehicle is again available for rent | | `on_trip` | `elsewhere` | `trip_leave_jurisdiction` | A vehicle on a trip left the jurisdiction | From e4e3b67ee1efcc219d9d8b7d42149ba8f9aa4f8b Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 12 Jan 2026 13:59:15 -0500 Subject: [PATCH 112/168] Clarified return trip type Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/delivery-robots.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modes/delivery-robots.md b/modes/delivery-robots.md index d412404d7..65efbb9a0 100644 --- a/modes/delivery-robots.md +++ b/modes/delivery-robots.md @@ -204,7 +204,7 @@ The `trip_type` field is used to describe the trip itself. The `trip_type` field **must** have one of the following enumerated values: - `delivery` (_default_): making a delivery -- `return`: returning to home location or next trip start +- `return`: returning to home location or pickup point - `advertising`: displaying advertising and not making a delivery - `mapping`: mapping the environment and not making a delivery - `roaming`: moving in right of way but not in another `trip_type` From 9f6584338772e63deb0208efee3c0886c4de7e61 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 12 Jan 2026 14:06:19 -0500 Subject: [PATCH 113/168] Event type link fix Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- data-types.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/data-types.md b/data-types.md index 3129ea1a4..9e1010e0e 100644 --- a/data-types.md +++ b/data-types.md @@ -401,5 +401,5 @@ An `external_reference` is a JSON *array* with the following fields within objec [toc]: #table-of-contents [ts]: /general-information.md#timestamps [vehicle-states]: /general-information.md#vehicle-states -[vehicle-events]: /general-information.md#event-types +[vehicle-events]: /modes/event_types.md [vehicle-types]: #vehicle-types From c832636e19240b34ad88f1bb215eb294632511d4 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 12 Jan 2026 14:09:00 -0500 Subject: [PATCH 114/168] Align vehicle types with CDS Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- data-types.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/data-types.md b/data-types.md index 9e1010e0e..b7658710f 100644 --- a/data-types.md +++ b/data-types.md @@ -54,12 +54,15 @@ The list of allowed `vehicle_type` values in MDS. | `delivery_robot` | A robot or remote-operated device intended for transporting goods | | `moped` | A seated fully-motorized mobility device capable of travel at moderate or high speeds and suited for operation in general urban traffic | | `motorcycle` | A seated fully-motorized mobility device capable of travel at high speeds and suited for operation in general urban traffic and highways | +| `scooter` | A standing _or_ seated fully-motorized mobility device intended for one rider, capable of travel at low or moderate speeds, and suited for operation in infrastructure shared with motorized bicycles | | `scooter_standing` | A standing fully-motorized mobility device without a seat intended for one rider, capable of travel at low or moderate speeds, and suited for operation in infrastructure shared with motorized bicycles | | `scooter_seated` | A fully-motorized mobility device with a seat intended for one rider, capable of travel at low or moderate speeds, and suited for operation in infrastructure shared with motorized bicycles | | `truck` | A truck or vehicle larger than a car or similar heavy-duty vehicle | +| `van` | A van with significant interior cargo space | +| `freight` | A large delivery truck with attached cab | | `other` | A device that does not fit in the other categories | -Values based off of `form_factor` in [GBFS vehicle_types](https://github.com/MobilityData/gbfs/blob/master/gbfs.md#vehicle_typesjson), with some additional to support MDS modes. +Values based off of `form_factor` in [GBFS vehicle_types](https://github.com/MobilityData/gbfs/blob/master/gbfs.md#vehicle_typesjson) and [CDS vehicle types](https://github.com/openmobilityfoundation/curb-data-specification/blob/main/events/README.md#vehicle-type), with some modifications to support MDS modes. [Top][toc] From 5975f8faa2ea04561d825c9d945d894559720f20 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 12 Jan 2026 14:11:36 -0500 Subject: [PATCH 115/168] Removing custom PR templates for now Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- .../pull_request_template.md | 41 ------------------- 1 file changed, 41 deletions(-) delete mode 100644 .github/PULL_REQUEST_TEMPLATE/pull_request_template.md diff --git a/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md b/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md deleted file mode 100644 index 6a41ea19c..000000000 --- a/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -name: Default -about: Suggest changes to MDS -title: - ---- - -# MDS Pull Request - -Thank you for your contribution! Please review our OMF [contributing page](https://github.com/openmobilityfoundation/governance/blob/main/CONTRIBUTING.md) to understand guidelines and policies for participation, and our [Code of Conduct page](https://github.com/openmobilityfoundation/governance/blob/main/CODE_OF_CONDUCT.md). - -To avoid complications and help make the Review process as smooth as possible, make sure to: - -1. Target [**`dev`**](https://github.com/openmobilityfoundation/mobility-data-specification/tree/dev) branch. Please ensure you are targeting **`dev`**, not **`main`**. -1. Keep the *"Allow edits from maintainers"* button checked to help us resolve some issues for you. -1. Be ready to resolve any merge conflicts before we approve your Pull Request. -1. Have an up to date profile, per our Github [community profile](https://github.com/openmobilityfoundation/governance/blob/main/CONTRIBUTING.md#community-profile) guildance. - -## Explain pull request - -Please provide a clear and concise reason for this pull request and the impact of the change - -## Is this a breaking change - -A breaking change would require consumers or implementors of the API to modify their code for it to continue to function (ex: renaming of a required field or the change in data type of an existing field). A non-breaking change would allow existing code to continue to function (ex: addition of an optional field or the creation of a new optional endpoint). - -* Yes, breaking -* No, not breaking -* I'm not sure - -## Impacted Spec - -Which spec(s) will this pull request impact? - -* `agency` -* `policy` -* `provider` - -## Additional context - -Add any other context or screenshots about the feature request here. From 6437a792c23888f5ccebe533900e77585da22b5b Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 12 Jan 2026 14:11:48 -0500 Subject: [PATCH 116/168] Removing custom PR templates for now Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- .../PULL_REQUEST_TEMPLATE/release-candidate.md | 18 ------------------ 1 file changed, 18 deletions(-) delete mode 100644 .github/PULL_REQUEST_TEMPLATE/release-candidate.md diff --git a/.github/PULL_REQUEST_TEMPLATE/release-candidate.md b/.github/PULL_REQUEST_TEMPLATE/release-candidate.md deleted file mode 100644 index cc6205b32..000000000 --- a/.github/PULL_REQUEST_TEMPLATE/release-candidate.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -name: Release Candidate -about: Initiate discussion to obtain OMF approval for new release -title: Release Candidate [X.Y.Z] -labels: admin -assignees: jfh01 - ---- - -### Summary - -The Release Candidate for MDS `X.Y.Z` has been submitted: - -Please use this pull request to track Technology Council and OMF Board feedback and/or requested changes. - -### Action Item - -This pull request will be merged by an OMF maintainer after OMF Board Approval following the [Release Guidelines](https://github.com/openmobilityfoundation/governance/blob/main/technical/ReleaseGuidelines.md#making-a-release). From 47dd70d3bc95526bdfa0638ec6ae9012cf21e48e Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 12 Jan 2026 14:19:18 -0500 Subject: [PATCH 117/168] Updates to PR template for licensing Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- .github/pull_request_template.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 6a41ea19c..249210882 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,10 +1,3 @@ ---- -name: Default -about: Suggest changes to MDS -title: - ---- - # MDS Pull Request Thank you for your contribution! Please review our OMF [contributing page](https://github.com/openmobilityfoundation/governance/blob/main/CONTRIBUTING.md) to understand guidelines and policies for participation, and our [Code of Conduct page](https://github.com/openmobilityfoundation/governance/blob/main/CODE_OF_CONDUCT.md). @@ -28,14 +21,22 @@ A breaking change would require consumers or implementors of the API to modify t * No, not breaking * I'm not sure -## Impacted Spec +## Impacted APIs -Which spec(s) will this pull request impact? +Which API(s) will this pull request impact? * `agency` -* `policy` * `provider` +* `policy` +* `geography` +* `jurisdiction` +* `metrics` ## Additional context Add any other context or screenshots about the feature request here. + +## Licensing Agreement + +By submitting this pull request, you are signing the OMF's [Individual Contributor License Agreement](https://github.com/openmobilityfoundation/governance/raw/main/documents/OMF-Individual-CLA.pdf) (ICLA), and agree to the OMF's [contributing requirements](https://github.com/openmobilityfoundation/governance/blob/main/CONTRIBUTING.md), [participation policies](https://github.com/openmobilityfoundation/governance/raw/main/documents/OMFParticipationPolicies.pdf), and [code of conduct](https://github.com/openmobilityfoundation/governance/blob/main/CODE_OF_CONDUCT.md). + From 6cc4f024e3fca746f9cf082f5840e8f0ecbdf768 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 12 Jan 2026 14:53:57 -0500 Subject: [PATCH 118/168] Added publication time to Telemetry Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- data-types.md | 1 + 1 file changed, 1 insertion(+) diff --git a/data-types.md b/data-types.md index b7658710f..48720fb44 100644 --- a/data-types.md +++ b/data-types.md @@ -143,6 +143,7 @@ A standard point of vehicle telemetry. References to latitude and longitude impl | `data_provider_id`| UUID | [Optional](./general-information.md#optional-fields) | If different than `provider_id`, a UUID for the data solution provider managing the data feed in this endpoint. See MDS [provider list](/providers.csv) which includes both service operators and data solution providers. | | `telemetry_id` | UUID | Required | ID used for uniquely-identifying a Telemetry entry | | `timestamp` | [Timestamp][ts] | Required | Date/time that event occurred. Based on GPS or GNSS clock | +| `publication_time`| [Timestamp][ts] | [Optional](./general-information.md#optional-fields) | Date/time that telemetry data became available through the telemetry endpoint | | `trip_ids` | UUID[] | Required | If telemetry occurred during a trip, the ID of the trip(s). If not in a trip, `null`. | `journey_id` | UUID | Required | If telemetry occurred during a trip and journeys are used for the mode, the ID of the journey. If not in a trip, `null`. | `stop_id` | UUID | [Required if Applicable](./general-information.md#required-if-applicable-fields) | Stop that the vehicle is currently located at. See [Stops][stops] | From 324c1672e765f59c3a940116f9f2099926465894 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 12 Jan 2026 14:59:00 -0500 Subject: [PATCH 119/168] Fixed accessibility attribute delivery format Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/delivery-robots.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/modes/delivery-robots.md b/modes/delivery-robots.md index 65efbb9a0..cdfefd507 100644 --- a/modes/delivery-robots.md +++ b/modes/delivery-robots.md @@ -282,11 +282,14 @@ The `vehicle_attributes` object **may** have the following key value pairs: ### Accessibility Attributes -The `accessibility_attributes` object **may** have the following key value pairs: +The `accessibility_attributes` enum represents the accessibility attributes available on a given vehicle, or the accessibility attributes utilized for a given trip. + +| `accessibility_attributes` | | Description | +|----------------------------|---|--------------------------------------| +| `audio_cue` | [Optional](../general-information.md#optional-fields) | is the device equipped with audio cues upon delivery | +| `visual_cue` | [Optional](../general-information.md#optional-fields) | is the device equipped with visual cues upon delivery | +| `remote_open` | [Optional](../general-information.md#optional-fields) | can the device door be remotely opened to retrieve cargo upon delivery | -- `audio_cue` (boolean, [Optional](../general-information.md#optional-fields)): is the device equipped with audio cues upon delivery -- `visual_cue` (boolean, [Optional](../general-information.md#optional-fields)): is the device equipped with visual cues upon delivery -- `remote_open` (boolean, [Optional](../general-information.md#optional-fields)): can the device door be remotely opened to retrieve cargo upon delivery [Top][toc] From 880517fb026214dfb942bb1a24351cfc3b579e78 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 13 Jan 2026 11:35:39 -0500 Subject: [PATCH 120/168] Mapping trip type in Fleet Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/car-share.md | 1 + 1 file changed, 1 insertion(+) diff --git a/modes/car-share.md b/modes/car-share.md index bc57abd01..9d4472247 100644 --- a/modes/car-share.md +++ b/modes/car-share.md @@ -193,6 +193,7 @@ The `trip_type` field **must** have one of the following enumerated values: - `private` (_default_): a private trip made by one paying customer with one or more guests, or a driver using the vehicle - `reservation`: en route to pickup a customer who has made a reservation, or movement before starting an official task +- `mapping`: primarily mapping the environment - `empty`: vehicle movement with no customer or work (outside of other `trip_type` values) that may need to be reported, e.g. for maintenance, returning, etc [Top][toc] From f83c93a0f59891132c6ae9f95d48bbf96c835f81 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 13 Jan 2026 11:36:29 -0500 Subject: [PATCH 121/168] Added mapping to Passenger mode Mostly for AVs and other smart vehicles. Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/passenger-services.md | 1 + 1 file changed, 1 insertion(+) diff --git a/modes/passenger-services.md b/modes/passenger-services.md index 33e99b859..1dbbf8f4b 100644 --- a/modes/passenger-services.md +++ b/modes/passenger-services.md @@ -158,6 +158,7 @@ The `trip_type` field **must** have one of the following enumerated values: - `private` (_default_): a private trip made by one paying customer with one or more guests - `shared`: a shared or pooled trip with more than one paying customer - `reservation`: en route to pickup a customer who has made a reservation, with no passengers in the vehicle +- `mapping`: mapping the environment - `empty`: vehicle movement with no passengers (outside of other `trip_type` values) that may need to be reported, e.g. for deadheading [Top][toc] From 10f7249b7c418daf202c15ba4e6b9166e6a1f3a5 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 13 Jan 2026 14:16:43 -0500 Subject: [PATCH 122/168] Updated de/commissioned field names Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- data-types.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/data-types.md b/data-types.md index 54a1ba4b1..a294ff9fd 100644 --- a/data-types.md +++ b/data-types.md @@ -34,9 +34,8 @@ A vehicle record is as follows: | `battery_capacity` | Integer | Required if Available | Capacity of battery expressed as milliamp hours (mAh) | | `fuel_capacity` | Integer | Required if Available | Capacity of fuel tank (liquid, solid, gaseous) expressed in liters | | `maximum_speed` | Integer | Required if Available | Maximum speed (kph) possible with vehicle under normal, flat incline, smooth surface conditions. Applicable if the device has a built-in or intelligent speed limiter/governor. | -|`service_start` |Timestamp | Conditionally Required | Date/time the vehicle starts providing service. Required if asked for by public agency. | -|`service_end` |Timestamp | Required if Available | Date/time the vehicle stops providing service. Required if the vehicle is retired | - +| `commissioned` | [Timestamp][ts] | Conditionally Required | Date/time the vehicle first starts providing service in the jurisdiction. Required if asked for by public agency. | +| `decommissioned` | [Timestamp][ts] | Conditionally Required | Date/time the vehicle stops providing service in the jurisdiction and is decommissioned. Required when the vehicle is retired from operations. | [Top][toc] From fd61514c3791e633cc8a381ebb92b79880d49592 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 13 Jan 2026 20:42:08 -0500 Subject: [PATCH 123/168] Added vehicles post option in Provider Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- provider/README.md | 50 +++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 49 insertions(+), 1 deletion(-) diff --git a/provider/README.md b/provider/README.md index dea447e48..6adba70d4 100644 --- a/provider/README.md +++ b/provider/README.md @@ -20,6 +20,8 @@ This specification contains a data standard for *mobility as a service* provider * [Municipality Boundary](#municipality-boundary) * [Other Data Types](#other-data-types) * [Vehicles](#vehicles) + * [Vehicles - Get](#vehicles---get) + * [Vehicles - Post](#vehicles---post) * [Vehicle Status](#vehicle-status) * [Trips](#trips) * [Trips - Query Parameters](#trips---query-parameters) @@ -190,6 +192,8 @@ vehicle in the `/vehicles/status` response in the `/vehicles` response.) Vehicle information about all device IDs present in other MDS endpoints must be acessible via the `/vehicles/{device_id}` style call regardless of when they were deployed. +#### Vehicles - Get + **Endpoint:** `/vehicles/{device_id}` **Method:** `GET` **Schema:** See [`mds-openapi`](https://github.com/openmobilityfoundation/mds-openapi) repository for schema. @@ -216,7 +220,7 @@ If `device_id` is specified, `GET` will return an array with a single vehicle re } ``` -#### Responses +**Responses** _Possible HTTP Status Codes_: 200, @@ -230,6 +234,50 @@ See [Responses][responses], [Bulk Responses][bulk-responses], and [schema][schem [Top][toc] +#### Vehicles - Post + +The `/vehicles` POST endpoint takes a JSON body of `device_ids` UUIDs, and returns only information for those device ids. This may be useful to obtain a targetted list of vehicles deployed more than 30 days into the past, retrieving info on many vehicles that are not in the base `/vehicles` GET response. + +**POST Body** + +```json +{"device_ids": ["a", "b", "c"]} +``` + +**Endpoint**: `/vehicles` +**Method:** `POST` +**Payload:** An array of [Vehicles](/data-types.md#vehicles) + +Returned will be a list of vehicle records with pagination details per the [JSON API](https://jsonapi.org/format/#fetching-pagination) spec (recommmend 1,000 devices or less per page): + +```json +{ + "version": "x.y.z", + "vehicles": [ ... ] + "links": { + "first": "https://...", + "last": "https://...", + "prev": "https://...", + "next": "https://..." + } +} +``` + +**Responses** + +_Possible HTTP Status Codes_: +200, +201, +400, +401, +406, +409, +500 + +See [Responses][responses], [Bulk Responses][bulk-responses], and [schema][schema] for details. + +[Top][toc] + ### Vehicle Status The `/vehicles/status` endpoint is a near-realtime endpoint and returns the current status of vehicles in an agency's [Jurisdiction](/general-information.md#definitions) and/or area of agency responsibility. All vehicles that are currently in any [PROW](/general-information.md#definitions) state [`vehicle_state`][vehicle-states] should be returned in this payload. Since all states are returned, care should be taken to filter out states not in the [PROW](/general-information.md#definitions) if doing vehicle counts. For the states `elsewhere`, `removed`, and `missing`, which include vehicles not in the [PROW](/general-information.md#definitions) but provide some operational clarity for agencies, these vehicles must only persist in the feed for 90 minutes before being removed (and should persist in the feed for at least 90 minutes). From e10ebcbcb50036edf409d0e952e9f2ccde509fea Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Wed, 14 Jan 2026 08:56:17 -0500 Subject: [PATCH 124/168] Added bulk error clarity Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- general-information.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/general-information.md b/general-information.md index 20ea6782a..88b0d1211 100644 --- a/general-information.md +++ b/general-information.md @@ -241,6 +241,8 @@ For multi-record POST and PUT calls, e.g. sending Events using the Agency API, t ### Failure Details +When there is a failure, stop processing the batch request, and return an error code relevant to the first error found. + | Field | Type | Field Description | | ------------------- | -------------------- | --------------------------------------------------- | | `item` | Vehicle, Event, etc. | Invalid submitted item | From 2a89af1d442f629541b7b9f689c332b1a4c0859d Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Wed, 14 Jan 2026 09:05:06 -0500 Subject: [PATCH 125/168] Adding some clarity to Event types for all modes Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/event_types.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/modes/event_types.md b/modes/event_types.md index 54eb29df7..a1af40350 100644 --- a/modes/event_types.md +++ b/modes/event_types.md @@ -18,7 +18,7 @@ As with all MDS definitions, they should be described in a way that maximizes th | `compliance_pick_up` | Pick up for compliance (rule violation) | | `customer_cancellation` | Customer cancelled a trip | | `decommissioned` | Decommissioned | -| `driver_cancellation` | Driver cancelled a trip | +| `driver_cancellation` | Driver cancelled a trip (if known, and more specific than `trip_cancel`) | | `fueling_start` | Fueling starts | | `fueling_end` | Fueling ends | | `located` | Location found (opposite of Missing) | @@ -30,28 +30,28 @@ As with all MDS definitions, they should be described in a way that maximizes th | `on_hours` | On hours - start of service | | `order_drop_off` | Pick up of the order at business | | `order_pick_up` | Delivery of the order at the customer location | -| `passenger_cancellation` | Passenger cancelled a trip | -| `provider_cancellation` | Provider cancelled a trip | +| `passenger_cancellation` | Passenger cancelled a trip (if known, and more specific than `trip_cancel`) | +| `provider_cancellation` | Provider cancelled a trip (if known, and more specific than `trip_cancel`) | | `provider_drop_off` | Drop off by the provider | | `rebalance_pick_up` | Pick up for rebalancing | | `recommission` | Recommissioned | | `remote_start` | Remotely start the engine | | `remote_end` | Remotely stop the engine | -| `reservation_cancel` | Reservation cancelled before trip | +| `reservation_cancel` | Reservation cancelled before trip (different than `trip_cancel` since the transaction hadn't started yet, and the reservation hold is let go) | | `reservation_start` | Reservation started | | `reservation_stop` | Reservation stopped temporarily | | `service_end` | End of service | | `system_start` | Start of service | | `system_resume` | Resume system operations, e.g. start of day | | `system_suspend` | Suspend system operations, e.g. end of day | -| `trip_cancel` | Cancel trip | -| `trip_end` | End trip | +| `trip_cancel` | Cancel trip - trip is ended by anyone for some reason, either before or after motion starts (note: use more specific cancellation event types when possible) | +| `trip_end` | End trip - end of the trip and transaction | | `trip_enter_jurisdiction` | Trip enters a jurisdiction | | `trip_leave_jurisdiction` | Trip leaves a jurisdiction | -| `trip_pause` | Pause trip temporarily but do not end trip | -| `trip_resume` | Resume trip | -| `trip_start` | Start trip | -| `trip_stop` | Stop trip | +| `trip_pause` | Pause trip temporarily but do not end trip - trip intends to continue, but is paused in motion or transaction | +| `trip_resume` | Resume trip - trip resumes after a `trip_pause` (a pause is required before a resume can happen) | +| `trip_start` | Start trip - first start of a trip and transaction (required for any trip) | +| `trip_stop` | Stop trip - last movement in the trip, intending to end it (customer may be idling or interacting with devices to end trip) | | `unspecified` | Unspecified | ### Limitations on the Use of Certain Values From d52e5c2d5e26f141b3658536c7040667fd104ac9 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 15 Jan 2026 08:32:08 -0500 Subject: [PATCH 126/168] Add new car share/fleet vehicle attributes Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/car-share.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/modes/car-share.md b/modes/car-share.md index 9d4472247..fccbcd7d0 100644 --- a/modes/car-share.md +++ b/modes/car-share.md @@ -249,14 +249,21 @@ The `vehicle_attributes` object **may** have the following key value pairs: - `phone_charger` (boolean, [Optional](../general-information.md#optional-fields)) - a place to charge your phone - `sunshade` (boolean, [Optional](../general-information.md#optional-fields)) - sunshade available (i.e. for windshield) - `cargo_volume_capacity` (integer, [Optional](../general-information.md#optional-fields)) - Cargo volume available in the vehicle, expressed in liters. For cars, it corresponds to the space between the boot floor, including the storage under the hatch, to the rear shelf in the trunk. -- `cargo_load_capacity` (integer, [Optional](../general-information.md#optional-fields)) - The capacity of the vehicle cargo space (excluding passengers), expressed in kilograms. +- `cargo_load_capacity` (integer, [Optional](../general-information.md#optional-fields)) - The capacity of the vehicle cargo space (excluding passengers), expressed in kilograms - `door_count` (integer, [Optional](../general-information.md#optional-fields)) - number of doors this vehicle type has - `wheel_count` (integer, [Optional](../general-information.md#optional-fields)) - number of wheels this vehicle type has - `air_conditioning` (boolean, [Optional](../general-information.md#optional-fields)) - vehicle has air conditioning -- `gear_switch` (enum, [Optional](../general-information.md#optional-fields)) - one of `automatic`, `manual` +- `gear_switch` (enum, [Optional](../general-information.md#optional-fields)) - one of `automatic` (automatic and semi-automatic), `manual` (single or dual clutch, intelligent manual), `variable` (Continuously Variable Transmission (CVT)) - `convertible` (boolean, [Optional](../general-information.md#optional-fields)) - vehicle has a retractable roof - `cruise_control` (boolean, [Optional](../general-information.md#optional-fields)) - vehicle has a cruise control system - `navigation` (boolean, [Optional](../general-information.md#optional-fields)) - vehicle has a built-in navigation system +- `wheel_drive` (string, [Optional](../general-information.md#optional-fields)) - type of wheel drive of the vehicle (e.g., 4WD, AWD, front wheel drive, back wheel drive) +- `child_seat` (boolean, [Optional](../general-information.md#optional-fields)) - the vehicle is equipped with a children's seat +- `pets_allowed` (boolean, [Optional](../general-information.md#optional-fields)) - pets are allowed in the vehicle +- `rooftop_cargo_box` (boolean, [Optional](../general-information.md#optional-fields)) - the vehicle is equipped with a rooftop cargo box +- `roof_rails` (boolean, [Optional](../general-information.md#optional-fields)) - the vehicle is equipped with roof rails +- `ski_hatch` (boolean, [Optional](../general-information.md#optional-fields)) - the vehicle has a ski hatch in the rear seat row +- `winter_tires` (boolean, [Optional](../general-information.md#optional-fields)) - the vehicle is equipped with winter tires Note many of these attributes come from fields in [GBFS vehicle_types](https://github.com/MobilityData/gbfs/blob/v2.3/gbfs.md#vehicle_typesjson). From d3794e29324f4ae1ffea2ce1ac52ba2a2257db04 Mon Sep 17 00:00:00 2001 From: Thomas Pouillevet Date: Fri, 16 Jan 2026 18:45:40 +0100 Subject: [PATCH 127/168] Add Getaround car-share provider to providers.csv Adding Getaround to MDS provider registry with car-share mode Signed-off-by: Thomas Pouillevet --- providers.csv | 1 + 1 file changed, 1 insertion(+) diff --git a/providers.csv b/providers.csv index f2f30e786..a5275640b 100644 --- a/providers.csv +++ b/providers.csv @@ -80,3 +80,4 @@ Code3,passenger-services,b49a32d7-a418-4a6a-9f81-b5227d6c7ef8,https://code3trans Track My Shuttle,passenger-services,dd7db795-09c0-402f-9441-360235da3025,https://trackmyshuttle.com/,, Greenwheels,car-share,5f88cd9e-2c7e-477a-a531-f68143121876,https://www.greenwheels.nl,, Sixt,car-share,df72d104-372f-4d98-a4c3-9b001967990e,https://sixt.com/,https://api.orange.sixt.com/v1/share-third-party-sources/mds,https://api.orange.sixt.com/v1/share-third-party-sources/gbfs +Getaround,car-share,ede4d096-1641-4077-b986-37c602e881ae,https:getaround.com/,, From 2eb31d444ea9297d3645e76568827dd5d6834d37 Mon Sep 17 00:00:00 2001 From: Thomas Pouillevet Date: Tue, 20 Jan 2026 13:45:41 +0100 Subject: [PATCH 128/168] Add Getaround GBFS link Added a GBFS link Signed-off-by: Thomas Pouillevet --- providers.csv | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/providers.csv b/providers.csv index a5275640b..4aa3a359d 100644 --- a/providers.csv +++ b/providers.csv @@ -80,4 +80,4 @@ Code3,passenger-services,b49a32d7-a418-4a6a-9f81-b5227d6c7ef8,https://code3trans Track My Shuttle,passenger-services,dd7db795-09c0-402f-9441-360235da3025,https://trackmyshuttle.com/,, Greenwheels,car-share,5f88cd9e-2c7e-477a-a531-f68143121876,https://www.greenwheels.nl,, Sixt,car-share,df72d104-372f-4d98-a4c3-9b001967990e,https://sixt.com/,https://api.orange.sixt.com/v1/share-third-party-sources/mds,https://api.orange.sixt.com/v1/share-third-party-sources/gbfs -Getaround,car-share,ede4d096-1641-4077-b986-37c602e881ae,https:getaround.com/,, +Getaround,car-share,ede4d096-1641-4077-b986-37c602e881ae,https:getaround.com/,,https://getaround.com/gbfs/ From b53ec499aa4016a89f03d923ba683f9bda61df24 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 27 Jan 2026 14:51:51 -0500 Subject: [PATCH 129/168] for-hire AVs, robotaxis Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 48627797e..efa785eb0 100644 --- a/README.md +++ b/README.md @@ -99,7 +99,7 @@ See our [MDS Vehicles Guide](https://github.com/openmobilityfoundation/mobility- MDS supports multiple "modes", defined as a distinct regulatory framework for a type of mobility service. See the [modes overview](/modes) or get started with a specific mode: - **[Micromobility](/modes/micromobility.md)** - customer operated dockless or docked small devices moving customers and goods, such as scooters, bikeshare, cargo bikes, adaptive scooters, docked bikes, mopeds, trikes, and quadracycles. -- **[Passenger](/modes/passenger-services.md)** - employees and contractors, autonomous, and remotely operated transporting individuals or goods with a vehicle driven by another entity, including taxis, AV robotaxis, busses, transportation network companies (TNCs), commercial transport apps (CTAs), and private hire vehicles (PHVs), shuttles, paratransit, on demand vehicles, limosines, and microtransit. +- **[Passenger](/modes/passenger-services.md)** - employees and contractors, autonomous, and remotely operated transporting individuals or goods with a vehicle driven by another entity, including taxis, for-hire AVs, robotaxis, busses, transportation network companies (TNCs), commercial transport apps (CTAs), and private hire vehicles (PHVs), shuttles, paratransit, on demand vehicles, limosines, and microtransit. - **[Fleet](/modes/car-share.md)** - customer, employees and contractors, autonomous, and remotely operated shared point-to-point, station-based, or free-floating multi-passenger or cargo vehicles like consumer car share, sanitation vehicles (garbage, recycling), city fleets, vehicle rentals, street sweepers, snow plows, utility services, construction, emergency response (police, fire, ambulance), tree maintenance, inspection and permitting vehicles, mobile health clinics, and heavy maintenance vehicles. - **[Delivery](/modes/delivery-robots.md)** - employees and contractors, autonomous, and remotely operated sidewalk robots, app delivery, packages, freight, goods, food, private hire vehicles, postal service, medicine, and other delivery services. From dca2575fa2f01f8322f2908e429530a191ceaae7 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 27 Jan 2026 14:52:52 -0500 Subject: [PATCH 130/168] for-hire AVs, robotaxis Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modes/README.md b/modes/README.md index d245557a4..ff42001dc 100644 --- a/modes/README.md +++ b/modes/README.md @@ -40,7 +40,7 @@ MDS is intended to be used for multiple transportation modes, including its orig ## List of Supported Modes - **[Micromobility](/modes/micromobility.md)** (`micromobility`) - customer operated dockless or docked small devices moving customers and goods, such as scooters, bikeshare, cargo bikes, adaptive scooters, docked bikes, mopeds, trikes, and quadracycles. -- **[Passenger](/modes/passenger-services.md)** (`passenger-services`) - employees and contractors, autonomous, and remotely operated transporting individuals or goods with a vehicle driven by another entity, including taxis, AV robotaxis, busses, transportation network companies (TNCs), commercial transport apps (CTAs), and private hire vehicles (PHVs), shuttles, paratransit, on demand vehicles, limosines, and microtransit. _Note: this will use the `passenger` short name in the next breaking release._ +- **[Passenger](/modes/passenger-services.md)** (`passenger-services`) - employees and contractors, autonomous, and remotely operated transporting individuals or goods with a vehicle driven by another entity, including taxis, for-hire AVs, robotaxis, transportation network companies (TNCs), commercial transport apps (CTAs), and private hire vehicles (PHVs), shuttles, paratransit, on demand vehicles, limosines, and microtransit. _Note: this will use the `passenger` short name in the next breaking release._ - **[Fleet](/modes/car-share.md)** (`car-share`) - customer, employees and contractors, autonomous, and remotely operated shared point-to-point, station-based, or free-floating multi-passenger or cargo vehicles like consumer car share, sanitation vehicles (garbage, recycling), city fleets, vehicle rentals, street sweepers, snow plows, utility services, construction, emergency response (police, fire, ambulance), tree maintenance, inspection and permitting vehicles, mobile health clinics, and heavy maintenance vehicles. _Note: this will use the `fleet` short name in the next breaking release._ - **[Delivery](/modes/delivery-robots.md)** (`delivery-robots`) - employees and contractors, autonomous, and remotely operated sidewalk robots, app delivery, packages, freight, goods, food, private hire vehicles, postal service, medicine, and other delivery services. _Note: this will use the `delivery` short name in the next breaking release._ From 59aa80770310bd9c1af46d1d9f95889db85fed33 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 27 Jan 2026 14:53:23 -0500 Subject: [PATCH 131/168] for-hire AVs, robotaxis Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/passenger-services.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modes/passenger-services.md b/modes/passenger-services.md index 33e99b859..09c1e255f 100644 --- a/modes/passenger-services.md +++ b/modes/passenger-services.md @@ -2,7 +2,7 @@ MDS Modes - Passenger -**Passenger** refers to employees and contractors, autonomous, and remotely operated transporting individuals or goods with a vehicle driven by another entity, including taxis, AV robotaxis, busses, transportation network companies (TNCs), commercial transport apps (CTAs), and private hire vehicles (PHVs), shuttles, paratransit, on demand vehicles, limousines, and microtransit. +**Passenger** refers to employees and contractors, autonomous, and remotely operated transporting individuals or goods with a vehicle driven by another entity, including taxis, for-hire AVs, robotaxis, busses, transportation network companies (TNCs), commercial transport apps (CTAs), and private hire vehicles (PHVs), shuttles, paratransit, on demand vehicles, limousines, and microtransit. See the [modes overview](/modes) for how the mode specific information below applies across MDS. From 68cfd465556515433af4773fca6492a0a280cf89 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 30 Jan 2026 15:24:46 -0500 Subject: [PATCH 132/168] Added more parking_category types Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- data-types.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/data-types.md b/data-types.md index 27565094b..3166a7d99 100644 --- a/data-types.md +++ b/data-types.md @@ -255,7 +255,7 @@ A Trip is defined by the following structure: | `publication_time` | [Timestamp][ts] | [Optional](./general-information.md#optional-fields) | Date/time that trip became available through the trips endpoint | | `accessibility_attributes` | Enum[] | Required if Available | **[Mode](/modes#list-of-supported-modes) Specific**. [Accessibility attributes](/modes#accessibility-attributes) given as an array of enumerated values. List of any accessibility attributes **used during the trip**. | | `parking_verification_url` | URL | [Optional](./general-information.md#optional-fields) | A URL to a photo (or other evidence) of proper vehicle parking at the end of a trip, provided by customer or operator. | -| `parking_category` | Enum | [Optional](./general-information.md#optional-fields) | The type of parking location detected or provided and the end of a trip. One of `corral`, `curb`, `rack`, `other_valid`, `invalid`. Note that `other_valid` covers any other allowed parking location beyond what is enumerated, and `invalid` is any improper parking based on agency parking rules. +| `parking_category` | Enum | [Optional](./general-information.md#optional-fields) | The type of parking location detected or provided and the end of a trip. One of `corral`, `curb`, `rack`, `space`, `dock`, `other_valid`, `invalid`. Note that `other_valid` covers any other allowed parking location beyond what is enumerated, and `invalid` is any improper parking based on agency parking rules. Use `external_references` to specify more details, like a link to CDS Curb Zones. | | `standard_cost` | Integer | [Optional](./general-information.md#optional-fields) | The cost, in the currency defined in `currency`, to perform that trip in the standard operation of the System (see [Costs & Currencies][costs-and-currencies]) | | `actual_cost` | Integer | [Optional](./general-information.md#optional-fields) | The actual cost, in the currency defined in `currency`, paid by the customer of the *mobility as a service* provider (see [Costs & Currencies][costs-and-currencies]) | | `currency` | String | [Optional](./general-information.md#optional-fields), USD cents is implied if null.| An [ISO 4217 Alphabetic Currency Code][iso4217] representing the currency of the payee (see [Costs & Currencies][costs-and-currencies]) | From 53bbf6f376172664f9edf005198a995d0e819e00 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 30 Jan 2026 15:28:48 -0500 Subject: [PATCH 133/168] Add passenger_pickup and passenger_drop_off boolean to Trip Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/passenger-services.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/modes/passenger-services.md b/modes/passenger-services.md index 1dbbf8f4b..67b64ae33 100644 --- a/modes/passenger-services.md +++ b/modes/passenger-services.md @@ -178,6 +178,8 @@ The `trip_attributes` object **may** have the following key value pairs: - `trip_fare_time` (milliseconds, [Optional](../general-information.md#optional-fields)): part of the passenger trip where the vehicle was moving more quickly (e.g. >12mph), which is a different fare rate in some jurisdictions - `pickup_address` (text, [Optional](../general-information.md#optional-fields)): street address where the trip originated from - `dropoff_address` (text, [Optional](../general-information.md#optional-fields)): street address where the trip ended +- `passenger_pickup` (boolean, [Optional](../general-information.md#optional-fields)): One or more passengers were picked up at the start of this trip. If you need to record other pickups, do so in a different Trip. +- `passenger_drop_off` (boolean, [Optional](../general-information.md#optional-fields)): One or more passengers were sropped off at the end of this trip. If you need to record other drop offs, do so in a different Trip. - `permit_license_number` (string, [Optional](../general-information.md#optional-fields)) - The permit license number of the organization that dispatched the vehicle - `driver_id` (string, [Optional](../general-information.md#optional-fields)): Universal identifier of a specific driver, static across operators, like a driver's license number. Could also be used as a lookup in an agency's internal driver system. - `wheelchair_transported` (boolean, [Optional](../general-information.md#optional-fields)) - was a wheelchair transported as part of this trip? From 0ad26d45d32785a4673614c06164c5d7179d6d13 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 30 Jan 2026 15:36:29 -0500 Subject: [PATCH 134/168] Added customer and vehicle wait time notes Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/vehicle_states.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modes/vehicle_states.md b/modes/vehicle_states.md index 0969852c8..9251b39d8 100644 --- a/modes/vehicle_states.md +++ b/modes/vehicle_states.md @@ -7,9 +7,9 @@ This file defines all possible `vehicle_state`s that can be used in state machin | `removed` | no | Examples include: at the Provider's warehouse, in a Provider's truck, or destroyed and in a landfill. | | `available` | yes | Available for rental via the Provider's app. | | `non_operational` | yes | Not available for hire. Examples include: vehicle has low battery, or currently outside legal operating hours. | -| `reserved` | yes | Reserved via Provider's app. A scooter waiting to be picked up by a rider, a taxi en route to a pickup. | +| `reserved` | yes | Reserved via Provider's app. A scooter waiting to be picked up by a rider, a taxi en route to a pickup. Time between `reserved` and `stopped` at pickup location is the customer's wait time for vehicle arrival. | | `on_trip` | yes | In a trip. For micromobility, in possession of renter. May or may not be in motion. | -| `stopped` | yes | In a trip, but stopped temporarily for some purpose, e.g. to pick up or drop off passengers or packages, or if a driver is on break. | +| `stopped` | yes | In a trip, but stopped temporarily for some purpose, e.g. to pick up or drop off passengers or packages, or if a driver is on break. Time between `stopped` and returning to `on_trip` is the vehicle wait time for customer. | | `non_contactable` | yes | Provider has temporarily lost contact with the vehicle and its disposition is unknown. Examples include: connectivity loss, GPS issues. | | `missing` | no | Provider has lost contact with the vehicle and its disposition is unknown with no immediate resolution. Examples include: scooter taken into a private residence, bike thrown in river. | | `elsewhere` | no | Outside of regulator's jurisdiction, and thus not subject to cap-counts or other regulations. Example: a vehicle that started a trip in L.A. has transitioned to Santa Monica. | From ed6c7dbef0ea3bfeb5022506ab73da75ec6c4d6c Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 30 Jan 2026 15:43:27 -0500 Subject: [PATCH 135/168] Clarified reservation_stop event for wait time calculation Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/event_types.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modes/event_types.md b/modes/event_types.md index a1af40350..c006b8042 100644 --- a/modes/event_types.md +++ b/modes/event_types.md @@ -39,7 +39,7 @@ As with all MDS definitions, they should be described in a way that maximizes th | `remote_end` | Remotely stop the engine | | `reservation_cancel` | Reservation cancelled before trip (different than `trip_cancel` since the transaction hadn't started yet, and the reservation hold is let go) | | `reservation_start` | Reservation started | -| `reservation_stop` | Reservation stopped temporarily | +| `reservation_stop` | Reservation stopped temporarily. If at the end of a trip, the time between `reserved` and `stopped` States is the customer wait time. | | `service_end` | End of service | | `system_start` | Start of service | | `system_resume` | Resume system operations, e.g. start of day | From ca0fe183b9694061aca8a6183f43cf366d931cbc Mon Sep 17 00:00:00 2001 From: Thomas Pouillevet Date: Fri, 6 Feb 2026 17:25:43 +0100 Subject: [PATCH 136/168] Update Getaround URL in providers.csv Updated Getaround URL to point to the new GBFS manifest. Signed-off-by: Thomas Pouillevet --- providers.csv | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/providers.csv b/providers.csv index 4aa3a359d..7eaf56aa4 100644 --- a/providers.csv +++ b/providers.csv @@ -80,4 +80,4 @@ Code3,passenger-services,b49a32d7-a418-4a6a-9f81-b5227d6c7ef8,https://code3trans Track My Shuttle,passenger-services,dd7db795-09c0-402f-9441-360235da3025,https://trackmyshuttle.com/,, Greenwheels,car-share,5f88cd9e-2c7e-477a-a531-f68143121876,https://www.greenwheels.nl,, Sixt,car-share,df72d104-372f-4d98-a4c3-9b001967990e,https://sixt.com/,https://api.orange.sixt.com/v1/share-third-party-sources/mds,https://api.orange.sixt.com/v1/share-third-party-sources/gbfs -Getaround,car-share,ede4d096-1641-4077-b986-37c602e881ae,https:getaround.com/,,https://getaround.com/gbfs/ +Getaround,car-share,ede4d096-1641-4077-b986-37c602e881ae,https:getaround.com/,,https://api-eu.getaround.com/gbfs/manifest?country_code=FR From e30c5601115df75bd1be6298cb0ed24e7a0223ae Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 6 Feb 2026 11:46:34 -0500 Subject: [PATCH 137/168] Updated micro vehicle states events Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/micromobility.md | 159 ++++++++++++++++++++++++++++------------- 1 file changed, 110 insertions(+), 49 deletions(-) diff --git a/modes/micromobility.md b/modes/micromobility.md index a9df92b30..2cd6a5174 100644 --- a/modes/micromobility.md +++ b/modes/micromobility.md @@ -25,7 +25,7 @@ See the [modes overview](/modes) for how the mode specific information below app - [State Machine](#state-machine) - [Vehicle States](#vehicle-states) - [Event Types](#event-types) - - [Vehicle State Events](#vehicle-states-events) + - [Vehicle States Events](#vehicle-states-events) - [State Machine Diagram](#state-machine-diagram) ## Mode Attributes @@ -161,7 +161,7 @@ See vehicle [Event Types][vehicle-events] for descriptions. [Top][toc] -### Vehicle State Events +### Vehicle States Events This is the list of `vehicle_state` and `event_type` pairings that constitute the valid transitions of the vehicle state machine. @@ -172,54 +172,115 @@ Note that to handle out-of-order events, the validity of the prior-state shall n Vehicles can enter the `non_contactable` state to and from any other state with the following event types: any state can go to `non_contactable` with event type `comms_lost` or `unspecified`, and `non_contactable` can go to any state with event type `comms_restored` of `unspecified`. Vehicles can exit the `missing` state to any other state with the following event types: `missing` can go to any state with event type `located` or `unspecified`. -| **From** `vehicle_state` | **To** `vehicle_state` | `event_type` | Description | -|-------------------------------------------------------------------------------|--------------------|---------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `available` | `non_operational` | `battery_low` | The vehicle's battery is below some rentability threshold | -| `available` | `non_operational` | `maintenance` | The vehicle requires some non-charge-related maintenance | -| `available` | `non_operational` | `off_hours` | The vehicle has exited operating hours (per the regulator or per the Provider) | -| `available` | `reserved` | `reservation_start` | The vehicle was reserved for use by a customer | -| `available` | `non_operational` | `system_suspend` | The vehicle is not available because of e.g. weather or temporary regulations | -| `available`, `elsewhere`, `non_operational`, `on_trip`, `removed`, `reserved` | `non_contactable` | `comms_lost` | The vehicle is unable to transmit its GPS location or other status information | -| `available`, `elsewhere`, `non_operational`, `on_trip`, `removed`, `reserved` | `non_contactable` | `unspecified` | The provider cannot definitively (yet) specify the reason for the non_contactable state | -| `available`, `non_contactable`, `missing` | `non_operational` | `unspecified` | The vehicle became unavailable, but the Provider cannot definitively (yet) specify the reason. | -| `available`, `non_operational`, `elsewhere` | `removed` | `compliance_pick_up` | The provider picked up the vehicle because it was placed in a non-compliant location | -| `available`, `non_operational`, `elsewhere` | `removed` | `maintenance_pick_up` | The provider picked up the vehicle to service it | -| `available`, `non_operational`, `elsewhere` | `removed` | `rebalance_pick_up` | The provider picked up the vehicle for rebalancing purposes | -| `available`, `non_operational`, `elsewhere`, `non_contactable`, `missing` | `removed` | `agency_pick_up` | An agency picked up the vehicle for some reason, e.g. illegal placement | -| `available`, `non_operational`, `elsewhere`, `non_contactable`, `missing` | `removed` | `decommissioned` | The provider has removed the vehicle from its fleet | -| `available`, `reserved` | `on_trip` | `trip_start` | A customer initiated a trip with this vehicle | -| `elsewhere` | `on_trip` | `trip_enter_jurisdiction` | A vehicle on a trip entered the jurisdiction | -| `missing` | `available` | `located` | The vehicle has been located by the provider | -| `missing` | `elsewhere` | `located` | The vehicle has been located by the provider | -| `missing` | `non_operational` | `located` | The vehicle has been located by the provider | -| `missing` | `on_trip` | `located` | The vehicle has been located by the provider | -| `missing` | `removed` | `located` | The vehicle has been located by the provider | -| `missing` | `reserved` | `located` | The vehicle has been located by the provider | -| `non_contactable` | `available` | `comms_restored` | The vehicle transmitted status information after a period of being out of communication. | -| `non_contactable` | `elsewhere` | `comms_restored` | The vehicle transmitted status information after a period of being out of communication. | -| `non_contactable` | `non_operational` | `comms_restored` | The vehicle transmitted status information after a period of being out of communication | -| `non_contactable` | `on_trip` | `comms_restored` | The vehicle transmitted status information after a period of being out of communication. | -| `non_contactable` | `removed` | `comms_restored` | The vehicle transmitted status information after a period of being in an non_contactable state | -| `non_contactable` | `reserved` | `comms_restored` | The vehicle transmitted status information after a period of being out of communication. | -| `non_contactable` | `missing` | `not_located` | The vehicle is not at its last reported GPS location, or that location is wildly in error | -| `non_contactable` | `missing` | `unspecified` | The provider cannot definitively (yet) specify the reason for the missing state | -| `non_contactable`, `missing` | `elsewhere` | `unspecified` | The provider cannot definitively state how a vehicle went `elsewhere`. | -| `non_contactable`, `missing` | `on_trip` | `unspecified` | The provider cannot definitively state how a vehicle started a trip. | -| `non_contactable`, `missing` | `reserved` | `unspecified` | The provider cannot definitively state how a vehicle became reserved. | -| `non_contactable`, `missing`, `non_operational`, `available`, `elsewhere` | `removed` | `unspecified` | The vehicle was removed, but the provider cannot definitively (yet) specify the reason | -| `non_operational` | `available` | `battery_charged` | The vehicle became available because its battery is now charged. | -| `non_operational` | `available` | `maintenance` | The vehicle was previously in need of maintenance | -| `non_operational` | `available` | `on_hours` | The vehicle has entered operating hours (per the regulator or per the provider) | -| `non_operational` | `available` | `system_resume` | The vehicle is available because e.g. weather suspension or temporary regulations ended | -| `non_operational`, `non_contactable`, `missing` | `available` | `unspecified` | The vehicle became available, but the provider cannot definitively (yet) specify the reason. Generally, regulator Service-Level Agreements will limit the amount of time a vehicle's last event type may be `unspecified`. | -| `on_trip` | `on_trip ` | `changed_geographies` | The vehicle has entered or left one or more Geographies managed by a Policy. See [Geography Driven Events](#geography-driven-events). | -| `on_trip` | `available` | `trip_cancel` | A trip was initiated, then canceled prior to moving any distance | -| `on_trip` | `available` | `trip_end` | A trip has ended, and the vehicle is again available for rent | -| `on_trip` | `elsewhere` | `trip_leave_jurisdiction` | A vehicle on a trip left the jurisdiction | -| `removed`, `non_contactable`, `missing` | `available` | `agency_drop_off` | The vehicle was placed in the PROW by a city or county | -| `removed`, `non_contactable`, `missing` | `available` | `provider_drop_off` | The vehicle was placed in the PROW by the provider | -| `reserved` | `available` | `reservation_cancel` | A reservation was canceled and the vehicle returned to service | +| From `vehicle_state` | To `vehicle_state` | `event_type` | Description | +|----------------------|--------------------|-----------------------|-----------------------------------------------------------------------------------------------| +| `available` | `non_contactable` | `comms_lost` | The vehicle is unable to transmit its GPS location or other status information | +| `available` | `non_contactable` | `unspecified` | The provider cannot definitively (yet) specify the reason for the non_contactable state | +| `available` | `non_operational` | `battery_low` | The vehicle's battery is below some rentability threshold | +| `available` | `non_operational` | `maintenance` | The vehicle requires some non-charge-related maintenance | +| `available` | `non_operational` | `off_hours` | The vehicle has exited operating hours (per the regulator or per the Provider) | +| `available` | `non_operational` | `system_suspend` | The vehicle is not available because of e.g. weather or temporary regulations | +| `available` | `non_operational` | `unspecified` | The vehicle became unavailable, but the Provider cannot definitively (yet) specify the reason | +| `available` | `on_trip` | `trip_start` | A customer initiated a trip with this vehicle | +| `available` | `removed` | `agency_pick_up` | An agency picked up the vehicle for some reason, e.g. illegal placement | +| `available` | `removed` | `compliance_pick_up` | The provider picked up the vehicle because it was placed in a non-compliant location | +| `available` | `removed` | `decommissioned` | The provider has removed the vehicle from its fleet | +| `available` | `removed` | `maintenance_pick_up` | The provider picked up the vehicle to service it | +| `available` | `removed` | `rebalance_pick_up` | The provider picked up the vehicle for rebalancing purposes | +| `available` | `removed` | `unspecified` | The vehicle was removed, but the provider cannot definitively (yet) specify the reason | +| `available` | `reserved` | `reservation_start` | The vehicle was reserved for use by a customer | + +| From `vehicle_state` | To `vehicle_state` | `event_type` | Description | +|----------------------|--------------------|---------------------------|-----------------------------------------------------------------------------------------| +| `elsewhere` | `non_contactable` | `comms_lost` | The vehicle is unable to transmit its GPS location or other status information | +| `elsewhere` | `non_contactable` | `unspecified` | The provider cannot definitively (yet) specify the reason for the non_contactable state | +| `elsewhere` | `on_trip` | `trip_enter_jurisdiction` | A vehicle on a trip entered the jurisdiction | +| `elsewhere` | `removed` | `agency_pick_up` | An agency picked up the vehicle for some reason, e.g. illegal placement | +| `elsewhere` | `removed` | `compliance_pick_up` | The provider picked up the vehicle because it was placed in a non-compliant location | +| `elsewhere` | `removed` | `decommissioned` | The provider has removed the vehicle from its fleet | +| `elsewhere` | `removed` | `maintenance_pick_up` | The provider picked up the vehicle to service it | +| `elsewhere` | `removed` | `rebalance_pick_up` | The provider picked up the vehicle for rebalancing purposes | +| `elsewhere` | `removed` | `unspecified` | The vehicle was removed, but the provider cannot definitively (yet) specify the reason | + +| From `vehicle_state` | To `vehicle_state` | `event_type` | Description | +|----------------------|--------------------|---------------------|-----------------------------------------------------------------------------------------------| +| `missing` | `available` | `agency_drop_off` | The vehicle was placed in the PROW by a city or county | +| `missing` | `available` | `located` | The vehicle has been located by the provider | +| `missing` | `available` | `provider_drop_off` | The vehicle was placed in the PROW by the provider | +| `missing` | `available` | `unspecified` | The vehicle became available, but the provider cannot definitively (yet) specify the reason. Generally, regulator Service-Level Agreements will limit the amount of time a vehicle's last event type may be `unspecified`. | +| `missing` | `elsewhere` | `located` | The vehicle has been located by the provider | +| `missing` | `elsewhere` | `unspecified` | The provider cannot definitively state how a vehicle went elsewhere | +| `missing` | `non_operational` | `located` | The vehicle has been located by the provider | +| `missing` | `non_operational` | `unspecified` | The vehicle became unavailable, but the Provider cannot definitively (yet) specify the reason | +| `missing` | `on_trip` | `located` | The vehicle has been located by the provider | +| `missing` | `on_trip` | `unspecified` | The provider cannot definitively state how a vehicle started a trip | +| `missing` | `removed` | `agency_pick_up` | An agency picked up the vehicle for some reason, e.g. illegal placement | +| `missing` | `removed` | `decommissioned` | The provider has removed the vehicle from its fleet | +| `missing` | `removed` | `located` | The vehicle has been located by the provider | +| `missing` | `removed` | `unspecified` | The vehicle was removed, but the provider cannot definitively (yet) specify the reason | +| `missing` | `reserved` | `located` | The vehicle has been located by the provider | +| `missing` | `reserved` | `unspecified` | The provider cannot definitively state how a vehicle became reserved | + +| From `vehicle_state` | To `vehicle_state` | `event_type` | Description | +|----------------------|--------------------|---------------------|-----------------------------------------------------------------------------------------------| +| `non_contactable` | `available` | `agency_drop_off` | The vehicle was placed in the PROW by a city or county | +| `non_contactable` | `available` | `comms_restored` | The vehicle transmitted status information after a period of being out of communication | +| `non_contactable` | `available` | `provider_drop_off` | The vehicle was placed in the PROW by the provider | +| `non_contactable` | `available` | `unspecified` | The vehicle became available, but the provider cannot definitively (yet) specify the reason. Generally, regulator Service-Level Agreements will limit the amount of time a vehicle's last event type may be `unspecified`. | +| `non_contactable` | `elsewhere` | `comms_restored` | The vehicle transmitted status information after a period of being out of communication | +| `non_contactable` | `elsewhere` | `unspecified` | The provider cannot definitively state how a vehicle went `elsewhere` | +| `non_contactable` | `missing` | `not_located` | The vehicle is not at its last reported GPS location, or that location is wildly in error | +| `non_contactable` | `missing` | `unspecified` | The provider cannot definitively (yet) specify the reason for the missing state | +| `non_contactable` | `non_operational` | `comms_restored` | The vehicle transmitted status information after a period of being out of communication | +| `non_contactable` | `non_operational` | `unspecified` | The vehicle became unavailable, but the Provider cannot definitively (yet) specify the reason | +| `non_contactable` | `on_trip` | `comms_restored` | The vehicle transmitted status information after a period of being out of communication | +| `non_contactable` | `on_trip` | `unspecified` | The provider cannot definitively state how a vehicle started a trip | +| `non_contactable` | `removed` | `agency_pick_up` | An agency picked up the vehicle for some reason, e.g. illegal placement | +| `non_contactable` | `removed` | `comms_restored` | The vehicle transmitted status information after a period of being out of communication | +| `non_contactable` | `removed` | `decommissioned` | The provider has removed the vehicle from its fleet | +| `non_contactable` | `removed` | `unspecified` | The vehicle was removed, but the provider cannot definitively (yet) specify the reason | +| `non_contactable` | `reserved` | `comms_restored` | The vehicle transmitted status information after a period of being out of communication | +| `non_contactable` | `reserved` | `unspecified` | The provider cannot definitively state how a vehicle became reserved | + +| From `vehicle_state` | To `vehicle_state` | `event_type` | Description | +|----------------------|--------------------|-----------------------|----------------------------------------------------------------------------------------------| +| `non_operational` | `available` | `battery_charged` | The vehicle became available because its battery is now charged | +| `non_operational` | `available` | `maintenance` | The vehicle was previously in need of maintenance | +| `non_operational` | `available` | `on_hours` | The vehicle has entered operating hours (per the regulator or per the provider) | +| `non_operational` | `available` | `system_resume` | The vehicle is available because e.g. weather suspension or temporary regulations ended | +| `non_operational` | `available` | `unspecified` | The vehicle became available, but the provider cannot definitively (yet) specify the reason. Generally, regulator Service-Level Agreements will limit the amount of time a vehicle's last event type may be `unspecified`. | +| `non_operational` | `non_contactable` | `comms_lost` | The vehicle is unable to transmit its GPS location or other status information | +| `non_operational` | `non_contactable` | `unspecified` | The provider cannot definitively (yet) specify the reason for the non_contactable state | +| `non_operational` | `removed` | `agency_pick_up` | An agency picked up the vehicle for some reason, e.g. illegal placement | +| `non_operational` | `removed` | `compliance_pick_up` | The provider picked up the vehicle because it was placed in a non-compliant location | +| `non_operational` | `removed` | `decommissioned` | The provider has removed the vehicle from its fleet | +| `non_operational` | `removed` | `maintenance_pick_up` | The provider picked up the vehicle to service it | +| `non_operational` | `removed` | `rebalance_pick_up` | The provider picked up the vehicle for rebalancing purposes | +| `non_operational` | `removed` | `unspecified` | The vehicle was removed, but the provider cannot definitively (yet) specify the reason | + +| From `vehicle_state` | To `vehicle_state` | `event_type` | Description | +|----------------------|--------------------|---------------------------|-----------------------------------------------------------------------------------------| +| `on_trip` | `available` | `trip_cancel` | A trip was initiated, then canceled prior to moving any distance | +| `on_trip` | `available` | `trip_end` | A trip has ended, and the vehicle is again available for rent | +| `on_trip` | `elsewhere` | `trip_leave_jurisdiction` | A vehicle on a trip left the jurisdiction | +| `on_trip` | `non_contactable` | `comms_lost` | The vehicle is unable to transmit its GPS location or other status information | +| `on_trip` | `non_contactable` | `unspecified` | The provider cannot definitively (yet) specify the reason for the non_contactable state | +| `on_trip` | `on_trip ` | `changed_geographies` | The vehicle has entered or left one or more Geographies managed by a Policy. See [Geography Driven Events](#geography-driven-events). | + +| From `vehicle_state` | To `vehicle_state` | `event_type` | Description | +|----------------------|--------------------|---------------------|-----------------------------------------------------------------------------------------| +| `removed` | `available` | `agency_drop_off` | The vehicle was placed in the PROW by a city or county | +| `removed` | `available` | `provider_drop_off` | The vehicle was placed in the PROW by the provider | +| `removed` | `non_contactable` | `comms_lost` | The vehicle is unable to transmit its GPS location or other status information | +| `removed` | `non_contactable` | `unspecified` | The provider cannot definitively (yet) specify the reason for the non_contactable state | + +| From `vehicle_state` | To `vehicle_state` | `event_type` | Description | +|----------------------|--------------------|----------------------|-----------------------------------------------------------------------------------------| +| `reserved` | `available` | `reservation_cancel` | A reservation was canceled and the vehicle returned to service | +| `reserved` | `non_contactable` | `comms_lost` | The vehicle is unable to transmit its GPS location or other status information | +| `reserved` | `non_contactable` | `unspecified` | The provider cannot definitively (yet) specify the reason for the non_contactable state | +| `reserved` | `on_trip` | `trip_start` | A customer initiated a trip with this vehicle | [Top][toc] From e3f5dca5d560b40093d3ab1debe9d5751ed505ed Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 6 Feb 2026 13:55:54 -0500 Subject: [PATCH 138/168] Refresh to state diagrams Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/car-share-state-machine-diagram.svg | 2 +- modes/delivery-robots-state-machine-diagram.svg | 2 +- modes/micromobility-state-machine-diagram.svg | 2 +- modes/passenger-services-state-machine-diagram.svg | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/modes/car-share-state-machine-diagram.svg b/modes/car-share-state-machine-diagram.svg index 365977f55..ba4770280 100644 --- a/modes/car-share-state-machine-diagram.svg +++ b/modes/car-share-state-machine-diagram.svg @@ -1 +1 @@ - \ No newline at end of file + \ No newline at end of file diff --git a/modes/delivery-robots-state-machine-diagram.svg b/modes/delivery-robots-state-machine-diagram.svg index 9e2dfa7c6..ab3bc5515 100644 --- a/modes/delivery-robots-state-machine-diagram.svg +++ b/modes/delivery-robots-state-machine-diagram.svg @@ -1 +1 @@ - \ No newline at end of file + \ No newline at end of file diff --git a/modes/micromobility-state-machine-diagram.svg b/modes/micromobility-state-machine-diagram.svg index e870daab0..3d7efa5c5 100644 --- a/modes/micromobility-state-machine-diagram.svg +++ b/modes/micromobility-state-machine-diagram.svg @@ -1 +1 @@ - \ No newline at end of file + \ No newline at end of file diff --git a/modes/passenger-services-state-machine-diagram.svg b/modes/passenger-services-state-machine-diagram.svg index b5c27f1e7..082826f86 100644 --- a/modes/passenger-services-state-machine-diagram.svg +++ b/modes/passenger-services-state-machine-diagram.svg @@ -1 +1 @@ - \ No newline at end of file + \ No newline at end of file From aaef73a243defba675ca218dbd3d942ea9fd0a60 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 6 Feb 2026 14:17:11 -0500 Subject: [PATCH 139/168] Event clarifications Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/event_types.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/modes/event_types.md b/modes/event_types.md index c006b8042..5046d9e6a 100644 --- a/modes/event_types.md +++ b/modes/event_types.md @@ -62,6 +62,16 @@ MDS is intended to communicate the provider's best available information to regu The `unspecified` event type state transition means that the vehicle has moved from one state to another for an unspecified or unknown reason. It is used when there are multiple possible event types between states, but the reason for the transition is not clear. It is expected that `unspecified` will not be used frequently, and only for short periods of time. Cities may put in place specific limitations via an SLA. When more accurate information becomes available to the provider, it should be updated in the MDS data by sending a new event type state transition with the current timestamp. +Generally, regulator Service-Level Agreements will limit the amount of time a vehicle's last event type may be `unspecified`. + +#### Multi State Transitions + +See the mode specific state-transition tables which descibe how the `vehicle_state` changes in response to each `event_type`. Most events will have a single `event_type`. However, if a single event has more than one ordered `event_type` entry, the intermediate `vehicle_state` value(s) are discarded. For example, if an event contains `[trip_end, battery_low]` then the vehicle transitions from `on_trip` through `available` to `non_operational` per the state machine, but the vehicle is never "in" the `available` state. + +#### Out of Order Events + +Note that to handle out-of-order events, the validity of the prior-state shall not be enforced at the time of ingest via Provider or Agency. Events received out-of-order may result in transient incorrect vehicle states. + --- [Modes Overview][modes] From 43daca6ef8673c79fde8b0e2f4b440a1ac56776c Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 6 Feb 2026 14:18:16 -0500 Subject: [PATCH 140/168] State clarifications Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/vehicle_states.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/modes/vehicle_states.md b/modes/vehicle_states.md index 9251b39d8..1385c6fc5 100644 --- a/modes/vehicle_states.md +++ b/modes/vehicle_states.md @@ -22,6 +22,14 @@ MDS is intended to communicate the provider's best available information to regu It is expected that `non-contactable` will be used only for short periods of time and cities may put in place specific limitations via an SLA. As vehicles regain connectivity they should return to their prior state, and then send additional events to reflect any subsequent changes to that state. If vehicles remain `non-contactable` for over a specific limit as stated in the City SLA, then vehicles should be moved to `missing`. +#### Multi State Transitions + +See the mode specific state-transition tables which descibe how the `vehicle_state` changes in response to each `event_type`. Most events will have a single `event_type`. However, if a single event has more than one ordered `event_type` entry, the intermediate `vehicle_state` value(s) are discarded. For example, if an event contains `[trip_end, battery_low]` then the vehicle transitions from `on_trip` through `available` to `non_operational` per the state machine, but the vehicle is never "in" the `available` state. + +#### Out of Order Events + +Note that to handle out-of-order events, the validity of the prior-state shall not be enforced at the time of ingest via Provider or Agency. Events received out-of-order may result in transient incorrect vehicle states. + --- [Modes Overview][modes] From c31e9393b1d378aaaf68d35ffa93a1ab94579380 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 6 Feb 2026 14:19:26 -0500 Subject: [PATCH 141/168] Removed redundant state event text Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/micromobility.md | 8 -------- 1 file changed, 8 deletions(-) diff --git a/modes/micromobility.md b/modes/micromobility.md index 2cd6a5174..bc871077c 100644 --- a/modes/micromobility.md +++ b/modes/micromobility.md @@ -165,14 +165,6 @@ See vehicle [Event Types][vehicle-events] for descriptions. This is the list of `vehicle_state` and `event_type` pairings that constitute the valid transitions of the vehicle state machine. -The state-transition table below describes how the `vehicle_state` changes in response to each `event_type`. Most events will have a single `event_type`. However, if a single event has more than one ordered `event_type` entry, the intermediate `vehicle_state` value(s) are discarded. For example, if an event contains [`trip_end`, `battery_low`] then the vehicle transitions from `on_trip` through `available` to `non_operational` per the state machine, but the vehicle is never "in" the `available` state. - -Note that to handle out-of-order events, the validity of the prior-state shall not be enforced at the time of ingest via Provider or Agency. Events received out-of-order may result in transient incorrect vehicle states. - -Vehicles can enter the `non_contactable` state to and from any other state with the following event types: any state can go to `non_contactable` with event type `comms_lost` or `unspecified`, and `non_contactable` can go to any state with event type `comms_restored` of `unspecified`. - -Vehicles can exit the `missing` state to any other state with the following event types: `missing` can go to any state with event type `located` or `unspecified`. - | From `vehicle_state` | To `vehicle_state` | `event_type` | Description | |----------------------|--------------------|-----------------------|-----------------------------------------------------------------------------------------------| | `available` | `non_contactable` | `comms_lost` | The vehicle is unable to transmit its GPS location or other status information | From dc5cca68cdc88ca57a7b51638b4a6639ea70d140 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 6 Feb 2026 14:19:54 -0500 Subject: [PATCH 142/168] Split fleet state tables Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/car-share.md | 119 ++++++++++++++++++++++++++------------------- 1 file changed, 70 insertions(+), 49 deletions(-) diff --git a/modes/car-share.md b/modes/car-share.md index fccbcd7d0..c27f5f27f 100644 --- a/modes/car-share.md +++ b/modes/car-share.md @@ -335,55 +335,76 @@ See vehicle [Event Types][vehicle-events] for descriptions. This is the list of `vehicle_state` and `event_type` pairings that constitute the valid transitions of the vehicle state machine. -| **From** `vehicle_state` | **To** `vehicle_state` | `trip_state` | `event_type` | Description | -| ------------------------ | ---------------------- | ------------ | ------------------------ | --------------------------------------------------------------------------------------------------------------- | -| `available` | `elsewhere` | N/A | `trip_leave_jurisdiction` | The vehicle has left jurisdictional boundaries while available for-hire | -| `available` | `non_contactable` | N/A | `comms_lost` | The vehicle has went out of comms while available for-use | -| `available` | `non_operational` | N/A | `service_end` | The vehicle has went out of service (is unavailable for-hire) | -| `available` | `reserved` | `reserved` | `reservation_start` | The vehicle was reserved by a passenger | -| `elsewhere` | `available` | N/A | `trip_enter_jurisdiction` | The vehicle has entered jurisdictional boundaries while available for-hire | -| `elsewhere` | `non_contactable` | N/A | `comms_lost` | The vehicle has went out of comms while outside of jurisdictional boundaries | -| `elsewhere` | `non_operational` | N/A | `trip_enter_jurisdiction` | The vehicle has entered jurisdictional boundaries while not operating commercially | -| `elsewhere` | `on_trip` | `on_trip` | `trip_enter_jurisdiction` | The vehicle has entered jurisdictional boundaries while on a trip | -| `elsewhere` | `reserved` | N/A | `trip_enter_jurisdiction` | The vehicle has entered jurisdictional boundaries while reserved by a customer | -| `non_contactable` | `available` | N/A | `comms_restored` | The vehicle has come back into comms while available for-hire | -| `non_contactable` | `elsewhere` | N/A | `comms_restored` | The vehicle has come back into comms while outside of jurisdictional boundaries | -| `non_contactable` | `non_operational` | N/A | `comms_restored` | The vehicle has come back into comms while not operating commercially | -| `non_contactable` | `on_trip` | `on_trip` | `comms_restored` | The vehicle has come back into comms while on a trip | -| `non_contactable` | `removed` | N/A | `comms_restored` | The vehicle has come back into comms while removed | -| `non_contactable` | `reserved` | `reserved` | `comms_restored` | The vehicle has come back into comms while reserved by a passenger | -| `non_contactable` | `stopped` | `stopped` | `comms_restored` | The vehicle has come back into comms while stopped | -| `non_operational` | `available` | N/A | `service_start` | The vehicle has went into service (is available for-hire) | -| `non_operational` | `elsewhere` | N/A | `trip_leave_jurisdiction` | The vehicle has left jurisdictional boundaries while not operating commercially | -| `non_operational` | `non_contactable` | N/A | `comms_lost` | The vehicle has went out of comms while not operating commercially | -| `non_operational` | `removed` | N/A | `decommissioned` | The vehicle has been removed from the Provider's fleet | -| `non_operational` | `removed` | N/A | `maintenance_pick_up` | The vehicle has entered the depot for maintenance | -| `non_operational` | `removed` | N/A | `maintenance` | The vehicle is undergoing maintenance on site | -| `on_trip` | `elsewhere` | N/A | `trip_leave_jurisdiction` | The vehicle has left jurisdictional boundaries while on a trip | -| `on_trip` | `non_contactable` | N/A | `comms_lost` | The vehicle has gone out of comms while on a trip | -| `on_trip` | `stopped` | `stopped` | `trip_stop` | The vehicle has stopped while on a trip | -| `removed` | `non_contactable` | N/A | `comms_lost` | The vehicle has gone out of comms while removed | -| `removed` | `non_operational` | N/A | `maintenance_end` | The vehicle maintenance work has ended | -| `removed` | `non_operational` | N/A | `recommissioned` | The vehicle has been re-added to the Provider's fleet after being previously `decommissioned` | -| `reserved` | `available` | N/A | `driver_cancellation` | The driver has canceled the reservation | -| `reserved` | `available` | N/A | `customer_cancellation` | The customer has canceled the reservation | -| `reserved` | `available` | N/A | `provider_cancellation` | The provider has canceled the reservation | -| `reserved` | `elsewhere` | N/A | `trip_leave_jurisdiction` | The vehicle has left the jurisdiction while in a reservation | -| `reserved` | `non_contactable` | N/A | `comms_lost` | The vehicle went out of comms while being reserved by a passenger | -| `reserved` | `stopped` | `stopped` | `reservation_stop` | The customer has activated the vehicle | -| `stopped` | `available` | N/A | `driver_cancellation` | The driver has canceled the trip | -| `stopped` | `available` | N/A | `customer_cancellation` | The customer has canceled the trip | -| `stopped` | `available` | N/A | `provider_cancellation` | The provider has canceled the trip | -| `stopped` | `available` | N/A | `trip_end` | The trip has been successfully completed | -| `stopped` | `non_contactable` | N/A | `comms_lost` | The vehicle has went out of comms while stopped | -| `stopped` | `on_trip` | `on_trip` | `trip_resume` | Resume a trip that was previously stopped (e.g. picking up a friend to go to the airport with) | -| `stopped` | `on_trip` | `on_trip` | `trip_start` | Start a trip | -| `stopped` | `stopped` | `stopped` | `charging_end` | End charging the device battery | -| `stopped` | `stopped` | `stopped` | `charging_start` | Start charging the device battery | -| `stopped` | `stopped` | `stopped` | `fueling_end` | End fueling the device with physical fuel | -| `stopped` | `stopped` | `stopped` | `fueling_start` | Start fueling the device with physical fuel | -| `stopped` | `stopped` | `stopped` | `remote_end` | Remotely stop the engine while vehicle is already stopped | -| `stopped` | `stopped` | `stopped` | `remote_start` | Remotely start the engine while vehicle is stopped, usually to charge battery or warm up | +| From `vehicle_state` | To `vehicle_state` | `event_type` | Description | +|----------------------|--------------------|---------------------------|------------------------------------------------------------------------------------------------| +| `available` | `elsewhere` | `trip_leave_jurisdiction` | The vehicle has left jurisdictional boundaries while available for-hire | +| `available` | `non_contactable` | `comms_lost` | The vehicle has went out of comms while available for-use | +| `available` | `non_operational` | `service_end` | The vehicle has went out of service (is unavailable for-hire) | +| `available` | `reserved` | `reservation_start` | The vehicle was reserved by a passenger | + +| From `vehicle_state` | To `vehicle_state` | `event_type` | Description | +|----------------------|--------------------|---------------------------|------------------------------------------------------------------------------------------------| +| `elsewhere` | `available` | `trip_enter_jurisdiction` | The vehicle has entered jurisdictional boundaries while available for-hire | +| `elsewhere` | `non_contactable` | `comms_lost` | The vehicle has went out of comms while outside of jurisdictional boundaries | +| `elsewhere` | `non_operational` | `trip_enter_jurisdiction` | The vehicle has entered jurisdictional boundaries while not operating commercially | +| `elsewhere` | `on_trip` | `trip_enter_jurisdiction` | The vehicle has entered jurisdictional boundaries while on a trip | +| `elsewhere` | `reserved` | `trip_enter_jurisdiction` | The vehicle has entered jurisdictional boundaries while reserved by a customer | + +| From `vehicle_state` | To `vehicle_state` | `event_type` | Description | +|----------------------|--------------------|---------------------------|------------------------------------------------------------------------------------------------| +| `non_contactable` | `available` | `comms_restored` | The vehicle has come back into comms while available for-hire | +| `non_contactable` | `elsewhere` | `comms_restored` | The vehicle has come back into comms while outside of jurisdictional boundaries | +| `non_contactable` | `non_operational` | `comms_restored` | The vehicle has come back into comms while not operating commercially | +| `non_contactable` | `on_trip` | `comms_restored` | The vehicle has come back into comms while on a trip | +| `non_contactable` | `removed` | `comms_restored` | The vehicle has come back into comms while removed | +| `non_contactable` | `reserved` | `comms_restored` | The vehicle has come back into comms while reserved by a passenger | +| `non_contactable` | `stopped` | `comms_restored` | The vehicle has come back into comms while stopped | + +| From `vehicle_state` | To `vehicle_state` | `event_type` | Description | +|----------------------|--------------------|---------------------------|------------------------------------------------------------------------------------------------| +| `non_operational` | `available` | `service_start` | The vehicle has went into service (is available for-hire) | +| `non_operational` | `elsewhere` | `trip_leave_jurisdiction` | The vehicle has left jurisdictional boundaries while not operating commercially | +| `non_operational` | `non_contactable` | `comms_lost` | The vehicle has went out of comms while not operating commercially | +| `non_operational` | `removed` | `decommissioned` | The vehicle has been removed from the Provider's fleet | +| `non_operational` | `removed` | `maintenance_pick_up` | The vehicle has entered the depot for maintenance | +| `non_operational` | `removed` | `maintenance` | The vehicle is undergoing maintenance on site | + +| From `vehicle_state` | To `vehicle_state` | `event_type` | Description | +|----------------------|--------------------|---------------------------|------------------------------------------------------------------------------------------------| +| `on_trip` | `elsewhere` | `trip_leave_jurisdiction` | The vehicle has left jurisdictional boundaries while on a trip | +| `on_trip` | `non_contactable` | `comms_lost` | The vehicle has gone out of comms while on a trip | +| `on_trip` | `stopped` | `trip_stop` | The vehicle has stopped while on a trip | + +| From `vehicle_state` | To `vehicle_state` | `event_type` | Description | +|----------------------|--------------------|---------------------------|------------------------------------------------------------------------------------------------| +| `removed` | `non_contactable` | `comms_lost` | The vehicle has gone out of comms while removed | +| `removed` | `non_operational` | `maintenance_end` | The vehicle maintenance work has ended | +| `removed` | `non_operational` | `recommissioned` | The vehicle has been re-added to the Provider's fleet after being previously `decommissioned` | + +| From `vehicle_state` | To `vehicle_state` | `event_type` | Description | +|----------------------|--------------------|---------------------------|------------------------------------------------------------------------------------------------| +| `reserved` | `available` | `driver_cancellation` | The driver has canceled the reservation | +| `reserved` | `available` | `customer_cancellation` | The customer has canceled the reservation | +| `reserved` | `available` | `provider_cancellation` | The provider has canceled the reservation | +| `reserved` | `elsewhere` | `trip_leave_jurisdiction` | The vehicle has left the jurisdiction while in a reservation | +| `reserved` | `non_contactable` | `comms_lost` | The vehicle went out of comms while being reserved by a passenger | +| `reserved` | `stopped` | `reservation_stop` | The customer has activated the vehicle | + +| From `vehicle_state` | To `vehicle_state` | `event_type` | Description | +|----------------------|--------------------|---------------------------|------------------------------------------------------------------------------------------------| +| `stopped` | `available` | `driver_cancellation` | The driver has canceled the trip | +| `stopped` | `available` | `customer_cancellation` | The customer has canceled the trip | +| `stopped` | `available` | `provider_cancellation` | The provider has canceled the trip | +| `stopped` | `available` | `trip_end` | The trip has been successfully completed | +| `stopped` | `non_contactable` | `comms_lost` | The vehicle has went out of comms while stopped | +| `stopped` | `on_trip` | `trip_resume` | Resume a trip that was previously stopped (e.g. picking up a friend to go to the airport with) | +| `stopped` | `on_trip` | `trip_start` | Start a trip | +| `stopped` | `stopped` | `charging_end` | End charging the device battery | +| `stopped` | `stopped` | `charging_start` | Start charging the device battery | +| `stopped` | `stopped` | `fueling_end` | End fueling the device with physical fuel | +| `stopped` | `stopped` | `fueling_start` | Start fueling the device with physical fuel | +| `stopped` | `stopped` | `remote_end` | Remotely stop the engine while vehicle is already stopped | +| `stopped` | `stopped` | `remote_start` | Remotely start the engine while vehicle is stopped, usually to charge battery or warm up | [Top][toc] From f334fe72196be046380392f221218b79402c5f06 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 6 Feb 2026 14:20:28 -0500 Subject: [PATCH 143/168] Fleet TOC update Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/car-share.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modes/car-share.md b/modes/car-share.md index c27f5f27f..d7250abe4 100644 --- a/modes/car-share.md +++ b/modes/car-share.md @@ -25,7 +25,7 @@ _Note: Formerly called "Car Share". Any references in the specification code or - [State Machine](#state-machine) - [Vehicle States](#vehicle-states) - [Event Types](#event-types) - - [Vehicle State Events](#vehicle-states-events) + - [Vehicle States Events](#vehicle-states-events) - [State Machine Diagram](#state-machine-diagram) ## Mode Attributes From 085aaa877d6aaa897229cdbd18fa67372df4b604 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 6 Feb 2026 14:23:05 -0500 Subject: [PATCH 144/168] Delivery states table split Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/delivery-robots.md | 136 +++++++++++++++++++++++---------------- 1 file changed, 80 insertions(+), 56 deletions(-) diff --git a/modes/delivery-robots.md b/modes/delivery-robots.md index cdfefd507..b3caf1333 100644 --- a/modes/delivery-robots.md +++ b/modes/delivery-robots.md @@ -27,7 +27,7 @@ _Note: Formerly called "Delivery Robots". Any references in the specification co - [State Machine](#state-machine) - [Vehicle States](#vehicle-states) - [Event Types](#event-types) - - [Vehicle State Events](#vehicle-states-events) + - [Vehicle States Events](#vehicle-states-events) - [State Machine Diagram](#state-machine-diagram) ## Mode Attributes @@ -351,66 +351,90 @@ See vehicle [Event Types][vehicle-events] for descriptions. This is the list of `vehicle_state` and `event_type` pairings that constitute the valid transitions of the vehicle state machine. -| **From** `vehicle_state` | **To** `vehicle_state` | `trip_state` | `event_type` | Description | -| ------------------------ | ---------------------- | ------------ | ----------------------- | --------------------------------------------------------------------------------------------- | -| `available` | `elsewhere` | N/A | `trip_leave_jurisdiction` | The vehicle has left jurisdictional boundaries while available for-hire | -| `available` | `non_contactable` | N/A | `comms_lost` | The vehicle has gone out of comms while available for-use | -| `available` | `non_operational` | N/A | `service_end` | The vehicle has gone out of service (is unavailable for-hire) | -| `available` | `reserved` | `reserved` | `reservation_start` | The vehicle was reserved by a customer | -| `elsewhere` | `available` | N/A | `trip_enter_jurisdiction` | The vehicle has entered jurisdictional boundaries while available for-hire | -| `elsewhere` | `non_contactable` | N/A | `comms_lost` | The vehicle has gone out of comms while outside of jurisdictional boundaries | -| `elsewhere` | `non_operational` | N/A | `trip_enter_jurisdiction` | The vehicle has entered jurisdictional boundaries while not operating commercially | -| `elsewhere` | `on_trip` | `on_trip` | `trip_enter_jurisdiction` | The vehicle has entered jurisdictional boundaries while on a trip | -| `elsewhere` | `reserved` | N/A | `trip_enter_jurisdiction` | The vehicle has entered jurisdictional boundaries while reserved by a customer | -| `missing` | `available` | N/A | `located` | The vehicle has been located while available for-hire | -| `missing` | `elsewhere` | N/A | `located` | The vehicle has been located while outside of jurisdictional boundaries | -| `missing` | `non_operational` | N/A | `located` | The vehicle has been located while not operating commercially | -| `missing` | `on_trip` | `on_trip` | `located` | The vehicle has been located while on a trip | -| `missing` | `removed` | N/A | `located` | The vehicle has been located while removed | -| `missing` | `reserved` | `reserved` | `located` | The vehicle has been located while reserved by a customer | -| `missing` | `stopped` | `stopped` | `located` | The vehicle has been located while stopped | -| `non_contactable` | `available` | N/A | `comms_restored` | The vehicle has come back into comms while available for-hire | -| `non_contactable` | `elsewhere` | N/A | `comms_restored` | The vehicle has come back into comms while outside of jurisdictional boundaries | -| `non_contactable` | `missing` | N/A | `not_located` | The vehicle has gone missing after a period of lost comms | -| `non_contactable` | `non_operational` | N/A | `comms_restored` | The vehicle has come back into comms while not operating commercially | -| `non_contactable` | `on_trip` | `on_trip` | `comms_restored` | The vehicle has come back into comms while on a trip | -| `non_contactable` | `removed` | N/A | `comms_restored` | The vehicle has come back into comms while removed | -| `non_contactable` | `reserved` | `reserved` | `comms_restored` | The vehicle has come back into comms while reserved by a customer | -| `non_contactable` | `stopped` | `stopped` | `comms_restored` | The vehicle has come back into comms while stopped | -| `non_operational` | `available` | N/A | `service_start` | The vehicle has gone into service (is available for-hire) | -| `non_operational` | `elsewhere` | N/A | `trip_leave_jurisdiction` | The vehicle has left jurisdictional boundaries while not operating commercially | -| `non_operational` | `non_contactable` | N/A | `comms_lost` | The vehicle has gone out of comms while not operating commercially | -| `non_operational` | `non_operational` | N/A | `maintenance` | The vehicle has maintenance performed on site | -| `non_operational` | `non_operational` | N/A | `maintenance_end` | Maintenance is complete | -| `non_operational` | `removed` | N/A | `maintenance_pick_up` | The vehicle has entered the depot for maintenance | -| `non_operational` | `removed` | N/A | `decommissioned` | The vehicle has been removed from the Provider's fleet | -| `on_trip` | `elsewhere` | N/A | `trip_leave_jurisdiction` | The vehicle has left jurisdictional boundaries while on a trip | -| `on_trip` | `non_contactable` | N/A | `comms_lost` | The vehicle has gone out of comms while on a trip to pick up the order | -| `on_trip` | `stopped` | N/A | `order_drop_off` | The vehicle is at the customer's place and is waiting for them | -| `on_trip` | `stopped` | `stopped` | `order_pick_up` | The vehicle has come to pick up the order at the restaurant | -| `on_trip` | `stopped` | `stopped` | `trip_pause` | The vehicle has paused while on a trip | -| `removed` | `non_contactable` | N/A | `comms_lost` | The vehicle has gone out of comms while removed | -| `removed` | `non_operational` | N/A | `maintenance_end` | The vehicle has left the depot | -| `removed` | `non_operational` | N/A | `recommissioned` | The vehicle has been re-added to the Provider's fleet after being previously `decommissioned` | -| `reserved` | `available` | N/A | `customer_cancellation` | The customer has canceled the reservation | -| `reserved` | `available` | N/A | `driver_cancellation` | The driver has canceled the reservation | -| `reserved` | `available` | N/A | `provider_cancellation` | The provider has canceled the reservation | -| `reserved` | `elsewhere` | N/A | `trip_leave_jurisdiction` | The vehicle has left the jurisdiction while in a reservation | -| `reserved` | `non_contactable` | N/A | `comms_lost` | The vehicle has gone out of comms while being reserved by a customer | -| `reserved` | `stopped` | `stopped` | `reservation_stop` | The vehicle has stopped to pickup reservation | -| `stopped` | `available` | N/A | `customer_cancellation` | The customer has canceled the trip while the vehicle is waiting | -| `stopped` | `available` | N/A | `driver_cancellation` | The driver has canceled the trip while waiting | -| `stopped` | `available` | N/A | `provider_cancellation` | The provider has canceled the trip while the vehicle is waiting | -| `stopped` | `available` | N/A | `trip_end` | The trip has been successfully completed | -| `stopped` | `non_contactable` | N/A | `comms_lost` | The vehicle has gone out of comms while stopped | -| `stopped` | `on_trip` | `on_trip` | `trip_resume` | Resume a trip that was previously paused (e.g. picking up an order) | -| `stopped` | `on_trip` | `on_trip` | `trip_start` | Start a trip | +| From `vehicle_state` | To `vehicle_state` | `event_type` | Description | +|----------------------|--------------------|---------------------------|-----------------------------------------------------------------------------------------------| +| `available` | `elsewhere` | `trip_leave_jurisdiction` | The vehicle has left jurisdictional boundaries while available for-hire | +| `available` | `non_contactable` | `comms_lost` | The vehicle has gone out of comms while available for-use | +| `available` | `non_operational` | `service_end` | The vehicle has gone out of service (is unavailable for-hire) | +| `available` | `reserved` | `reservation_start` | The vehicle was reserved by a customer | + +| From `vehicle_state` | To `vehicle_state` | `event_type` | Description | +|----------------------|--------------------|---------------------------|-----------------------------------------------------------------------------------------------| +| `elsewhere` | `available` | `trip_enter_jurisdiction` | The vehicle has entered jurisdictional boundaries while available for-hire | +| `elsewhere` | `non_contactable` | `comms_lost` | The vehicle has gone out of comms while outside of jurisdictional boundaries | +| `elsewhere` | `non_operational` | `trip_enter_jurisdiction` | The vehicle has entered jurisdictional boundaries while not operating commercially | +| `elsewhere` | `on_trip` | `trip_enter_jurisdiction` | The vehicle has entered jurisdictional boundaries while on a trip | +| `elsewhere` | `reserved` | `trip_enter_jurisdiction` | The vehicle has entered jurisdictional boundaries while reserved by a customer | + +| From `vehicle_state` | To `vehicle_state` | `event_type` | Description | +|----------------------|--------------------|---------------------------|-----------------------------------------------------------------------------------------------| +| `missing` | `available` | `located` | The vehicle has been located while available for-hire | +| `missing` | `elsewhere` | `located` | The vehicle has been located while outside of jurisdictional boundaries | +| `missing` | `non_operational` | `located` | The vehicle has been located while not operating commercially | +| `missing` | `on_trip` | `located` | The vehicle has been located while on a trip | +| `missing` | `removed` | `located` | The vehicle has been located while removed | +| `missing` | `reserved` | `located` | The vehicle has been located while reserved by a customer | +| `missing` | `stopped` | `located` | The vehicle has been located while stopped | + +| From `vehicle_state` | To `vehicle_state` | `event_type` | Description | +|----------------------|--------------------|---------------------------|-----------------------------------------------------------------------------------------------| +| `non_contactable` | `available` | `comms_restored` | The vehicle has come back into comms while available for-hire | +| `non_contactable` | `elsewhere` | `comms_restored` | The vehicle has come back into comms while outside of jurisdictional boundaries | +| `non_contactable` | `missing` | `not_located` | The vehicle has gone missing after a period of lost comms | +| `non_contactable` | `non_operational` | `comms_restored` | The vehicle has come back into comms while not operating commercially | +| `non_contactable` | `on_trip` | `comms_restored` | The vehicle has come back into comms while on a trip | +| `non_contactable` | `removed` | `comms_restored` | The vehicle has come back into comms while removed | +| `non_contactable` | `reserved` | `comms_restored` | The vehicle has come back into comms while reserved by a customer | +| `non_contactable` | `stopped` | `comms_restored` | The vehicle has come back into comms while stopped | + +| From `vehicle_state` | To `vehicle_state` | `event_type` | Description | +|----------------------|--------------------|---------------------------|-----------------------------------------------------------------------------------------------| +| `non_operational` | `available` | `service_start` | The vehicle has gone into service (is available for-hire) | +| `non_operational` | `elsewhere` | `trip_leave_jurisdiction` | The vehicle has left jurisdictional boundaries while not operating commercially | +| `non_operational` | `non_contactable` | `comms_lost` | The vehicle has gone out of comms while not operating commercially | +| `non_operational` | `non_operational` | `maintenance` | The vehicle has maintenance performed on site | +| `non_operational` | `non_operational` | `maintenance_end` | Maintenance is complete | +| `non_operational` | `removed` | `maintenance_pick_up` | The vehicle has entered the depot for maintenance | +| `non_operational` | `removed` | `decommissioned` | The vehicle has been removed from the Provider's fleet | + +| From `vehicle_state` | To `vehicle_state` | `event_type` | Description | +|----------------------|--------------------|---------------------------|-----------------------------------------------------------------------------------------------| +| `on_trip` | `elsewhere` | `trip_leave_jurisdiction` | The vehicle has left jurisdictional boundaries while on a trip | +| `on_trip` | `non_contactable` | `comms_lost` | The vehicle has gone out of comms while on a trip to pick up the order | +| `on_trip` | `stopped` | `order_drop_off` | The vehicle is at the customer's place and is waiting for them | +| `on_trip` | `stopped` | `order_pick_up` | The vehicle has come to pick up the order at the restaurant | +| `on_trip` | `stopped` | `trip_pause` | The vehicle has paused while on a trip | + +| From `vehicle_state` | To `vehicle_state` | `event_type` | Description | +|----------------------|--------------------|---------------------------|-----------------------------------------------------------------------------------------------| +| `removed` | `non_contactable` | `comms_lost` | The vehicle has gone out of comms while removed | +| `removed` | `non_operational` | `maintenance_end` | The vehicle has left the depot | +| `removed` | `non_operational` | `recommissioned` | The vehicle has been re-added to the Provider's fleet after being previously `decommissioned` | + +| From `vehicle_state` | To `vehicle_state` | `event_type` | Description | +|----------------------|--------------------|---------------------------|-----------------------------------------------------------------------------------------------| +| `reserved` | `available` | `customer_cancellation` | The customer has canceled the reservation | +| `reserved` | `available` | `driver_cancellation` | The driver has canceled the reservation | +| `reserved` | `available` | `provider_cancellation` | The provider has canceled the reservation | +| `reserved` | `elsewhere` | `trip_leave_jurisdiction` | The vehicle has left the jurisdiction while in a reservation | +| `reserved` | `non_contactable` | `comms_lost` | The vehicle has gone out of comms while being reserved by a customer | +| `reserved` | `stopped` | `reservation_stop` | The vehicle has stopped to pickup reservation | + +| From `vehicle_state` | To `vehicle_state` | `event_type` | Description | +|----------------------|--------------------|---------------------------|-----------------------------------------------------------------------------------------------| +| `stopped` | `available` | `customer_cancellation` | The customer has canceled the trip while the vehicle is waiting | +| `stopped` | `available` | `driver_cancellation` | The driver has canceled the trip while waiting | +| `stopped` | `available` | `provider_cancellation` | The provider has canceled the trip while the vehicle is waiting | +| `stopped` | `available` | `trip_end` | The trip has been successfully completed | +| `stopped` | `non_contactable` | `comms_lost` | The vehicle has gone out of comms while stopped | +| `stopped` | `on_trip` | `trip_resume` | Resume a trip that was previously paused (e.g. picking up an order) | +| `stopped` | `on_trip` | `trip_start` | Start a trip | [Top][toc] ### State Machine Diagram -This *State Machine Diagram* shows how `vehicle_state` and `event_type` relate to each other and how vehicles can transition between states. See [Google Slides](https://docs.google.com/presentation/d/1fHdq1efbN5GSFDLF4en-oA_BYPXQKbbIbHff6iROJKA/edit#slide=id.g207ec9d0152_0_0) for the source file. +This *State Machine Diagram* shows how `vehicle_state` and `event_type` relate to each other and how vehicles can transition between states. See [Google Slides](https://docs.google.com/presentation/d/1FCrBCtNQyoIcchaGx6zw4BpLCquQaWmBHsEU6fUdUoo/edit?slide=id.g207ec9d0152_0_0#slide=id.g207ec9d0152_0_0) for the source file. ![Delivery State Machine Diagram](delivery-robots-state-machine-diagram.svg) From 9169201fb5c33aaf1ea51324c8d5534bea1553e5 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 6 Feb 2026 14:26:56 -0500 Subject: [PATCH 145/168] Passenger states table split Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/passenger-services.md | 113 +++++++++++++++++++++--------------- 1 file changed, 67 insertions(+), 46 deletions(-) diff --git a/modes/passenger-services.md b/modes/passenger-services.md index 67b64ae33..1c2bc9c35 100644 --- a/modes/passenger-services.md +++ b/modes/passenger-services.md @@ -29,7 +29,7 @@ Taxis and similar traditionally regulated services typically require explicit tr - [State Machine](#state-machine) - [Vehicle States](#vehicle-states) - [Event Types](#event-types) - - [Vehicle State Events](#vehicle-states-events) + - [Vehicle States Events](#vehicle-states-events) - [State Machine Diagram](#state-machine-diagram) ## Mode Attributes @@ -289,56 +289,77 @@ See vehicle [Event Types][vehicle-events] for descriptions. This is the list of `vehicle_state` and `event_type` pairings that constitute the valid transitions of the vehicle state machine. -| **From** `vehicle_state` | **To** `vehicle_state` | `trip_state` | `event_type` | Description | -| ------------------------ | ---------------------- | ------------ | ------------------------ | --------------------------------------------------------------------------------------------------------------- | -| `available` | `elsewhere` | N/A | `trip_leave_jurisdiction` | The vehicle has left jurisdictional boundaries while available for-hire | -| `available` | `non_contactable` | N/A | `comms_lost` | The vehicle has went out of comms while available for-use | -| `available` | `non_operational` | N/A | `service_end` | The vehicle has went out of service (is unavailable for-hire) | -| `available` | `reserved` | `reserved` | `reservation_start` | The vehicle was reserved by a passenger | -| `elsewhere` | `available` | N/A | `trip_enter_jurisdiction` | The vehicle has entered jurisdictional boundaries while available for-hire | -| `elsewhere` | `non_contactable` | N/A | `comms_lost` | The vehicle has went out of comms while outside of jurisdictional boundaries | -| `elsewhere` | `non_operational` | N/A | `trip_enter_jurisdiction` | The vehicle has entered jurisdictional boundaries while not operating commercially | -| `elsewhere` | `on_trip` | `on_trip` | `trip_enter_jurisdiction` | The vehicle has entered jurisdictional boundaries while on a trip | -| `elsewhere` | `reserved` | N/A | `trip_enter_jurisdiction` | The vehicle has entered jurisdictional boundaries while reserved by a customer | -| `non_contactable` | `available` | N/A | `comms_restored` | The vehicle has come back into comms while available for-hire | -| `non_contactable` | `elsewhere` | N/A | `comms_restored` | The vehicle has come back into comms while outside of jurisdictional boundaries | -| `non_contactable` | `non_operational` | N/A | `comms_restored` | The vehicle has come back into comms while not operating commercially | -| `non_contactable` | `on_trip` | `on_trip` | `comms_restored` | The vehicle has come back into comms while on a trip | -| `non_contactable` | `removed` | N/A | `comms_restored` | The vehicle has come back into comms while removed | -| `non_contactable` | `reserved` | `reserved` | `comms_restored` | The vehicle has come back into comms while reserved by a passenger | -| `non_contactable` | `stopped` | `stopped` | `comms_restored` | The vehicle has come back into comms while stopped | -| `non_operational` | `available` | N/A | `service_start` | The vehicle has went into service (is available for-hire) | -| `non_operational` | `elsewhere` | N/A | `trip_leave_jurisdiction` | The vehicle has left jurisdictional boundaries while not operating commercially | -| `non_operational` | `non_contactable` | N/A | `comms_lost` | The vehicle has went out of comms while not operating commercially | -| `non_operational` | `non_operational` | N/A | `maintenance` | The vehicle has maintenance performed on site | -| `non_operational` | `non_operational` | N/A | `maintenance_end` | Maintenance is complete | -| `non_operational` | `removed` | N/A | `maintenance_pick_up` | The vehicle has entered the depot for maintenance | -| `non_operational` | `removed` | N/A | `decommissioned` | The vehicle has been removed from the Provider's fleet | -| `on_trip` | `elsewhere` | N/A | `trip_leave_jurisdiction` | The vehicle has left jurisdictional boundaries while on a trip | -| `on_trip` | `non_contactable` | N/A | `comms_lost` | The vehicle has gone out of comms while on a trip | -| `on_trip` | `stopped` | `stopped` | `trip_stop` | The vehicle has stopped while on a trip | -| `removed` | `non_contactable` | N/A | `comms_lost` | The vehicle has gone out of comms while removed | -| `removed` | `non_operational` | N/A | `maintenance_end` | The vehicle has left the depot | -| `removed` | `non_operational` | N/A | `recommissioned` | The vehicle has been re-added to the Provider's fleet after being previously `decommissioned` | -| `reserved` | `available` | N/A | `driver_cancellation` | The driver has canceled the reservation | -| `reserved` | `available` | N/A | `passenger_cancellation` | The passenger has canceled the reservation | -| `reserved` | `available` | N/A | `provider_cancellation` | The provider has canceled the reservation | -| `reserved` | `elsewhere` | N/A | `trip_leave_jurisdiction` | The vehicle has left the jurisdiction while in a reservation | -| `reserved` | `non_contactable` | N/A | `comms_lost` | The vehicle went out of comms while being reserved by a passenger | -| `reserved` | `stopped` | `stopped` | `reservation_stop` | The vehicle has stopped to pick up the passenger | -| `stopped` | `available` | N/A | `driver_cancellation` | The driver has canceled the trip while either waiting for the passenger, or dropping them off | -| `stopped` | `available` | N/A | `passenger_cancellation` | The passenger has canceled the trip while the vehicle is waiting to pick them up, or they are being dropped off | -| `stopped` | `available` | N/A | `provider_cancellation` | The provider has canceled the trip while the vehicle is waiting for a passenger, or dropping them off | -| `stopped` | `available` | N/A | `trip_end` | The trip has been successfully completed | -| `stopped` | `non_contactable` | N/A | `comms_lost` | The vehicle has went out of comms while stopped | -| `stopped` | `on_trip` | `on_trip` | `trip_resume` | Resume a trip that was previously stopped (e.g. picking up a friend to go to the airport with) | -| `stopped` | `on_trip` | `on_trip` | `trip_start` | Start a trip | +| From `vehicle_state` | To `vehicle_state` | `event_type` | Description | +|----------------------|--------------------|---------------------------|-----------------------------------------------------------------------------------------------------------------| +| `available` | `elsewhere` | `trip_leave_jurisdiction` | The vehicle has left jurisdictional boundaries while available for-hire | +| `available` | `non_contactable` | `comms_lost` | The vehicle has went out of comms while available for-use | +| `available` | `non_operational` | `service_end` | The vehicle has went out of service (is unavailable for-hire) | +| `available` | `reserved` | `reservation_start` | The vehicle was reserved by a passenger | + +| From `vehicle_state` | To `vehicle_state` | `event_type` | Description | +|----------------------|--------------------|---------------------------|-----------------------------------------------------------------------------------------------------------------| +| `elsewhere` | `available` | `trip_enter_jurisdiction` | The vehicle has entered jurisdictional boundaries while available for-hire | +| `elsewhere` | `non_contactable` | `comms_lost` | The vehicle has went out of comms while outside of jurisdictional boundaries | +| `elsewhere` | `non_operational` | `trip_enter_jurisdiction` | The vehicle has entered jurisdictional boundaries while not operating commercially | +| `elsewhere` | `on_trip` | `trip_enter_jurisdiction` | The vehicle has entered jurisdictional boundaries while on a trip | +| `elsewhere` | `reserved` | `trip_enter_jurisdiction` | The vehicle has entered jurisdictional boundaries while reserved by a customer | + +| From `vehicle_state` | To `vehicle_state` | `event_type` | Description | +|----------------------|--------------------|---------------------------|-----------------------------------------------------------------------------------------------------------------| +| `non_contactable` | `available` | `comms_restored` | The vehicle has come back into comms while available for-hire | +| `non_contactable` | `elsewhere` | `comms_restored` | The vehicle has come back into comms while outside of jurisdictional boundaries | +| `non_contactable` | `non_operational` | `comms_restored` | The vehicle has come back into comms while not operating commercially | +| `non_contactable` | `on_trip` | `comms_restored` | The vehicle has come back into comms while on a trip | +| `non_contactable` | `removed` | `comms_restored` | The vehicle has come back into comms while removed | +| `non_contactable` | `reserved` | `comms_restored` | The vehicle has come back into comms while reserved by a passenger | +| `non_contactable` | `stopped` | `comms_restored` | The vehicle has come back into comms while stopped | + +| From `vehicle_state` | To `vehicle_state` | `event_type` | Description | +|----------------------|--------------------|---------------------------|-----------------------------------------------------------------------------------------------------------------| +| `non_operational` | `available` | `service_start` | The vehicle has went into service (is available for-hire) | +| `non_operational` | `elsewhere` | `trip_leave_jurisdiction` | The vehicle has left jurisdictional boundaries while not operating commercially | +| `non_operational` | `non_contactable` | `comms_lost` | The vehicle has went out of comms while not operating commercially | +| `non_operational` | `non_operational` | `maintenance` | The vehicle has maintenance performed on site | +| `non_operational` | `non_operational` | `maintenance_end` | Maintenance is complete | +| `non_operational` | `removed` | `maintenance_pick_up` | The vehicle has entered the depot for maintenance | +| `non_operational` | `removed` | `decommissioned` | The vehicle has been removed from the Provider's fleet | + +| From `vehicle_state` | To `vehicle_state` | `event_type` | Description | +|----------------------|--------------------|---------------------------|-----------------------------------------------------------------------------------------------------------------| +| `on_trip` | `elsewhere` | `trip_leave_jurisdiction` | The vehicle has left jurisdictional boundaries while on a trip | +| `on_trip` | `non_contactable` | `comms_lost` | The vehicle has gone out of comms while on a trip | +| `on_trip` | `stopped` | `trip_stop` | The vehicle has stopped while on a trip | + +| From `vehicle_state` | To `vehicle_state` | `event_type` | Description | +|----------------------|--------------------|---------------------------|-----------------------------------------------------------------------------------------------------------------| +| `removed` | `non_contactable` | `comms_lost` | The vehicle has gone out of comms while removed | +| `removed` | `non_operational` | `maintenance_end` | The vehicle has left the depot | +| `removed` | `non_operational` | `recommissioned` | The vehicle has been re-added to the Provider's fleet after being previously `decommissioned` | + +| From `vehicle_state` | To `vehicle_state` | `event_type` | Description | +|----------------------|--------------------|---------------------------|-----------------------------------------------------------------------------------------------------------------| +| `reserved` | `available` | `driver_cancellation` | The driver has canceled the reservation | +| `reserved` | `available` | `passenger_cancellation` | The passenger has canceled the reservation | +| `reserved` | `available` | `provider_cancellation` | The provider has canceled the reservation | +| `reserved` | `elsewhere` | `trip_leave_jurisdiction` | The vehicle has left the jurisdiction while in a reservation | +| `reserved` | `non_contactable` | `comms_lost` | The vehicle went out of comms while being reserved by a passenger | +| `reserved` | `stopped` | `reservation_stop` | The vehicle has stopped to pick up the passenger | + +| From `vehicle_state` | To `vehicle_state` | `event_type` | Description | +|----------------------|--------------------|---------------------------|-----------------------------------------------------------------------------------------------------------------| +| `stopped` | `available` | `driver_cancellation` | The driver has canceled the trip while either waiting for the passenger, or dropping them off | +| `stopped` | `available` | `passenger_cancellation` | The passenger has canceled the trip while the vehicle is waiting to pick them up, or they are being dropped off | +| `stopped` | `available` | `provider_cancellation` | The provider has canceled the trip while the vehicle is waiting for a passenger, or dropping them off | +| `stopped` | `available` | `trip_end` | The trip has been successfully completed | +| `stopped` | `non_contactable` | `comms_lost` | The vehicle has went out of comms while stopped | +| `stopped` | `on_trip` | `trip_resume` | Resume a trip that was previously stopped (e.g. picking up a friend to go to the airport with) | +| `stopped` | `on_trip` | `trip_start` | Start a trip | [Top][toc] ### State Machine Diagram -This *State Machine Diagram* shows how `vehicle_state` and `event_type` relate to each other and how vehicles can transition between states. See [Google Slides](https://docs.google.com/presentation/d/1fHdq1efbN5GSFDLF4en-oA_BYPXQKbbIbHff6iROJKA/edit#slide=id.g2072486e468_1_19) for the source file. +This *State Machine Diagram* shows how `vehicle_state` and `event_type` relate to each other and how vehicles can transition between states. See [Google Slides](https://docs.google.com/presentation/d/1FCrBCtNQyoIcchaGx6zw4BpLCquQaWmBHsEU6fUdUoo/edit?slide=id.g2072486e468_1_19#slide=id.g2072486e468_1_19) for the source file. ![Passenger State Machine Diagram](passenger-services-state-machine-diagram.svg) From dd807a31a973d9faa47afac05f67b4c7522e5283 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 6 Feb 2026 14:28:19 -0500 Subject: [PATCH 146/168] New Fleet state diagram link Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/car-share.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modes/car-share.md b/modes/car-share.md index d7250abe4..8d609024c 100644 --- a/modes/car-share.md +++ b/modes/car-share.md @@ -410,7 +410,7 @@ This is the list of `vehicle_state` and `event_type` pairings that constitute th ### State Machine Diagram -This *State Machine Diagram* shows how `vehicle_state` and `event_type` relate to each other and how vehicles can transition between states. See [Google Slides](https://docs.google.com/presentation/d/1fHdq1efbN5GSFDLF4en-oA_BYPXQKbbIbHff6iROJKA/edit#slide=id.g2072486e468_1_300) for the source file. +This *State Machine Diagram* shows how `vehicle_state` and `event_type` relate to each other and how vehicles can transition between states. See [Google Slides](https://docs.google.com/presentation/d/1FCrBCtNQyoIcchaGx6zw4BpLCquQaWmBHsEU6fUdUoo/edit?slide=id.g2072486e468_1_300#slide=id.g2072486e468_1_300) for the source file. ![Fleet State Machine Diagram](car-share-state-machine-diagram.svg) From e0caa6b9283dbe0bc95dd481c9ccbed3084ecf30 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 6 Feb 2026 14:29:49 -0500 Subject: [PATCH 147/168] New Micro state diagram link Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/micromobility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modes/micromobility.md b/modes/micromobility.md index bc871077c..ad38812b1 100644 --- a/modes/micromobility.md +++ b/modes/micromobility.md @@ -278,7 +278,7 @@ This is the list of `vehicle_state` and `event_type` pairings that constitute th ### State Machine Diagram -This *State Machine Diagram* shows how `vehicle_state` and `event_type` relate to each other and how vehicles can transition between states. See [Google Slides](https://docs.google.com/presentation/d/1fHdq1efbN5GSFDLF4en-oA_BYPXQKbbIbHff6iROJKA/edit#slide=id.g206f7c6e12e_0_0) for the source file. +This *State Machine Diagram* shows how `vehicle_state` and `event_type` relate to each other and how vehicles can transition between states. See [Google Slides](https://docs.google.com/presentation/d/1FCrBCtNQyoIcchaGx6zw4BpLCquQaWmBHsEU6fUdUoo/edit?slide=id.g206f7c6e12e_0_0#slide=id.g206f7c6e12e_0_0) for the source file. ![micromobility-state-machine-diagram](/modes/micromobility-state-machine-diagram.svg) From 26e0078d73752b9ce407dc59d61b68b6f0980cd8 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Wed, 11 Feb 2026 19:42:40 -0500 Subject: [PATCH 148/168] Added `hardware_model` to Vehicle Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- data-types.md | 1 + 1 file changed, 1 insertion(+) diff --git a/data-types.md b/data-types.md index 3166a7d99..3bee9f099 100644 --- a/data-types.md +++ b/data-types.md @@ -38,6 +38,7 @@ A vehicle record is as follows: | `battery_capacity` | Integer | Required if Available | Capacity of battery expressed as milliamp hours (mAh) | | `fuel_capacity` | Integer | Required if Available | Capacity of fuel tank (liquid, solid, gaseous) expressed in liters | | `maximum_speed` | Integer | Required if Available | Maximum speed (kph) possible with vehicle under normal, flat incline, smooth surface conditions. Applicable if the device has a built-in or intelligent speed limiter/governor. | +| `hardware_model` | String | Number, identifier, or description of the main device hardware model. Can apply to and mode. | | `commissioned` | [Timestamp][ts] | Conditionally Required | Date/time the vehicle first starts providing service in the jurisdiction. Required if asked for by public agency. | | `decommissioned` | [Timestamp][ts] | Conditionally Required | Date/time the vehicle stops providing service in the jurisdiction and is decommissioned. Required when the vehicle is retired from operations. | From 204d288f5437fd57e8342befc74702cf598daa49 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Wed, 11 Feb 2026 19:43:24 -0500 Subject: [PATCH 149/168] Set requirement of `hardware_model` Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- data-types.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/data-types.md b/data-types.md index 3bee9f099..c1982f778 100644 --- a/data-types.md +++ b/data-types.md @@ -38,7 +38,7 @@ A vehicle record is as follows: | `battery_capacity` | Integer | Required if Available | Capacity of battery expressed as milliamp hours (mAh) | | `fuel_capacity` | Integer | Required if Available | Capacity of fuel tank (liquid, solid, gaseous) expressed in liters | | `maximum_speed` | Integer | Required if Available | Maximum speed (kph) possible with vehicle under normal, flat incline, smooth surface conditions. Applicable if the device has a built-in or intelligent speed limiter/governor. | -| `hardware_model` | String | Number, identifier, or description of the main device hardware model. Can apply to and mode. | +| `hardware_model` | String | Required if Available | Number, identifier, or description of the main device hardware model. Can apply to and mode. | | `commissioned` | [Timestamp][ts] | Conditionally Required | Date/time the vehicle first starts providing service in the jurisdiction. Required if asked for by public agency. | | `decommissioned` | [Timestamp][ts] | Conditionally Required | Date/time the vehicle stops providing service in the jurisdiction and is decommissioned. Required when the vehicle is retired from operations. | From f3ba37210b1a5837bbb77f0f256c4c2553c03cae Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Wed, 11 Feb 2026 19:46:25 -0500 Subject: [PATCH 150/168] Added `software_version` and `description` to Event Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- data-types.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/data-types.md b/data-types.md index c1982f778..0fd5479b4 100644 --- a/data-types.md +++ b/data-types.md @@ -119,6 +119,8 @@ Events represent changes in vehicle status. | `timestamp` | [Timestamp][ts] | Required | Date/time that event occurred at. See [Event Times][event-times] | | `publication_time` | [Timestamp][ts] | [Optional](./general-information.md#optional-fields) | Date/time that event became available through the status changes endpoint | | `location` | [GPS][gps] | Required | See also [Telemetry][telemetry]. | +| `software_version` | String | [Optional](./general-information.md#optional-fields) | Software version the main device is running on | +| `description` | String | [Optional](./general-information.md#optional-fields) | Description of the reason for the event, e.g. the type and reason for maintenance performed, software version upgrade, reason for system suspension, comms lost details, provider pickup reason, etc. | | `event_geographies` | UUID[] | [Optional](./general-information.md#optional-fields) | Array of Geography UUIDs consisting of every Geography that contains the location of the status change. See [Geography Driven Events][geography-driven-events]. Required if `location` and `statistical_area_ids` are not present. | | `statistical_areas` | Strings[] | [Optional](./general-information.md#optional-fields) | Array of statistical area identifier(s) where the event occurred. e.g. US census area IDs (tract, block group, block, etc), Canadian dissemination blocks or areas, UK output areas, etc, or any other pre-defined standard district, area, sector, neighborhood, etc. Details of the type and meaning of these identifiers are communicated between the public agency and operator outside of MDS. Note that instead of these pre-defined areas, custom geographic areas can be defined using `event_geographies`. Required if `location` and `event_geographies` are not present. | | `battery_percent` | Integer | [Required if Applicable](./general-information.md#required-if-applicable-fields) | Percent battery charge of vehicle, expressed between 0 and 100 | From df324e9f345adc7da599c3b28735e4184c7306e7 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 12 Feb 2026 09:52:12 -0500 Subject: [PATCH 151/168] Description updates Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- data-types.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/data-types.md b/data-types.md index 0fd5479b4..d528d12df 100644 --- a/data-types.md +++ b/data-types.md @@ -38,7 +38,7 @@ A vehicle record is as follows: | `battery_capacity` | Integer | Required if Available | Capacity of battery expressed as milliamp hours (mAh) | | `fuel_capacity` | Integer | Required if Available | Capacity of fuel tank (liquid, solid, gaseous) expressed in liters | | `maximum_speed` | Integer | Required if Available | Maximum speed (kph) possible with vehicle under normal, flat incline, smooth surface conditions. Applicable if the device has a built-in or intelligent speed limiter/governor. | -| `hardware_model` | String | Required if Available | Number, identifier, or description of the main device hardware model. Can apply to and mode. | +| `hardware_model` | String | Required if Available | Number, identifier, or description of the main device hardware model. Can apply to any mode. | | `commissioned` | [Timestamp][ts] | Conditionally Required | Date/time the vehicle first starts providing service in the jurisdiction. Required if asked for by public agency. | | `decommissioned` | [Timestamp][ts] | Conditionally Required | Date/time the vehicle stops providing service in the jurisdiction and is decommissioned. Required when the vehicle is retired from operations. | @@ -119,8 +119,8 @@ Events represent changes in vehicle status. | `timestamp` | [Timestamp][ts] | Required | Date/time that event occurred at. See [Event Times][event-times] | | `publication_time` | [Timestamp][ts] | [Optional](./general-information.md#optional-fields) | Date/time that event became available through the status changes endpoint | | `location` | [GPS][gps] | Required | See also [Telemetry][telemetry]. | -| `software_version` | String | [Optional](./general-information.md#optional-fields) | Software version the main device is running on | -| `description` | String | [Optional](./general-information.md#optional-fields) | Description of the reason for the event, e.g. the type and reason for maintenance performed, software version upgrade, reason for system suspension, comms lost details, provider pickup reason, etc. | +| `software_version` | String | [Optional](./general-information.md#optional-fields) | Software version the main device is running on. Can be provided only when there is an update. | +| `description` | String | [Optional](./general-information.md#optional-fields) | Description of the reason for the event, e.g. the type and reason for maintenance performed, note a software version upgrade, reason for system suspension, comms lost details, provider pickup reason, inspection details, etc. | | `event_geographies` | UUID[] | [Optional](./general-information.md#optional-fields) | Array of Geography UUIDs consisting of every Geography that contains the location of the status change. See [Geography Driven Events][geography-driven-events]. Required if `location` and `statistical_area_ids` are not present. | | `statistical_areas` | Strings[] | [Optional](./general-information.md#optional-fields) | Array of statistical area identifier(s) where the event occurred. e.g. US census area IDs (tract, block group, block, etc), Canadian dissemination blocks or areas, UK output areas, etc, or any other pre-defined standard district, area, sector, neighborhood, etc. Details of the type and meaning of these identifiers are communicated between the public agency and operator outside of MDS. Note that instead of these pre-defined areas, custom geographic areas can be defined using `event_geographies`. Required if `location` and `event_geographies` are not present. | | `battery_percent` | Integer | [Required if Applicable](./general-information.md#required-if-applicable-fields) | Percent battery charge of vehicle, expressed between 0 and 100 | From f8ae188780d9c1875d896efc770e10fe0e9d4d40 Mon Sep 17 00:00:00 2001 From: Marcus V Date: Wed, 18 Feb 2026 11:36:17 -0800 Subject: [PATCH 152/168] Update providers.csv with Transwest Signed-off-by: Marcus V --- providers.csv | 1 + 1 file changed, 1 insertion(+) diff --git a/providers.csv b/providers.csv index 7eaf56aa4..a07ebbf16 100644 --- a/providers.csv +++ b/providers.csv @@ -81,3 +81,4 @@ Track My Shuttle,passenger-services,dd7db795-09c0-402f-9441-360235da3025,https:/ Greenwheels,car-share,5f88cd9e-2c7e-477a-a531-f68143121876,https://www.greenwheels.nl,, Sixt,car-share,df72d104-372f-4d98-a4c3-9b001967990e,https://sixt.com/,https://api.orange.sixt.com/v1/share-third-party-sources/mds,https://api.orange.sixt.com/v1/share-third-party-sources/gbfs Getaround,car-share,ede4d096-1641-4077-b986-37c602e881ae,https:getaround.com/,,https://api-eu.getaround.com/gbfs/manifest?country_code=FR +Transwest,passenger-services,8cf2ebbb-f2d4-46a7-98d2-e10e229cf718,https://www.transwestco.com/,, From 077418b9b3413b12760f444f883805e50506709e Mon Sep 17 00:00:00 2001 From: Michael Schwartz Date: Wed, 11 Mar 2026 09:13:40 -0400 Subject: [PATCH 153/168] Create edits Signed-off-by: Michael Schwartz --- edits | 1 + 1 file changed, 1 insertion(+) create mode 100644 edits diff --git a/edits b/edits new file mode 100644 index 000000000..8b1378917 --- /dev/null +++ b/edits @@ -0,0 +1 @@ + From 09cb7132f4d20cef118c1e10ba78e353a52488f1 Mon Sep 17 00:00:00 2001 From: Phil Teigne Date: Wed, 18 Feb 2026 22:20:45 -0500 Subject: [PATCH 154/168] Add Drop Mobility to listed providers --- providers.csv | 1 + 1 file changed, 1 insertion(+) diff --git a/providers.csv b/providers.csv index a07ebbf16..684b1c582 100644 --- a/providers.csv +++ b/providers.csv @@ -82,3 +82,4 @@ Greenwheels,car-share,5f88cd9e-2c7e-477a-a531-f68143121876,https://www.greenwhee Sixt,car-share,df72d104-372f-4d98-a4c3-9b001967990e,https://sixt.com/,https://api.orange.sixt.com/v1/share-third-party-sources/mds,https://api.orange.sixt.com/v1/share-third-party-sources/gbfs Getaround,car-share,ede4d096-1641-4077-b986-37c602e881ae,https:getaround.com/,,https://api-eu.getaround.com/gbfs/manifest?country_code=FR Transwest,passenger-services,8cf2ebbb-f2d4-46a7-98d2-e10e229cf718,https://www.transwestco.com/,, +Drop Mobility,micromobility,f219d244-5f62-45f1-8e79-fb0274ac58fe,https://dropmobility.com/,https://mds.dropmobility.com,https://gbfs.dropmobility.com \ No newline at end of file From 68f080a4089441250c311c90a1c5b90d9d4c8755 Mon Sep 17 00:00:00 2001 From: Michael Schwartz Date: Wed, 11 Mar 2026 11:33:33 -0400 Subject: [PATCH 155/168] Delete edits Signed-off-by: Michael Schwartz --- edits | 1 - 1 file changed, 1 deletion(-) delete mode 100644 edits diff --git a/edits b/edits deleted file mode 100644 index 8b1378917..000000000 --- a/edits +++ /dev/null @@ -1 +0,0 @@ - From 3077a77213dc942b030071768b6d7b00d1218905 Mon Sep 17 00:00:00 2001 From: Michael Schwartz Date: Wed, 11 Mar 2026 11:54:28 -0400 Subject: [PATCH 156/168] Update micromobility.md Signed-off-by: Michael Schwartz --- modes/micromobility.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/modes/micromobility.md b/modes/micromobility.md index d1adb14e5..745279b17 100644 --- a/modes/micromobility.md +++ b/modes/micromobility.md @@ -74,7 +74,8 @@ The `trip_attributes` object is not used in this mode. ### Fare Attributes -The `fare_attributes` object is not used in this mode. +The `fare_attributes` object may have the following key value pairs: +- `rate_code_id` (enumerated, Optional) - one of `standard`, `access` [Top][toc] From 858154ecc7871d3cb1eb1d8be1af0ad118d8efee Mon Sep 17 00:00:00 2001 From: Joseph Lai <90877795+josephlaidoordash@users.noreply.github.com> Date: Wed, 18 Mar 2026 14:57:36 -0500 Subject: [PATCH 157/168] Added DoorDash as a MDS provider Signed-off-by: Joseph Lai <90877795+josephlaidoordash@users.noreply.github.com> --- providers.csv | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/providers.csv b/providers.csv index 684b1c582..c76e9f7e0 100644 --- a/providers.csv +++ b/providers.csv @@ -82,4 +82,5 @@ Greenwheels,car-share,5f88cd9e-2c7e-477a-a531-f68143121876,https://www.greenwhee Sixt,car-share,df72d104-372f-4d98-a4c3-9b001967990e,https://sixt.com/,https://api.orange.sixt.com/v1/share-third-party-sources/mds,https://api.orange.sixt.com/v1/share-third-party-sources/gbfs Getaround,car-share,ede4d096-1641-4077-b986-37c602e881ae,https:getaround.com/,,https://api-eu.getaround.com/gbfs/manifest?country_code=FR Transwest,passenger-services,8cf2ebbb-f2d4-46a7-98d2-e10e229cf718,https://www.transwestco.com/,, -Drop Mobility,micromobility,f219d244-5f62-45f1-8e79-fb0274ac58fe,https://dropmobility.com/,https://mds.dropmobility.com,https://gbfs.dropmobility.com \ No newline at end of file +Drop Mobility,micromobility,f219d244-5f62-45f1-8e79-fb0274ac58fe,https://dropmobility.com/,https://mds.dropmobility.com,https://gbfs.dropmobility.com +DoorDash,delivery-robots,6728346d-5ad1-4ddb-81d6-161c915a3d35,https://www.doordash.com/,, From 2fdfef21f994b03a2c326ec472fdc16cd143320f Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 27 Mar 2026 13:28:17 -0400 Subject: [PATCH 158/168] Added world map Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index efa785eb0..ab2126c56 100644 --- a/README.md +++ b/README.md @@ -32,7 +32,9 @@ The Mobility Data Specification (**MDS**), a project of the [Open Mobility Found ### History -**MDS** is an open-source project originally created by the [Los Angeles Department of Transportation](http://ladot.io) (LADOT). In November 2019, stewardship of MDS and the ownership of this repository were transferred to the [Open Mobility Foundation](http://www.openmobilityfoundation.org). GitHub automatically redirects any links to this repository from the `CityOfLosAngeles` organization to the `openmobilityfoundation` instead. MDS continues to be used by LADOT and [many other municipalities](#cities-using-mds) and companies (confirmed over 200 mobility operators, operating in over 1,000 cities globally, and 2 billion trips sent). +**MDS** is an open-source project originally created by the [Los Angeles Department of Transportation](http://ladot.io) (LADOT). In November 2019, stewardship of MDS and the ownership of this repository were transferred to the [Open Mobility Foundation](http://www.openmobilityfoundation.org). GitHub automatically redirects any links to this repository from the `CityOfLosAngeles` organization to the `openmobilityfoundation` instead. MDS continues to be used by LADOT and [many other municipalities](#cities-using-mds) and companies (confirmed over 200 mobility operators, operating in over 1,200 cities globally, and 2 billion trips sent) as a global standard. + +![MDS Global Map](https://i.imgur.com/Mx8qHwz.png) [Top][toc] From 8131356bdb42fb7a66c725934cd89a7cebddf6d2 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 27 Mar 2026 13:29:50 -0400 Subject: [PATCH 159/168] Added member option Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/micromobility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modes/micromobility.md b/modes/micromobility.md index 745279b17..167a28a75 100644 --- a/modes/micromobility.md +++ b/modes/micromobility.md @@ -75,7 +75,7 @@ The `trip_attributes` object is not used in this mode. ### Fare Attributes The `fare_attributes` object may have the following key value pairs: -- `rate_code_id` (enumerated, Optional) - one of `standard`, `access` +- `rate_code_id` (enumerated, Optional) - one of `standard`, `access`, `member` [Top][toc] From 76c4188bd18ad9c5cbce5f0fab838384653fc11c Mon Sep 17 00:00:00 2001 From: Marcus V Date: Wed, 8 Apr 2026 14:29:34 -0700 Subject: [PATCH 160/168] Update providers with Peak Transit.csv Signed-off-by: Marcus V --- providers.csv | 1 + 1 file changed, 1 insertion(+) diff --git a/providers.csv b/providers.csv index c76e9f7e0..c525d4437 100644 --- a/providers.csv +++ b/providers.csv @@ -84,3 +84,4 @@ Getaround,car-share,ede4d096-1641-4077-b986-37c602e881ae,https:getaround.com/,,h Transwest,passenger-services,8cf2ebbb-f2d4-46a7-98d2-e10e229cf718,https://www.transwestco.com/,, Drop Mobility,micromobility,f219d244-5f62-45f1-8e79-fb0274ac58fe,https://dropmobility.com/,https://mds.dropmobility.com,https://gbfs.dropmobility.com DoorDash,delivery-robots,6728346d-5ad1-4ddb-81d6-161c915a3d35,https://www.doordash.com/,, +Peak Transit,passenger-services,b0a0cc68-6248-4d5c-b514-bc44fbfb5d96,https://www.peaktransit.com/,, From 4a0d1ad3d1d4cd86818c88bfb9325657e3c37f24 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 14 Apr 2026 11:47:14 -0400 Subject: [PATCH 161/168] Fixed order drop off/pick up descriptions Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/event_types.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modes/event_types.md b/modes/event_types.md index 5046d9e6a..b71e73e6b 100644 --- a/modes/event_types.md +++ b/modes/event_types.md @@ -28,8 +28,8 @@ As with all MDS definitions, they should be described in a way that maximizes th | `not_located` | Location unknown | | `off_hours` | Off hours - end of service | | `on_hours` | On hours - start of service | -| `order_drop_off` | Pick up of the order at business | -| `order_pick_up` | Delivery of the order at the customer location | +| `order_drop_off` | Delivery of the order at the customer location | +| `order_pick_up` | Pick up of the order at business | | `passenger_cancellation` | Passenger cancelled a trip (if known, and more specific than `trip_cancel`) | | `provider_cancellation` | Provider cancelled a trip (if known, and more specific than `trip_cancel`) | | `provider_drop_off` | Drop off by the provider | From 8c329f0f99f707e1d97f69e396792c8215bbfdf3 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 14 Apr 2026 11:48:34 -0400 Subject: [PATCH 162/168] Minor update to order pick up/drop off description Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/delivery-robots.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modes/delivery-robots.md b/modes/delivery-robots.md index b3caf1333..52dbc337a 100644 --- a/modes/delivery-robots.md +++ b/modes/delivery-robots.md @@ -401,8 +401,8 @@ This is the list of `vehicle_state` and `event_type` pairings that constitute th |----------------------|--------------------|---------------------------|-----------------------------------------------------------------------------------------------| | `on_trip` | `elsewhere` | `trip_leave_jurisdiction` | The vehicle has left jurisdictional boundaries while on a trip | | `on_trip` | `non_contactable` | `comms_lost` | The vehicle has gone out of comms while on a trip to pick up the order | -| `on_trip` | `stopped` | `order_drop_off` | The vehicle is at the customer's place and is waiting for them | -| `on_trip` | `stopped` | `order_pick_up` | The vehicle has come to pick up the order at the restaurant | +| `on_trip` | `stopped` | `order_drop_off` | The vehicle is at the customer's place | +| `on_trip` | `stopped` | `order_pick_up` | The vehicle has come to pick up the order from the origin point | | `on_trip` | `stopped` | `trip_pause` | The vehicle has paused while on a trip | | From `vehicle_state` | To `vehicle_state` | `event_type` | Description | From 164a39cbc66364355263e4a82eaf8a9cd6d80e06 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 14 Apr 2026 11:52:52 -0400 Subject: [PATCH 163/168] Version updates on home page Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index ab2126c56..48c1f8e27 100644 --- a/README.md +++ b/README.md @@ -121,7 +121,7 @@ Support for other shared modes, services, programs, and vehicles has been discus # Versions -MDS has a **current release** (version 2.0.0), **previous releases** (both recommended and longer recommended for use), and **upcoming releases** in development. For a full list of releases, their status, recommended versions, and timelines, see the [Official MDS Releases](https://github.com/openmobilityfoundation/governance/wiki/Releases) page. +MDS has a **current release** (version 2.1.0), **previous releases** (both recommended and longer recommended for use), and **upcoming releases** in development. For a full list of releases, their status, recommended versions, and timelines, see the [Official MDS Releases](https://github.com/openmobilityfoundation/governance/wiki/Releases) page. The OMF provides guidance on upgrading for cities, providers, and software companies, and sample permit language for cities. See our [MDS Version Guidance](https://github.com/openmobilityfoundation/governance/blob/main/technical/OMF-MDS-Version-Guidance.md) for best practices on how and when to upgrade MDS as new versions become available. Our complimentary [MDS Policy Language Guidance](https://github.com/openmobilityfoundation/governance/blob/main/technical/OMF-MDS-Policy-Language-Guidance.md) document is for cities writing MDS into their operating policy and includes sample policy language. @@ -174,7 +174,7 @@ Read about [how to become an OMF member](https://www.openmobilityfoundation.org/ # Cities Using MDS -More than 200 cities and public agencies across 21 countries around the world are known to use MDS, and it has been implemented by most major [mobility service providers](#providers-using-mds). +More than 1,200 cities and public agencies across 21 countries around the world are known to use MDS, and it has been implemented by over 200 major [mobility service providers](#providers-using-mds). - See our **[list of cities using MDS](https://www.openmobilityfoundation.org/mds-users/#cities-using-mds)** with links to public mobility websites and policy/permit documents. Please let us know [via our website](https://www.openmobilityfoundation.org/get-in-touch/) or in the [public discussion area](https://github.com/openmobilityfoundation/mobility-data-specification/discussions) if you are an agency using MDS so we can add you to the city resource list, especially if you have published your policies or documents publicly. @@ -185,7 +185,7 @@ To add yourself to the [agency list](/agencies.csv) and add your [Policy Require # Providers Using MDS -Over four dozen mobility service providers (MSPs) around the world use MDS, allowing them to create tools around a single data standard for multiple cities. +Over 200 mobility service providers (MSPs) around the world use MDS, allowing them to create tools around a single data standard for multiple cities globally. - See our **[list of providers using MDS](https://www.openmobilityfoundation.org/mds-users/#mobility-providers-using-mds)**. For a table list with unique IDs, see the MDS [provider list](/providers.csv) which includes both service operators and data solution providers. - A provider needs a unique ID for each [mode](#modes) they operate under. @@ -196,7 +196,7 @@ To add yourself to the provider list, please let us know [via our website](https # Software Companies Using MDS -An open source approach to data specifications benefits cities and companies by creating a space for collaborative development, reducing costs, and nurturing a healthy, competitive ecosystem for mobility services and software tools. The open model promotes a competitive ecosystem for software tools built by dozens of software companies providing their services to cities, agencies, and providers. +An open source approach to data specifications benefits cities and companies by creating a space for collaborative development, reducing costs, and nurturing a healthy, competitive ecosystem for mobility services and software tools. The open model promotes a competitive ecosystem for software tools built by dozens of software companies and vendors providing their services to cities, agencies, and providers. - See our **[list of third party software companies using MDS](https://www.openmobilityfoundation.org/mds-users/#software-companies-using-mds)** and an article about the [benefits of an open approach](https://www.openmobilityfoundation.org/why-open-behind-omfs-unique-open-source-model/). - For a table list with unique IDs, see the MDS [provider list](/providers.csv) which includes both service operators and data solution providers. @@ -234,7 +234,7 @@ How cities use MDS depends on a variety of factors: their transportation goals, - **Resident Complaints:** Investigate and validate complaints from residents about operations, parking, riding, speed, etc, usually reported through 311 - **Infrastructure Planning:** Determine where to place new bike/scooter lanes and drop zones based on usage and demand, start and end points, and trips taken -A list of use cases is useful to show what's possible with MDS, to list what other cities are accomplishing with the data, to see many use cases up front for privacy considerations, and to use for policy discussions and policy language. More details and examples can be seen on the [OMF website](https://www.openmobilityfoundation.org/whats-possible-with-mds/) and our [Wiki Database](https://github.com/openmobilityfoundation/governance/wiki/MDS-Use-Cases). An agency may align their program to specific use cases by publishing [Policy Requirement use cases](/policy#requirement-apis). +A list of more than 60 use cases is useful to show what's possible with MDS, to list what other cities are accomplishing with the data, to see many use cases up front for privacy considerations, and to use for policy discussions and policy language. More details and examples can be seen on the [OMF website](https://www.openmobilityfoundation.org/whats-possible-with-mds/) and our [Wiki Database](https://github.com/openmobilityfoundation/governance/wiki/MDS-Use-Cases). An agency may align their program to specific use cases by publishing [Policy Requirement use cases](/policy#requirement-apis). Please [let us know](https://docs.google.com/forms/d/e/1FAIpQLScrMPgeb1TKMYCjjKsJh3y1TPTJO8HR_y1NByrf1rDmTEJS7Q/viewform) if you have recommended updates or use cases to add. From 8b66af8c252eea144371cd166e53cf16c2249b39 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Wed, 15 Apr 2026 11:47:37 -0400 Subject: [PATCH 164/168] New API diagram with Incidents Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 48c1f8e27..ac9439b7d 100644 --- a/README.md +++ b/README.md @@ -86,7 +86,7 @@ Many parts of the MDS definitions and APIs align across each other. In these cas You can read more in our **[Understanding the different MDS APIs](https://github.com/openmobilityfoundation/governance/blob/main/technical/Understanding-MDS-APIs.md)** guide. -![MDS APIs and Endpoints](https://i.imgur.com/i27Mmfw.png) +![MDS APIs and Endpoints](https://i.imgur.com/4xVWwbj.png) ## GBFS Requirement From a363386b7ee9b1295fe029e0497aab33b9ec96f2 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 16 Apr 2026 14:56:07 -0400 Subject: [PATCH 165/168] Added delivery examples Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index ac9439b7d..dc14799b1 100644 --- a/README.md +++ b/README.md @@ -103,7 +103,7 @@ MDS supports multiple "modes", defined as a distinct regulatory framework for a - **[Micromobility](/modes/micromobility.md)** - customer operated dockless or docked small devices moving customers and goods, such as scooters, bikeshare, cargo bikes, adaptive scooters, docked bikes, mopeds, trikes, and quadracycles. - **[Passenger](/modes/passenger-services.md)** - employees and contractors, autonomous, and remotely operated transporting individuals or goods with a vehicle driven by another entity, including taxis, for-hire AVs, robotaxis, busses, transportation network companies (TNCs), commercial transport apps (CTAs), and private hire vehicles (PHVs), shuttles, paratransit, on demand vehicles, limosines, and microtransit. - **[Fleet](/modes/car-share.md)** - customer, employees and contractors, autonomous, and remotely operated shared point-to-point, station-based, or free-floating multi-passenger or cargo vehicles like consumer car share, sanitation vehicles (garbage, recycling), city fleets, vehicle rentals, street sweepers, snow plows, utility services, construction, emergency response (police, fire, ambulance), tree maintenance, inspection and permitting vehicles, mobile health clinics, and heavy maintenance vehicles. -- **[Delivery](/modes/delivery-robots.md)** - employees and contractors, autonomous, and remotely operated sidewalk robots, app delivery, packages, freight, goods, food, private hire vehicles, postal service, medicine, and other delivery services. +- **[Delivery](/modes/delivery-robots.md)** - employees and contractors, autonomous, and remotely operated sidewalk robots, app delivery, packages, freight, goods, food, private hire vehicles, electric cargo bikes and trikes, mopeds and motorcycles, box trucks, bike and scooter couriers, cargo vans, semi-trucks and tractor-trailers, postal service, medicine, and other delivery services.

MDS Mode - Micromobility       From 5f71c337ec201e8bb37ae47c87e28e9045f5e019 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 16 Apr 2026 14:56:36 -0400 Subject: [PATCH 166/168] Added more delivery types Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- modes/delivery-robots.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modes/delivery-robots.md b/modes/delivery-robots.md index 52dbc337a..9477e41b0 100644 --- a/modes/delivery-robots.md +++ b/modes/delivery-robots.md @@ -2,7 +2,7 @@ MDS Modes - Delivery Robots -**Delivery** refers to employees and contractors, autonomous, and remotely operated sidewalk robots, app delivery, packages, freight, goods, food, private hire vehicles, postal service, medicine, and other delivery services. +**Delivery** refers to employees and contractors, autonomous, and remotely operated sidewalk robots, app delivery, packages, freight, goods, food, private hire vehicles, electric cargo bikes and trikes, mopeds and motorcycles, box trucks, bike and scooter couriers, cargo vans, semi-trucks and tractor-trailers, postal service, medicine, and other delivery services. There can be one or multiple orders on different trips at the same time, connected via the journey identifier. The state machine tracks the trip states of the orders separately from the vehicle state. From a715460879d2c3bb56b03b3a02c74c9445f27124 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 16 Apr 2026 15:31:42 -0400 Subject: [PATCH 167/168] Release notes for 2.1 RC Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- ReleaseNotes.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/ReleaseNotes.md b/ReleaseNotes.md index 5a2cb7499..271ccb982 100644 --- a/ReleaseNotes.md +++ b/ReleaseNotes.md @@ -1,3 +1,15 @@ +## 2.1.0 + +> Released: xxxx + +The 2.1 release is a minor release. + +### CHANGES + +See the [Milestone 2.1.0](https://github.com/openmobilityfoundation/mobility-data-specification/milestone/17) and [Issues](https://github.com/openmobilityfoundation/mobility-data-specification/milestone/17?closed=1) for a full list of changes. + +**Full [Release Notes](https://github.com/openmobilityfoundation/mobility-data-specification/releases/tag/2.1.0)** for details. + ## 2.0.2 > Release 2025.06.04 From 2236fdce4925d766cc29e868c4b57f210d47d5b0 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 20 Apr 2026 14:24:15 -0400 Subject: [PATCH 168/168] Added more External Reference examples Signed-off-by: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> --- data-types.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/data-types.md b/data-types.md index d528d12df..1db883eb0 100644 --- a/data-types.md +++ b/data-types.md @@ -388,7 +388,7 @@ An `external_reference` is a JSON *array* with the following fields within objec | Name | Type | Required/Optional | Description | | ------ | ------ | ------------------- | ------------- | | `reference_url` | URL | Required | A web-accessible identifier URL for the source of the publicly or privately accessible data feed, document, website, etc. This MUST be a full HTTPS URL pointing to a location which contains more information impacting or explaining the location, event, or policy, etc. | -| `name` | String | [Optional](./general-information.md#optional-fields) | Name of the data source for reference. E.g. "WZDx", "CWZ", "CDS", "GBFS", "GTFS", "MDS". | +| `name` | String | [Optional](./general-information.md#optional-fields) | Name of the data source for reference. E.g. "WZDx", "CWZ", "GBFS", "GTFS", "Waze CIF", "TOMP", "OCPI", "NEVI", "DATEX", "TODS", "TIDES", even across to "CDS", and back to "MDS". | | `public` | Boolean | [Optional](./general-information.md#optional-fields) | Is this data source able to be viewed with out any sort of authentication? If `true`, the `reference_url` is public. If `false`, the `reference_url` requires some sort of authentication, authorization, or API key to access. This is an informational field to set access expectations for the data source user, and does not provide any credentials directly unless explicitly contained in the `reference_url`. | | `identifier_name` | String | [Optional](./general-information.md#optional-fields) | The name of the data field identifier or object that is referenced by the unique `ids`. E.g. "id", "report_id", "trip_id", "vehicle_id", "RoadEventFeature", etc, if relevant and available in `reference_url`. | | `ids` | Array of Strings | [Optional](./general-information.md#optional-fields) | An array of one or more **ids** from the data sources that impacts the use of or relationship to part of MDS, e.g. Trips, Events, Stops, etc. The **ids** and their details are be found in the referenced `reference_url`. |