Feature modes passenger services

README.md

@@ -10,7 +10,7 @@
 - [Versions](#versions)
   - [Technical Information](#technical-information)
 - [Get Involved](#get-involved)
-  - [Membership](#membership)  
+  - [Membership](#membership)
 - [Cities Using MDS](#cities-using-mds)
 - [Providers Using MDS](#providers-using-mds)
 - [Software Companies Using MDS](#software-companies-using-mds)

agency/README.md

@@ -84,7 +84,7 @@ A vehicle record is as follows:
 | `vehicle_id`  | String    | Vehicle Identification Number (vehicle_id) visible on vehicle                 |
 | `vehicle_type`        | Enum      | [Vehicle Type][vehicle-types]           |
 | `propulsion_types`  | Enum[]    | Array of [Propulsion Type][propulsion-types]; allows multiple values          |
-| `vehicle_attributes`        | Array of [vehicle attributes](/modes/#vehicle-attributes)   | Vehicle attributes appropriate for the current mode |
+| `vehicle_attributes`        | Array of [vehicle attributes](/modes/#vehicle-attributes)   | Vehicle attributes appropriate for the current [mode][modes] |
 | `state`       | Enum      | Current vehicle state. See [Vehicle State][vehicle-states]                    |
 | `prev_events`  | Enum[]      | Last [Vehicle Event][vehicle-events]                                           |
 | `updated`     | [timestamp][ts] | Date of last event update                                                     |
@@ -111,7 +111,7 @@ Body Params:
 | `vehicle_type`       | Enum    | Required          | [Vehicle Type][vehicle-types]                                        |
 | `mode`       | Enum    | Required          | [Mobility Mode][modes]                                        |
 | `propulsion_types` | Enum[]  | Required          | Array of [Propulsion Type][propulsion-types]; allows multiple values |
-| `vehicle_attributes`        | Array of [vehicle attributes](/modes/#vehicle-attributes)   | Vehicle attributes appropriate for the current mode |
+| `vehicle_attributes` | Conditionally Required | Array of [vehicle attributes](/modes/#vehicle-attributes)   | Vehicle attributes appropriate for the current [mode][modes] |
 
 201 Success Response:
 
@@ -143,7 +143,7 @@ Body Params:
 
 | Field        | Type    | Required/Optional | Field Description                                                    |
 | ------------ | ------- | ----------------- | -------------------------------------------------------------------- |
-| `vehicle_id` | String  | Required          | Vehicle Identification Number (vehicle_id) visible on vehicle               |
+| `vehicle_id` | String  | Required          | License Plate (if present) or VIN visible on a vehicle               |
 
 200 Success Response:
 
@@ -164,7 +164,7 @@ _No content returned if no vehicle matching `device_id` is found._
 
 ## Vehicle - Event
 
-The vehicle `/event` endpoint allows the Provider to control the state of the vehicle including deregister a vehicle from the fleet.
+The vehicle `/event` endpoint allows the Provider to control the state of the vehicle.
 
 Endpoint: `/vehicles/{device_id}/event`
 Method: `POST`
@@ -177,14 +177,14 @@ Path Params:
 
 Body Params:
 
-| Field           | Type                          | Required/Optional | Field Description |
-| -----------     | ----------------------------- | -------- | -------------------------------------------------------------------------------- |
-| `vehicle_state` | Enum                          | Required | see [Vehicle States][vehicle-states] |
-| `event_types`   | Enum[]                        | Required | see [Vehicle Events][vehicle-events] |
-| `timestamp`     | [timestamp][ts]               | Required | Date of last event update |
-| `telemetry`     | [Telemetry](#telemetry-data)  | Required | Single point of telemetry. |
+| Field           | Type                         | Required/Optional      | Field Description                                                                                          |
+|-----------------|------------------------------|------------------------|------------------------------------------------------------------------------------------------------------|
+| `vehicle_state` | Enum                         | Required               | see [Vehicle States][vehicle-states]                                                                       |
+| `event_types`   | Enum[]                       | Required               | see [Vehicle Events][vehicle-events]       |
+| `timestamp`     | [timestamp][ts]              | Required               | Date of last event update                                                                                  |
+| `telemetry`     | [Telemetry](#telemetry-data) | Required               | Single point of telemetry                                                                                  |
 | `event_geographies`  | UUID[] | Optional        | **[Beta feature](/general-information.md#beta-features):** *Yes (as of 1.1.0)*. Array of Geography UUIDs consisting of every Geography that contains the location of the event. See [Geography Driven Events][geography-driven-events]. Required if `telemetry` is not present. |
-| `trip_id`       | UUID                          | Optional | UUID provided by Operator to uniquely identify the trip. Required if `event_types` contains `trip_start`, `trip_end`, `trip_cancel`, `trip_enter_jurisdiction`, or `trip_leave_jurisdiction` |
+| `trip_id`       | UUID                         | Conditionally required | UUID provided by Operator to uniquely identify the trip. See `trip_id` requirements for each [mode][modes]. |
 
 201 Success Response:
 
@@ -323,6 +323,8 @@ Path Params:
 
 If `stop_id` is specified, `GET` will return an array with a single stop record, otherwise it will be a list of all stop records.
 
+[Top][toc]
+
 ## Reservation Type
 
 The reservation type enum expresses the urgency of a given reservation. This can be useful when attempting to quantify metrics around trips: for example, computing passenger wait-time. In the `on_demand` case, passenger wait-time may be quantified by the delta between the `reservation_time`, and the pick-up time; however, in the `scheduled` case, the wait time may be quantified based on the delta between the `scheduled_trip_start_time` found in the Trips payload, and the actual `trip_start_time`. 
@@ -332,6 +334,8 @@ The reservation type enum expresses the urgency of a given reservation. This can
 | `on_demand`        | The passenger requested the vehicle as soon as possible                |
 | `scheduled`        | The passenger requested the vehicle for a scheduled time in the future |
 
+[Top][toc]
+
 ## Reservation Method
 
 The reservation method enum describes the different ways in which a passenger can create their reservation.
@@ -342,6 +346,8 @@ The reservation method enum describes the different ways in which a passenger ca
 | `street_hail`        | Reservation was made by the passenger hailing the vehicle |
 | `phone_dispatch`     | Reservation was made by calling the dispatch operator     |
 
+[Top][toc]
+
 ## Fare
 
 The Fare object describes a fare for a Trip. 
@@ -354,6 +360,8 @@ The Fare object describes a fare for a Trip.
 | currency        | string                | Required          | ISO 4217 currency code                                                                  |
 | payment_methods | `string[]`            | Optional          | Breakdown of different payment methods used for a trip, e.g. cash, card, equity_program |
 
+[Top][toc]
+
 ## Trip Metadata
 
 The Trips endpoint serves two purposes: 
@@ -394,9 +402,9 @@ Payload which was POST'd
 | `bad_param`          | A validation error occurred.                      | Array of parameters with errors |
 | `missing_param`      | A required parameter is missing.                  | Array of missing parameters     |
 
-
 [Top][toc]
 
+[accessibility-options]: /general-information.md#accessibility-options
 [beta]: /general-information.md#beta-features
 [general]: /general-information.md
 [geography-driven-events]: /general-information.md#geography-driven-events
@@ -409,6 +417,6 @@ Payload which was POST'd
 [toc]: #table-of-contents
 [ts]: /general-information.md#timestamps
 [vehicle-types]: /general-information.md#vehicle-types
-[vehicle-states]: /modes#vehicle-states
-[vehicle-events]: /modes#event-types
+[vehicle-states]: /modes/vehicle_states.md
+[vehicle-events]: /modes/event_types.md
 [versioning]: /general-information.md#versioning

general-information.md

@@ -4,31 +4,33 @@ This document contains specifications that are shared between the various MDS AP
 
 ## Table of Contents
 
-* [Beta Features](#beta-features)
-* [Costs and Currencies](#costs-and-currencies)
-* [Definitions](#definitions)
-* [Devices](#devices)
-* [Geographic Data][geo]
-  * [Geographic Telemetry Data](#geographic-telemetry-data)
-  * [Stop-based Geographic Data](#stop-based-geographic-data)
-  * [Intersection Operation](#intersection-operation)
-* [Geography-Driven Events](#geography-driven-events)
-* [Optional Authentication](#optional-authentication)
-* [Propulsion Types](#propulsion-types)
-* [Responses](#responses)
-  * [Error Messages](#error-messages)
-* [Strings](#strings)
-* [Stops](#stops)
-  * [Stop Status](#stop-status)
-  * [GBFS Compatibility](#gbfs-compatibility)
-* [Timestamps](#timestamps)
-* [UUIDs](#uuids)
-* [Vehicle States](#vehicle-states)
-  * [Event Types](#event-types)
-  * [Vehicle State Events](#vehicle-state-events)
-  * [State Machine Diagram](#state-machine-diagram)
-* [Vehicle Types](#vehicle-types)
-* [Versioning](#versioning)
+- [Beta Features](#beta-features)
+- [Costs and Currencies](#costs-and-currencies)
+- [Definitions](#definitions)
+- [Devices](#devices)
+- [Geographic Data](#geographic-data)
+  - [Geographic Telemetry Data](#geographic-telemetry-data)
+  - [Stop-based Geographic Data](#stop-based-geographic-data)
+  - [Intersection Operation](#intersection-operation)
+- [Geography-Driven Events](#geography-driven-events)
+- [Optional Authentication](#optional-authentication)
+- [Responses](#responses)
+  - [Error Messages](#error-messages)
+- [Strings](#strings)
+- [Stops](#stops)
+  - [Stop Status](#stop-status)
+  - [GBFS Compatibility](#gbfs-compatibility)
+- [Timestamps](#timestamps)
+- [UUIDs](#uuids)
+- [Vehicle Characteristics](#vehicle-characteristics)
+  - [Accessibility Options](#accessibility-options)
+  - [Propulsion Types](#propulsion-types)
+  - [Vehicle Types](#vehicle-types)
+- [Vehicle States](#vehicle-states)
+  - [Event Types](#event-types)
+  - [Vehicle State Events](#vehicle-state-events)
+  - [State Machine Diagram](#state-machine-diagram)
+- [Versioning](#versioning)
 
 ## Beta Features
 
@@ -176,19 +178,6 @@ Note if implementing the beta feature [Geography Driven Events](/general-informa
 
 [Top][toc]
 
-## Propulsion Types
-
-| `propulsion`      | Description                                            |
-| ----------------- | ------------------------------------------------------ |
-| `human`           | Pedal or foot propulsion                               |
-| `electric_assist` | Provides power only alongside human propulsion         |
-| `electric`        | Contains throttle mode with a battery-powered motor    |
-| `combustion`      | Contains throttle mode with a gas engine-powered motor |
-
-A vehicle may have one or more values from the `propulsion`, depending on the number of modes of operation. For example, a scooter that can be powered by foot or by electric motor would have the `propulsion` represented by the array `['human', 'electric']`. A bicycle with pedal-assist would have the `propulsion` represented by the array `['human', 'electric_assist']` if it can also be operated as a traditional bicycle.
-
-[Top][toc]
-
 ## Responses
 
 * **200:** OK: operation successful.
@@ -316,7 +305,35 @@ See new location within [individual modes](/modes#list-of-supported-modes) in [m
 
 [Top][toc]
 
-## Vehicle Types
+## Vehicle Characteristics
+
+Properties and characteristics of vehicles and devices.
+
+[Top][toc]
+
+### Accessibility Options
+This enum represents the accessibility options available on a given vehicle, or the accessibility options utilized for a given trip. Optional and applicable only to certain [modes][modes].
+
+| `accessibility_option`  | Description                           |
+|-------------------------|---------------------------------------|
+| `wheelchair_accessible` | This vehicle is wheelchair accessible |
+
+[Top][toc]
+
+### Propulsion Types
+
+| `propulsion`      | Description                                            |
+| ----------------- | ------------------------------------------------------ |
+| `human`           | Pedal or foot propulsion                               |
+| `electric_assist` | Provides power only alongside human propulsion         |
+| `electric`        | Contains throttle mode with a battery-powered motor    |
+| `combustion`      | Contains throttle mode with a gas engine-powered motor |
+
+A vehicle may have one or more values from the `propulsion`, depending on the number of modes of operation. For example, a scooter that can be powered by foot or by electric motor would have the `propulsion` represented by the array `['human', 'electric']`. A bicycle with pedal-assist would have the `propulsion` represented by the array `['human', 'electric_assist']` if it can also be operated as a traditional bicycle.
+
+[Top][toc]
+
+### Vehicle Types
 
 The list of allowed `vehicle_type` values in MDS. Aligning with [GBFS vehicle types form factors](https://github.com/NABSA/gbfs/blob/master/gbfs.md#vehicle_typesjson-added-in-v21-rc).
 
@@ -364,6 +381,7 @@ If an unsupported or invalid version is requested, the API must respond with a s
 [geo]: #geographic-data
 [geojson-feature]: https://tools.ietf.org/html/rfc7946#section-3.2
 [geojson-point]: https://tools.ietf.org/html/rfc7946#section-3.1.2
+[modes]: /modes/README.md
 [policy]: /policy/README.md
 [provider]: /provider/README.md
 [st-intersects]: https://postgis.net/docs/ST_Intersects.html

modes/README.md

@@ -13,13 +13,13 @@ All MDS APIs should be mode-agnostic.
 
 ## Modes
 
-The `mode` value is used to specify the applicable mobility category in MDS Policy, MDS Jurisdictions, and other parts of the spec. The only currently supported mode is `micromobility`, but others such as taxi and delivery robots are planned.
+The `mode` value is used to specify the applicable mobility category in MDS Policy, MDS Jurisdictions, and many other parts of MDS. 
 
 A `mode` is defined as: A distinct regulatory framework for a type of mobility service, as distinguished by a combination of a) the data needed by regulators, b) the operating rules under which the service functions, c) the legal authority under which it is regulated, and the d) design and operating model of the service itself.
 
-There will be some gray areas and some differences from one jurisdiction to another (e.g. taxis and ridehail may be regulated under the same rules on one place, but different rules in another). We do not need to pre-define a complete taxonomy of modes, or identify every modal boundary upfront, but would instead add modes on an as-needed basis, maintaining as much consistency of naming as possible.
+There will be some gray areas and some differences from one jurisdiction to another (e.g. taxis and ridehail may be regulated under the same rules on one place, but different rules in another). MDS will not pre-define a complete taxonomy of modes, or identify every modal boundary upfront, but will instead add modes on an as-needed basis, maintaining as much consistency of naming as possible.
 
-We should err on the side of treating highly similar services as one mode, but should consult with our members and community to inform each decision about how to integrate a new service and whether it needs to be designated as its own mode. This is a policy implementation question as much as it is a technical one.
+We err on the side of treating highly similar services as one mode, but consult with our members and community to inform each decision about how to integrate a new service and whether it needs to be designated as its own mode. This is a policy implementation question as much as it is a technical one.
 
 Each mode defined in MDS shall include key descriptive information, such as journey type (e.g. point-to-point, multi-segment, multi-segment overlapping), primary purpose (goods, single passenger, multi-passenger, etc.), and a description of the service being offered that aligns with terminology commonly understood by the public (e.g. “e-scooter” or “ridehailing”). 
 

modes/event_types.md

@@ -14,15 +14,18 @@ As with all MDS definitions, they should be described in a way that maximizes th
 | `comms_restored`      | Communications restored |
 | `compliance_pick_up`  | Pick up for compliance (rule violation) |
 | `decommissioned`      | Decommissioned |
+| `driver_cancellation` | Driver cancelled a trip |
 | `located`             | Located (opposite of Missing) |
 | `maintenance`         | General maintenance |
 | `maintenance_pick_up` | Pick up for maintenance |
 | `missing`             | Missing |
 | `off_hours`           | Off hours - end of service |
 | `on_hours`            | On hours - start of service |
+| `passenger_cancellation` | Passenger cancelled a trip |
+| `provider_cancellation` | Provider cancelled a trip |
 | `provider_drop_off`   | Drop off by the provider |
 | `rebalance_pick_up`   | Pick up for rebalancing |
-| `reservation_cancel`  | Reservation canceled |
+| `reservation_cancel`  | Reservation cancelled |
 | `reservation_start`   | Reservation started |
 | `system_resume`       | Resume system operations, e.g. start of day |
 | `system_suspend`      | Suspend system operations, e.g. end of day |

modes/micromobility.md

@@ -18,13 +18,21 @@ See the [modes overview](/modes) for how the mode specific information below app
 
 Some fields used across MDS APIs are defined in more detail within each mode.
 
+### Mode ID
+
+The short name identifier for Micromobility used across MDS is `micromobility`.
+
 ### Journey ID
 
 The `journey_id` field is not used with the micromobility mode.
 
+### Trip ID Requirements
+
+Required in events if `event_types` contains `trip_start`, `trip_end`, `trip_cancel`, `trip_enter_jurisdiction`, or `trip_leave_jurisdiction`.
+
 ### Trip Type
 
-The `trip_type` field may have one of the following values:
+The `trip_type` field **may** have one of the following values:
 
 - `rider`: a single rider is taking a trip
 
@@ -37,9 +45,24 @@ The `trip_attributes` array is not used with the micromobility mode.
 The `vehicle_attributes` array may have the following key value pairs:
 
 - `year` (integer)
-- `manufacturer` (string)
+- `make` (string)
 - `model` (string)
 
+### Propulsion Types
+
+#### Valid for vehicle_types: bicycle, scooter, moped, other
+
+| `propulsion`      |
+| ----------------- |
+| `human`           |
+| `electric_assist` |
+| `electric`        |
+| `combustion`      |
+
+### Accessibility Options
+
+Accessibility options are not used in micromobility.
+
 [Top][toc]
 
 ## Vehicle States
@@ -155,7 +178,7 @@ Vehicles can enter the `unknown` state to and from any other state with the foll
 ### 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/1Ar2-ju8YlddSsTATvQw4YjsSa5108XtidtnJNk-UAfA/edit) for the source file.
-![MDS State Machine Diagram](/modes/MDS-micromobility-state-machine-diagram.svg)
+![MDS State Machine Diagram](/modes/micromobility-state-machine-diagram.svg)
 
 [Top][toc]