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

@@ -1,34 +1,36 @@
 # Mobility Data Specification: **General information**
 
-This document contains specifications that are shared between the various MDS APIs such as [`agency`][agency], [`policy`][policy], [`provider`][provider], etc.
+This document contains specifications that are shared between the various MDS [APIs and endpoints](/README.md#endpoints).
 
 ## 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.
@@ -251,7 +240,6 @@ Stops describe vehicle trip start and end locations in a pre-designated physical
 | devices                | UUID[]                                                | Optional | List of device_ids for vehicles which are currently at this stop |
 | image_url              | URL                                                   | Optional | Link to an image, photo, or diagram of the stop. Could be used by providers to help riders find or use the stop. |
 
-
 ### Stop Status
 
 **Stop Status** returns information about the current status of a **[Stop](#stops)**.
@@ -272,6 +260,8 @@ Example of the **Stop Status** object with properties listed:
 }
 ```
 
+[Top][toc]
+
 ### GBFS Compatibility
 
 Some of the fields in the `Stops` definition are using notions which are currently not in MDS, such as `rental_methods`. These fields are included for compatibility with GBFS.
@@ -294,13 +284,13 @@ MDS uses Version 1 UUIDs by default. Version 4 UUIDs may be used where noted.
 
 ## Vehicle States
 
-See new location in [vehicle states](/modes/vehicle_states.md) within [modes](/modes#vehicle-states).
+See new location within [vehicle states](/modes/vehicle_states.md) in [modes](/modes#vehicle-states).
 
 [Top][toc]
 
 ### Event Types
 
-See new location in [event types](/modes/event_types.md) within [modes](/modes#event-types).
+See new location within [event types](/modes/event_types.md) in [modes](/modes#event-types).
 
 [Top][toc]
 
@@ -316,7 +306,32 @@ 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
+
+See new location within [individual modes](/modes#list-of-supported-modes) in [modes](/modes#accessibility-options).
+
+[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 +379,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

@@ -6,20 +6,20 @@ All MDS APIs should be mode-agnostic.
 
 ## Table of Contents
 
-* [Modes](#modes)
-* [List of Supported Modes](#list-of-supported-modes)
-* [Mode Attributes](#mode-attributes)
-* [Unique Mode Properties](#unique-mode-properties)
+- [Modes](#modes)
+- [List of Supported Modes](#list-of-supported-modes)
+- [Mode Attributes](#mode-attributes)
+- [Unique Mode Properties](#unique-mode-properties)
 
 ## 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”). 
 
@@ -62,6 +62,10 @@ The `trip_attributes` array allows additional mode-specific information about th
 
 The `vehicle_attributes` array returns a list of JSON-formatted key/value pairs which correspond to the allowed attributes and values for the operative mode. For each mode, the allowed attributes and corresponding values are defined in the [mode definition](#list-of-supported-modes).
 
+### Accessibility Options
+
+The `accessibility_options` array returns a list of JSON-formatted key/value pairs which correspond to the allowed accessibility attributes and values for the operative mode. For each mode, the allowed attributes and corresponding values are defined in the [mode definition](#list-of-supported-modes).
+
 [Top][toc]
 
 ## Unique Mode Properties

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 |