Skip to content

Commit

Permalink
Merge pull request #763 from openmobilityfoundation/feature-modes-pas…
Browse files Browse the repository at this point in the history 
…senger-services

Feature: modes - passenger services. Merging back to main modes feature branch to allow consistent work on other modes.
  • Loading branch information
@schnuerle
schnuerle authored Sep 9, 2022
2 parents c219154 + 4920f72 commit d72659d
Show file tree
Hide file tree
Showing 13 changed files with 635 additions and 139 deletions.
2 changes: 1 addition & 1 deletion README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
36 changes: 22 additions & 14 deletions agency/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand All @@ -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:

Expand Down Expand Up @@ -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:

Expand All @@ -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`
Expand All @@ -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:

Expand Down Expand Up @@ -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`.
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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:
Expand Down Expand Up @@ -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
Expand All @@ -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
102 changes: 59 additions & 43 deletions general-information.md
View file
Original file line number Diff line number Diff line change
@@ -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

Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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)**.
Expand All @@ -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.
Expand All @@ -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]

Expand All @@ -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).

Expand Down Expand Up @@ -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
Expand Down
18 changes: 11 additions & 7 deletions modes/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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”).

Expand Down Expand Up @@ -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
Expand Down
5 changes: 4 additions & 1 deletion modes/event_types.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down
0 ...S-micromobility-state-machine-diagram.svg → ...s/micromobility-state-machine-diagram.svg
View file
File renamed without changes
Loading

0 comments on commit d72659d

Please sign in to comment.