Merge pull request #4 from openmobilityfoundation/dev

Dev merge
openmobilityfoundation · Jun 26, 2020 · 48bd397 · 48bd397
2 parents 440637b + c82637c
commit 48bd397
Show file tree

Hide file tree

Showing 8 changed files with 78 additions and 43 deletions.
diff --git a/MDS-state-machine-diagram.svg b/MDS-state-machine-diagram.svg
diff --git a/README.md b/README.md
@@ -30,11 +30,10 @@ You can also get involved in development by joining an OMF working group. The wo
 Working Group | Mailing List | Description
 --- | --- | ---
 Provider Services | [mds-provider-services](https://groups.google.com/a/groups.openmobilityfoundation.org/forum/#!forum/mds-provider-services) | Manages the [`provider`][provider] API within MDS.
-City Services | [mds-city-services](https://groups.google.com/a/groups.openmobilityfoundation.org/forum/#!forum/mds-city-services) | Manages the [`agency`][agency] and [`policy`][policy] APIs within MDS, as well as the [`mds-core`](https://github.com/openmobilityfoundation/mds-core) reference implementation.
+City Services | [mds-city-services](https://groups.google.com/a/groups.openmobilityfoundation.org/forum/#!forum/mds-city-services) | Manages the [`agency`][agency] and [`policy`][policy] APIs within MDS, as well as the [`mds-core`](https://github.com/openmobilityfoundation/mds-core) and [`mds-compliance-mobile`](https://github.com/openmobilityfoundation/mds-compliance-mobile) reference implementations.
 
 You can view info about past releases and planning calls in the [wiki](https://github.com/openmobilityfoundation/mobility-data-specification/wiki).
 
-
 For questions about MDS please contact [info@openmobilityfoundation.org](mailto:info@openmobilityfoundation.org). Media inquiries to [media@openmobilityfoundation.org](mailto:media@openmobilityfoundation.org)
 
 ## Versions
@@ -49,15 +48,38 @@ Information about the latest release and all releases are below. Please note, yo
 
 ## Cities Using MDS
 
-More than 80 cities and public agencies around the world use MDS, and it has been implemented by most major mobility providers. Below are links to some specific agency programs/policies:
-
-* Los Angeles: The rules and guidelines for the Los Angeles Dockless Bikeshare Systems / Pilot Program can be found on [Council Clerk Connect](https://cityclerk.lacity.org/lacityclerkconnect/index.cfm?fa=ccfi.viewrecord&cfnumber=17-1125) along with supporting info on [ladot.io](https://ladot.io/programs/dockless/).
-* Santa Monica: The rules and guidelines for the Santa Monica Shared Mobility Pilot Program can be found at https://www.smgov.net/sharedmobility.
-* Austin: The rules and guidelines for Austin's Micromobility Program can be found at https://austintexas.gov/micromobility.
-* Ulm: A draft of the guidelines can be found at [the city's GitHub presence](https://github.com/stadtulm/mds-zonen).
+More than 90 cities and public agencies around the world use MDS, and it has been implemented by most major mobility providers. Below are links to some of the specific agency programs/policies:
+
+* **Arlington, VA**: [Shared Micro-Mobility Devices](https://transportation.arlingtonva.us/scooters-and-dockless-bikeshare/) page and [permit application](https://arlingtonva.s3.amazonaws.com/wp-content/uploads/sites/19/2019/12/Micro-Mobility_Permit_Final_191203.pdf).
+* **Atlanta, GA**: [Administrative Regulations
+for Shareable Dockless Mobility Device Permit Holders](https://www.atlantaga.gov/home/showdocument?id=44650) from [Department of City Planning](https://www.atlantaga.gov/government/departments/city-planning).
+* **Austin, TX**: The rules and guidelines for Austin's Micromobility Program can be found on Austin's [Shared Mobility Program](https://austintexas.gov/department/shared-mobility-services) website.
+* **Calgary, Canada**: Programs for a [Dockless Bike Share Pilot](https://www.calgary.ca/transportation/tp/cycling/cycling-strategy/bike-share-system.html?redirect=/bikeshare) and a [hared electric scooter pilot](https://www.calgary.ca/transportation/tp/cycling/cycling-strategy/shared-electric-scooter-pilot.html) that require [MDS in the application](https://www.calgary.ca/content/dam/www/transportation/tp/documents/cycling/cycling_strategy/framework-for-dockless-bike-share-permit-phase-2.pdf) and programs.
+* **Chicago, IL**: [E-Scooter Share Pilot Program](https://www.chicago.gov/city/en/depts/cdot/supp_info/escooter-share-pilot-project.html) information.
+* **Denver, CO**: [Dockless Mobility Vehicle Pilot Permit Program](https://www.denvergov.org/content/denvergov/en/transportation-infrastructure/programs-services/dockless-mobility.html) in the [Department of Transportation & Infrastructure](https://www.denvergov.org/content/denvergov/en/transportation-infrastructure.html).
+* **Detroit, MI**: See the Public Works [Scooter Page[(https://detroitmi.gov/departments/department-public-works/complete-streets/scooters) and the [Dockless Scooters Interpretation](http://www.detroitmi.gov/Portals/0/docs/DPW/Dockless%20Scooters%20Memo%20of%20Interpretation_Final%20Version%207%2020%2018_1.pdf)
+* **Kansas City, MO**: [Scooter and e-Bike Pilot Program](https://www.kcmo.gov/programs-initiatives/scooters-and-ebikes) document.
+* **Kelowna, Canada**: [Bikeshare Permit Program](https://www.kelowna.ca/roads-transportation/active-transportation/cycling/bikeshare-permit-program) and operator application.
+* **Los Angeles, CA**: The rules and guidelines for the Los Angeles Dockless Bikeshare Systems / Pilot Program can be found on [Council Clerk Connect](https://cityclerk.lacity.org/lacityclerkconnect/index.cfm?fa=ccfi.viewrecord&cfnumber=17-1125) along with supporting info on [ladot.io](https://ladot.lacity.org/projects/transportation-services/shared-mobility/micromobility).
+* **Louisville, KY**: City [Dockless Vehicle Policy](https://data.louisvilleky.gov/dataset/dockless-vehicles/resource/541f050d-b868-428e-9601-c48a04eba17c) and [Public Works Guideance](https://louisvilleky.gov/government/public-works/dockless-find-and-ride-vehicles).
+* **Nashville, TN**: [Mobility Devices Bill](https://www.nashville.gov/Metro-Clerk/Legislative/Ordinances/Details/7d2cf076-b12c-4645-a118-b530577c5ee8/2015-2019/BL2018-1202.aspx).
+* **Miami, FL**: [Miami Scooter Program](https://www.miamigov.com/Services/Transportation/Miami-Scooter-Pilot-Program?BestBetMatch=scooters|d13b95b2-5146-4b00-9e3e-a80c73739a64|4f05f368-ecaa-4a93-b749-7ad6c4867c1f|en-US).
+* **Minneapolis, MN**: [Motorized Foot Scooters](http://www.minneapolismn.gov/www/groups/public/@publicworks/documents/webcontent/wcmsp-218311.pdf) and [Mobility Data Methodology and Analysis](http://www.minneapolismn.gov/publicworks/trans/WCMSP-212816).
+* **Philadelphia, PA**: [Dockless Bike Share Pilot](http://www.phillyotis.com/portfolio-item/dockless-bike-share-pilot/) and regulations.
+* **Pittsburgh, PA**: The city's [Bike+ Master Plan](https://pittsburghpa.gov/domi/bikeplan) includes multiple modes.
+* **Portland, OR**: [Administrative Rule and data sharing](https://www.portlandoregon.gov/citycode/article/690212) document from [PBOT](https://www.portlandoregon.gov/transportation/).
+* **San Diego, CA**: [Shared Mobility Device Operator Regulations](https://www.sandiego.gov/bicycling/bicycle-and-scooter-sharing/company-contacts) and [Ordinance with Data Sharing Provisions](https://docs.sandiego.gov/council_reso_ordinance/rao2019/O-21070.pdf).
+* **San Francisco, CA**: [SFMTA Policy Document](https://www.sfmta.com/sites/default/files/reports-and-documents/2018/05/powered_scooter_share_program_permit_application.pdf) and [Guideance Page](https://www.sfmta.com/projects/powered-scooter-share-permit-and-pilot-program). 
+* **San Jose, CA**: [Shared Micro-mobility Permit Administrative Regulations](https://www.sanjoseca.gov/home/showdocument?id=38091).
+* **Santa Monica, CA**: The rules and guidelines are on the Santa Monica [Shared Mobility Pilot Program page](https://www.smgov.net/Departments/PCD/Transportation/Shared-Mobility-Services/).
+* **Seattle, WA**: SDOT's [Free-floating Bike Share Permitting](https://www.seattle.gov/transportation/projects-and-programs/programs/bike-program/bike-share#permityearpermit2.1) program and [permit requirements](https://www.seattle.gov/Documents/Departments/SDOT/BikeProgram/Seattle_Bike_Share_Permit_Requirements_v2.1_20181219.pdf).
+* **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)_
 
+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.
+
 ## Use Cases
 Some examples of how cities are using MDS in practice:
 
@@ -77,7 +99,7 @@ Some examples of how cities are using MDS in practice:
 
 ### Open Mobility Foundation
 * [`mds-core`](https://github.com/openmobilityfoundation/mds-core) - A reference implementation of an MDS Agency Server, built using PostgresQL, TypeScript, NodeJS.
-* [`mds-compliance-mobile`](`https://github.com/openmobilityfoundation/mds-compliance-mobile`) - A mobile app for performing in-the-field data validation and compliance monitoring.
+* [`mds-compliance-mobile`](https://github.com/openmobilityfoundation/mds-compliance-mobile) - A mobile app for performing in-the-field data validation and compliance monitoring.
 
 ### City of Los Angeles
 * [`mds-dev`](https://github.com/cityoflosangeles/mds-dev) - Code to do cap checking, fake data generation and more with provider data.

diff --git a/agency/README.md b/agency/README.md
@@ -76,7 +76,7 @@ A vehicle record is as follows:
 | `model`       | String    | Vehicle Model                                                                 |
 | `state`       | Enum      | Current vehicle state. See [Vehicle State][vehicle-states]                    |
 | `prev_event`  | Enum      | Last [Vehicle Event][vehicle-event]                                           |
-| `updated`     | Timestamp | Date of last event update                                                     |
+| `updated`     | [timestamp][ts] | Date of last event update                                                     |
 
 404 Failure Response:
 
@@ -166,7 +166,7 @@ Body Params:
 | -----------     | ----------------------------- | -------- | -------------------------------------------------------------------------------- |
 | `vehicle_state` | Enum                          | Required | see [Vehicle States][vehicle-states] |
 | `event_types`   | Enum[]                        | Required | see [Vehicle Events][vehicle-events] |
-| `timestamp`     | Timestamp                     | Required | Date of last event update |
+| `timestamp`     | [timestamp][ts]                     | Required | Date of last event update |
 | `telemetry`     | [Telemetry](#telemetry-data)  | Required | Single point of telemetry |
 | `trip_id`       | UUID                          | Optional | UUID provided by Operator to uniquely identify the trip. Required for `trip_start`, `trip_end`, `trip_enter`, and `trip_leave` event types |
 
@@ -197,11 +197,12 @@ Body Params:
 | ------------- | ------------------------------ | ----------------- | -------------------------------------------------------------------------------------- |
 | `data`        | [Telemetry](#telemetry-data)[] | Required          | Array of telemetry for one or more vehicles.                                           |
 
-201 Success Response:
+200 Success Response:
 
-| Field     | Type                           | Field Description                                                                                       |
-| --------- | ------------------------------ | ------------------------------------------------------------------------------------------------------- |
-| `result`  | String                         | Responds with number of successfully written telemetry data points and total number of provided points. |
+| Field      | Type                           | Field Description                                                                                       |
+| ---------- | ------------------------------ | ------------------------------------------------------------------------------------------------------- |
+| `success`  | Integer                        | Number of successfully written telemetry data points.                                                   |
+| `total`    | Integer                        | Ttotal number of provided points.                                                                       |
 | `failures` | [Telemetry](#telemetry-data)[] | Array of failed telemetry for zero or more vehicles (empty if all successful).                          |
 
 400 Failure Response:
@@ -219,7 +220,7 @@ A standard point of vehicle telemetry. References to latitude and longitude impl
 | Field          | Type           | Required/Optional     | Field Description                                            |
 | -------------- | -------------- | --------------------- | ------------------------------------------------------------ |
 | `device_id`    | UUID           | Required              | ID used in [Register](#vehicle-register)                     |
-| `timestamp`    | Timestamp      | Required              | Date/time that event occurred. Based on GPS or GNSS clock            |
+| `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                                     |
 | `gps.lng`      | Double         | Required              | Longitude of the location                                    |
@@ -233,13 +234,14 @@ A standard point of vehicle telemetry. References to latitude and longitude impl
 
 [Top][toc]
 
-[toc]: #table-of-contents
 [general]: /general-information.md
-[versioning]: /general-information.md#versioning
-[responses]: /general-information.md#responses
 [error-messages]: /general-information.md#error-messages
+[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
+[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
-[propulsion-types]: /general-information.md#propulsion-types
-[hdop]: https://support.esri.com/en/other-resources/gis-dictionary/term/358112bd-b61c-4081-9679-4fca9e3eb926
+[versioning]: /general-information.md#versioning
diff --git a/agency/images/MDS_agency_event_state.png b/agency/images/MDS_agency_event_state.png
diff --git a/general-information.md b/general-information.md
@@ -6,6 +6,7 @@ This document contains specifications that are shared between the various MDS AP
 
 * [Beta Features](#beta-features)
 * [Costs and Currencies](#costs-and-currencies)
+* [Definitions](#definitions)
 * [Devices](#devices)
 * [Propulsion Types](#propulsion-types)
 * [Responses](#responses)
@@ -38,6 +39,17 @@ If the currency field is null, USD cents is implied.
 
 [Top][toc]
 
+## Definitions
+
+Defining terminology and abbreviations used throughout MDS.
+
+- **API** - Application Programming Interface - A function or set of functions that allow one software application to access or communicate with features of a different software application or service. 
+- **API Endpoint** - A point at which an API connects with a software application or service.
+- **DOT** - Department of Transportation, usually a city-run agency.
+- **PROW** - Public Right of Way - the physical infrastructure reserved for transportation purposes, examples include sidewalks, curbs, bike lanes, transit lanes and stations, traffic lanes and signals, and public parking.
+
+[Top][toc]
+
 ## Devices
 
 MDS defines the *device* as the unit that transmits GPS or GNSS signals for a particular vehicle. A given device must have a UUID (`device_id` below) that is unique within the Provider's fleet.
@@ -168,11 +180,9 @@ Note that to handle out-of-order events, the validity of the prior-state shall n
 | `available`, `reserved`, `on_trip`, `non_operational`, `elsewhere` | `unknown`     | `missing`            | The vehicle is not at its last reported GPS location, or that location is wildly in error |
 | `available`, `reserved`, `on_trip`, `non_operational`, `elsewhere` | `unknown`     | `comms_lost`       | The vehicle is unable to transmit its GPS location or other status information |
 
-NOTES:
-
-Should we try to handle "unlicensed movements"?
+The *State Machine Diagram* shows how the `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](/MDS-state-machine-diagram.svg)
 
-What's the best way to return from `unknown`?
 
 [Top][toc]
 

diff --git a/policy/README.md b/policy/README.md
@@ -277,7 +277,7 @@ The internal mechanics of ordering are up to the Policy editing and hosting soft
 [iana]: https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml
 [muni-boundary]: ../provider/README.md#municipality-boundary
 [propulsion-types]: /general-information.md#propulsion-types
-[timestamps]: /general-information.md#timestamps
+[ts]: /general-information.md#timestamps
 [toc]: #table-of-contents
 [vehicle-events]: /general-information.md#vehicle-state-events
 [vehicle-states]: /general-information.md#vehicle-states

diff --git a/policy/examples.md b/policy/examples.md
@@ -175,22 +175,6 @@ This Policy sets a 15 MPH speed limit in greater LA, and a 10 MPH speed limit in
   "published_date": 1552678594428,
   "prev_policies": null,
   "rules": [{
-      "name": "Greater LA",
-      "rule_id": "529b6cd7-0e0d-4439-babf-c5908a664ecf",
-      "rule_type": "speed",
-      "rule_units": "mph",
-      "geographies": [
-        "b4bcc213-4888-48ce-a33d-4dd6c3384bda"
-      ],
-      "statuses": {
-        "trip": []
-      },
-      "vehicle_types": [
-        "bicycle",
-        "scooter"
-      ],
-      "maximum": 15
-  }, {
       "name": "Venice Beach on weekend afternoons",
       "rule_id": "d4c0f42f-3f79-4eb4-850a-430b9701d5cf",
       "rule_type": "speed",
@@ -216,6 +200,22 @@ This Policy sets a 15 MPH speed limit in greater LA, and a 10 MPH speed limit in
           "en-US": "Remember to stay under 10 MPH on Venice Beach on weekends!",
           "es-US": "¡Recuerda permanecer menos de 10 millas por hora en Venice Beach los fines de semana!"
       }
+  }, {
+      "name": "Greater LA",
+      "rule_id": "529b6cd7-0e0d-4439-babf-c5908a664ecf",
+      "rule_type": "speed",
+      "rule_units": "mph",
+      "geographies": [
+        "b4bcc213-4888-48ce-a33d-4dd6c3384bda"
+      ],
+      "statuses": {
+        "trip": []
+      },
+      "vehicle_types": [
+        "bicycle",
+        "scooter"
+      ],
+      "maximum": 15
   }]
 }
 ```

diff --git a/provider/README.md b/provider/README.md
@@ -310,7 +310,7 @@ The schema and datatypes are the same as those defined for [`/status_changes`][s
 
 **Endpoint:** `/events`  
 **Method:** `GET`  
-**[Beta feature][beta]:** Yes (as of 0.4.0)  
+**[Beta feature][beta]:** No (as of 1.0.0)  
 **Schema:** [`events` schema][events-schema]  
 **`data` Payload:** `{ "status_changes": [] }`, an array of objects with the same structure as in [`/status_changes`][status]