diff --git a/README.md b/README.md index b7c6fccf..8dd8ffa3 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


diff --git a/data-types.md b/data-types.md index 6e9b175a..81768fde 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` | diff --git a/modes/README.md b/modes/README.md index 26187fc7..c4415b07 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


diff --git a/modes/delivery-robots.md b/modes/delivery-robots.md index d170a91c..3d28e056 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 +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 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 @@ -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 a driver or operator's working 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 @@ -78,7 +77,8 @@ 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] @@ -87,10 +87,16 @@ 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. -- `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 +- `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? @@ -102,6 +108,9 @@ 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 [Top][toc] @@ -118,8 +127,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 @@ -243,7 +253,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 | @@ -259,9 +269,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`