Merge pull request #7 from openmobilityfoundation/dev

update Dev

Author: schnuerle

.github/PULL_REQUEST_TEMPLATE/default.md

@@ -9,7 +9,11 @@ title: <Insert Title>
 
 Thank you for your contribution!
 
-*For most Pull Requests, the target branch should be [**`dev`**](https://github.com/openmobilityfoundation/mobility-data-specification/tree/dev). Please ensure you are targeting **`dev`** to avoid complications and help make the Review process as smooth as possible.*
+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.
 
 ## Explain pull request
 

README.md

@@ -76,7 +76,7 @@ for Shareable Dockless Mobility Device Permit Holders](https://www.atlantaga.gov
 * **Ulm, Germany**: A draft of the guidelines can be found at [the city's GitHub presence](https://github.com/stadtulm/mds-zonen).
 * **Washington, DC**: [Dockless Vehicle Permits](https://ddot.dc.gov/page/dockless-vehicle-permits-district), [terms and conditions](https://ddot.dc.gov/sites/default/files/dc/sites/ddot/2019.11.6%20Shared%20dockless%202020%20Terms%20and%20Conditions%20scooter.pdf), [data reporting standards](https://ddot.dc.gov/sites/default/files/dc/sites/ddot/2019.11.6%20Dockless%20Permit%20TC%20Attatchments.pdf),  and [FAQ](https://docs.google.com/document/d/1G2ddANcXl3lShCZInV3uX2NTBfRRu4Fm-tiaCi203QM/).
 
-* _[add your City here by opening a pull request](https://github.com/openmobilityfoundation/mobility-data-specification/compare)_
+* _add a city here by [opening a pull request](https://github.com/openmobilityfoundation/mobility-data-specification/compare/dev...dev) or [making an issue](https://github.com/openmobilityfoundation/mobility-data-specification/issues/new?assignees=&labels=&template=feature-request---proposal.md&title=)_.
 
 Other cities include Baltimore, Bellevue, Charlotte, Oakland, and Seattle, via the [NACTO Guidelines for Regulating Shared Micromobility](https://nacto.org/wp-content/uploads/2019/09/NACTO_Shared_Micromobility_Guidelines_Web.pdf), page 48.
 

agency/README.md

@@ -2,38 +2,46 @@
 
 This specification contains a collection of RESTful APIs used to specify the digital relationship between *mobility as a service* Providers and the Agencies that regulate them.
 
-* Date: 19 Sep 2019
-* Version: BETA
-
 ## Table of Contents
 
 * [General Information](#general-information)
+  * [Versioning](#versioning)
+  * [Responses and Error Messages](#responses-and-error-messages)
+  * [Authorization](#authorization)
 * [Vehicles](#vehicles)
-* [Vehicle Registration](#vehicle---register)
-* [Vehicle Update](#vehicle---update)
-* [Vehicle Events](#vehicle---event)
-* [Vehicles Telemetry](#vehicles---telemetry)
+* [Vehicle - Register](#vehicle---register)
+* [Vehicle - Update](#vehicle---update)
+* [Vehicle - Events](#vehicle---event)
+* [Vehicle - Telemetry](#vehicle---telemetry)
 * [Telemetry Data](#telemetry-data)
 * [Stops](#stops)
 
 ## General information
 
 This specification uses data types including timestamps, UUIDs, and vehicle state definitions as described in the MDS [General Information][general] document.
 
+[Top][toc]
+
 ### Versioning
 
 `agency` APIs must handle requests for specific versions of the specification from clients.
 
 Versioning must be implemented as specified in the [Versioning section][versioning].
 
+[Top][toc]
+
 ### Responses and Error Messages
 
 See the [Responses][responses] and [Error Messages][error-messages] sections.
 
+[Top][toc]
+
 ### Authorization
 
 When making requests, the Agency API expects `provider_id` to be part of the claims in a [JWT](https://jwt.io/) `access_token` in the `Authorization` header, in the form `Authorization: Bearer <access_token>`. The token issuance, expiration and revocation policies are at the discretion of the Agency.
 
+[Top][toc]
+
 ## Vehicles
 
 The `/vehicles` endpoint returns the specified vehicle (if a device_id is provided) or a list of known vehicles. Providers can only retrieve data for vehicles in their registered fleet.
@@ -49,7 +57,7 @@ Path Params:
 
 200 Success Response:
 
-If `device_id` is specified, `GET` will return a single vehicle record, otherwise it will be a list of vehicle records with pagination details per the [JSON API](https://jsonapi.org/format/#fetching-pagination) spec:
+If `device_id` is specified, `GET` will return an array with a single vehicle record, otherwise it will be a list of vehicle records with pagination details per the [JSON API](https://jsonapi.org/format/#fetching-pagination) spec:
 
 ```json
 {
@@ -83,7 +91,9 @@ A vehicle record is as follows:
 
 _No content returned on vehicle not found._
 
-## Vehicle Registration
+[Top][toc]
+
+## Vehicle - Register
 
 The `/vehicles` registration endpoint is used to register a vehicle for use in the Agency jurisdiction.
 
@@ -120,6 +130,8 @@ _No content returned on success._
 | -------------------- | ------------------------------------------------- | ------------------------------- |
 | `already_registered` | A vehicle with `device_id` is already registered  |                                 |
 
+[Top][toc]
+
 ## Vehicle - Update
 
 The `/vehicles` update endpoint is used to update some mutable aspect of a vehicle. For now, only `vehicle_id`.
@@ -148,6 +160,8 @@ _No content returned on success._
 
 _No content returned if no vehicle matching `device_id` is found._
 
+[Top][toc]
+
 ## Vehicle - Event
 
 The vehicle `/event` endpoint allows the Provider to control the state of the vehicle including deregister a vehicle from the fleet.
@@ -159,7 +173,7 @@ Path Params:
 
 | Field        | Type | Required/Optional | Field Description                        |
 | ------------ | ---- | ----------------- | ---------------------------------------- |
-| `device_id`  | UUID | Required          | ID used in [Register](#vehicle-register) |
+| `device_id`  | UUID | Required          | ID used in [Register](#vehicle---register) |
 
 Body Params:
 
@@ -185,7 +199,9 @@ Body Params:
 | `missing_param`     | A required parameter is missing | Array of missing parameters     |
 | `unregistered`      | Vehicle is not registered       |                                 |
 
-## Vehicles - Telemetry
+[Top][toc]
+
+## Vehicle - Telemetry
 
 The vehicle `/telemetry` endpoint allows a Provider to send vehicle telemetry data in a batch for any number of vehicles in the fleet.
 
@@ -214,13 +230,15 @@ Body Params:
 | `invalid_data`  | None of the provided data was valid. |                                 |
 | `missing_param` | A required parameter is missing.     | Array of missing parameters     |
 
+[Top][toc]
+
 ## Telemetry Data
 
 A standard point of vehicle telemetry. References to latitude and longitude imply coordinates encoded in the [WGS 84 (EPSG:4326)](https://en.wikipedia.org/wiki/World_Geodetic_System) standard GPS or GNSS projection expressed as [Decimal Degrees](https://en.wikipedia.org/wiki/Decimal_degrees).
 
 | Field          | Type           | Required/Optional     | Field Description                                            |
 | -------------- | -------------- | --------------------- | ------------------------------------------------------------ |
-| `device_id`    | UUID           | Required              | ID used in [Register](#vehicle-register)                     |
+| `device_id`    | UUID           | Required              | ID used in [Register](#vehicle---register)                     |
 | `timestamp`    | [timestamp][ts]      | Required              | Date/time that event occurred. Based on GPS or GNSS clock            |
 | `gps`          | Object         | Required              | Telemetry position data                                      |
 | `gps.lat`      | Double         | Required              | Latitude of the location                                     |
@@ -234,15 +252,34 @@ A standard point of vehicle telemetry. References to latitude and longitude impl
 | `charge`       | Float          | Required if Applicable | Percent battery charge of vehicle, expressed between 0 and 1 |
 | `stop_id`      | UUID           | Required if Applicable | Stop that the vehicle is currently located at. Only applicable for _docked_ Micromobility. See [Stops][stops] |
 
+[Top][toc]
+
 ## Stops
 
-The `/stops` endpoint allows an agency to register Stops.
+The `/stops` endpoint allows an agency to register city-managed Stops, or a provider to register self-managed Stops.
 
 **Endpoint:** `/stops`  
 **Method:** `POST`  
 **[Beta feature][beta]:** Yes (as of 1.0.0)  
 **Request Body**: An array of [Stops][stops]
 
+201 Success Response:
+
+_No content returned on success._
+
+400 Failure Response:
+
+| `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     |
+
+409 Failure Response:
+
+| `error`              | `error_description`                               | `error_details`[]               |
+| -------------------- | ------------------------------------------------- | ------------------------------- |
+| `already_registered` | A stop with `stop_id` is already registered       |                                 |
+
 **Endpoint:** `/stops`  
 **Method:** `PUT`  
 **[Beta feature][beta]:** Yes (as of 1.0.0)  
@@ -254,12 +291,35 @@ The `/stops` endpoint allows an agency to register Stops.
 | status              | Optional          |See [Stops][stops] |
 | num_spots_disabled  | Optional          |See [Stops][stops] |
 
+200 Success Response:
+
+_No content returned on success._
+
+400 Failure Response:
+
+| `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     |
+
+404 Failure Response:
+
+_No content returned if no vehicle matching `stop_id` is found._
+
 **Endpoint:** `/stops/:stop_id`  
 **Method:** `GET`  
 **[Beta feature][beta]:** Yes (as of 1.0.0)  
-**`data` Payload:** `{ "stops": [] }`, an array of [Stops][stops]
+**Payload:** `{ "stops": [] }`, an array of [Stops][stops]
+
+Path Params:
+
+| Param        | Type | Required/Optional | Description                                 |
+| ------------ | ---- | ----------------- | ------------------------------------------- |
+| `stop_id`    | UUID | Optional          | If provided, retrieve the specified stop    |
+
+200 Success Response:
 
-In the case that a `stop_id` query parameter is specified, the `stops` array returned will only have one entry. In the case that no `stop_id` query parameter is specified, all stops will be returned.
+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]
 
@@ -269,10 +329,10 @@ In the case that a `stop_id` query parameter is specified, the `stops` array ret
 [hdop]: https://support.esri.com/en/other-resources/gis-dictionary/term/358112bd-b61c-4081-9679-4fca9e3eb926
 [propulsion-types]: /general-information.md#propulsion-types
 [responses]: /general-information.md#responses
-[stops]: /general-information#stops
+[stops]: /general-information.md#stops
 [toc]: #table-of-contents
 [ts]: /general-information.md#timestamps
 [vehicle-types]: /general-information.md#vehicle-types
 [vehicle-states]: /general-information.md#vehicle-states
 [vehicle-events]: /general-information.md#vehicle-state-events
-[versioning]: /general-information.md#versioning
+[versioning]: /general-information.md#versioning