Merge pull request #562 from openmobilityfoundation/release-1.0.0

Release 1.0.0 - Tech Council Review

Author: schnuerle

.github/PULL_REQUEST_TEMPLATE/release-final.md

@@ -0,0 +1,41 @@
+---
+name: Default
+about: Suggest changes to MDS
+title: <Insert Title>
+
+---
+
+# MDS Pull Request
+
+Thank you for your contribution!  Please review our OMF [contributing page](https://github.com/openmobilityfoundation/governance/blob/main/CONTRIBUTING.md) to understand guidelines and policies for participation, and our [Code of Conduct page](https://github.com/openmobilityfoundation/governance/blob/main/CODE_OF_CONDUCT.md).
+
+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.
+1. Have an up to date profile, per our Github [community profile](https://github.com/openmobilityfoundation/governance/blob/main/CONTRIBUTING.md#community-profile) guildance.
+
+## Explain pull request
+
+Please provide a clear and concise reason for this pull request and the impact of the change
+
+## Is this a breaking change
+
+A breaking change would require consumers or implementors of the API to modify their code for it to continue to function (ex: renaming of a required field or the change in data type of an existing field). A non-breaking change would allow existing code to continue to function (ex: addition of an optional field or the creation of a new optional endpoint).
+
+* Yes, breaking
+* No, not breaking
+* I'm not sure
+
+## Impacted Spec
+
+Which spec(s) will this pull request impact?
+
+* `agency`
+* `policy`
+* `provider`
+
+## Additional context
+
+Add any other context or screenshots about the feature request here.

.github/pull_request_template.md

@@ -1,11 +1,28 @@
 # Mobility Data Specification
 
+## Table of Contents
+
+- [About](#about)
+- [Endpoints](#endpoints)
+- [Get Involved](#get-involved)
+- [Versions](#versions)
+- [Cities Using MDS](#cities-using-mds)
+- [Providers Using MDS](#providers-using-mds)
+- [Use Cases](#use-cases)
+- [Related Projects](#related-projects)
+
+## About
+
 The Mobility Data Specification (**MDS**), a project of the [Open Mobility Foundation](http://www.openmobilityfoundation.org) (OMF), is a set of Application Programming Interfaces (APIs) focused on dockless e-scooters, bicycles, mopeds and carshare. Inspired by projects like [GTFS](https://developers.google.com/transit/gtfs/reference/) and [GBFS](https://github.com/NABSA/gbfs), the goals of MDS are to provide a standardized way for municipalities or other regulatory agencies to ingest, compare and analyze data from mobility service providers, and to give municipalities the ability to express regulation in machine-readable formats.
 
 **MDS** helps cities interact with companies who operate dockless scooters, bicycles, mopeds and carshare in the public right-of-way. MDS is a key piece of digital infrastructure that supports the effective implementation of mobility policies in cities around the world.
 
 **MDS** is an open-source project. It was originally created by the [Los Angeles Department of Transportation](http://ladot.io) (LADOT). In November 2019, stewardship of MDS and the ownership of this repository was transferred to the Open Mobility Foundation. GitHub automatically redirects any links to this repository in the `CityOfLosAngeles` organization to the `openmobilityfoundation` instead. MDS continues to be used by LADOT and many other municipalities.
 
+[Top][toc]
+
+## Endpoints
+
 **MDS** is currently comprised of three distinct components:
 
 * The [`provider`][provider] API endpoints are intended to be implemented by mobility providers and consumed by regulatory agencies. When a municipality queries information from a mobility provider, the Provider API has a historical view of operations in a standard format. It was first released in June 2018. Development takes place under the guidance of the OMF's Provider Services Working Group.
@@ -16,9 +33,14 @@ The Mobility Data Specification (**MDS**), a project of the [Open Mobility Found
 
 MDS is designed to be a modular kit-of-parts. Regulatory agencies can use the components of the API that are appropriate for their needs. An agency may choose to use only `agency`, `provider`, or `policy`. Or they may select specific elements (endpoints) from each to help them implement their goals.
 
-You can read more about the different APIs here: **[Understanding the different MDS APIs](https://github.com/openmobilityfoundation/mobility-data-specification/wiki/Understanding-MDS-APIs)**
+Many parts of the MDS definitions and APIs align across each other. In these cases, consolidated information can be found on the [General Information](/general-information.md) page.
+
+You can read more about the different APIs here: **[Understanding the different MDS APIs](https://github.com/openmobilityfoundation/governance/blob/main/technical/Understanding-MDS-APIs.md)**
+
+[Top][toc]
+
+## Get Involved
 
-## Learn More / Get Involved / Contributing
 To stay up to date on MDS releases, meetings, and events, please **subscribe to the [mds-announce](https://groups.google.com/a/groups.openmobilityfoundation.org/forum/#!forum/mds-announce) mailing list.**
 
 The Mobility Data Specification is an open source project with all development taking place on GitHub. Comments and ideas can be shared by [creating an issue](https://github.com/openmobilityfoundation/mobility-data-specification/issues), and specific changes can be suggested by [opening a pull request](https://github.com/openmobilityfoundation/mobility-data-specification/pulls). Before contributing, please review our OMF [CONTRIBUTING page](https://github.com/openmobilityfoundation/governance/blob/main/CONTRIBUTING.md) to understand guidelines and policies for participation and our [CODE OF CONDUCT page](https://github.com/openmobilityfoundation/governance/blob/main/CODE_OF_CONDUCT.md).
@@ -36,6 +58,8 @@ You can view info about past releases and planning calls in the [wiki](https://g
 
 For questions about MDS please contact [info@openmobilityfoundation.org](mailto:info@openmobilityfoundation.org). Media inquiries to [media@openmobilityfoundation.org](mailto:media@openmobilityfoundation.org)
 
+[Top][toc]
+
 ## Versions
 
 The latest MDS release is in the [`main`](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main) branch, and preparation for the next release occurs in the [`dev`](https://github.com/openmobilityfoundation/mobility-data-specification/tree/dev) branch.
@@ -48,6 +72,8 @@ The MDS specification is versioned using Git tags and [semantic versioning](http
 * [Release Timeline](https://github.com/openmobilityfoundation/mobility-data-specification/wiki#mds-releases)
 * [Release Guidelines](https://github.com/openmobilityfoundation/governance/blob/main/technical/ReleaseGuidelines.md)
 
+[Top][toc]
+
 ## Cities Using MDS
 
 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:
@@ -74,14 +100,22 @@ for Shareable Dockless Mobility Device Permit Holders](https://www.atlantaga.gov
 * **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).
+* **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, [permit requirements](https://www.seattle.gov/Documents/Departments/SDOT/BikeProgram/Seattle_Bike_Share_Permit_Requirements_v2.1_20181219.pdf), and [Mobility Data Privacy and Handling Guidelines](http://www.seattle.gov/Documents/Departments/Tech/Privacy/SDOT_Mobility_Data_Guidelines.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/).
+* **Washington, DC**: Information about the program can be found on [DDOT’s dockless mobility](https://ddot.dc.gov/page/dockless-vehicle-permits-district) page along with the [terms and conditions](https://ddot.dc.gov/sites/default/files/dc/sites/ddot/2019.11.6%20Shared%20dockless%202020%20Terms%20and%20Conditions%20scooter.pdf) and [Attachment C data standards](https://ddot.dc.gov/sites/default/files/dc/sites/ddot/2019.11.6%20Dockless%20Permit%20TC%20Attatchments.pdf).  Further information on the dockless data policies are available [here](https://ddot.dc.gov/page/dockless-api).  
 
 * _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, and Oakland, as mentioned in the [NACTO Guidelines for Regulating Shared Micromobility](https://nacto.org/wp-content/uploads/2019/09/NACTO_Shared_Micromobility_Guidelines_Web.pdf), page 48.
 
+[Top][toc]
+
+## Providers Using MDS
+
+Over two dozen mobility service providers around the world use MDS, allowing them to create tools around a single data standard for multiple cities.  For a full list, see the MDS [provider list](/providers.csv).
+
+[Top][toc]
+
 ## Use Cases
 Some examples of how cities are using MDS in practice:
 
@@ -97,6 +131,10 @@ Some examples of how cities are using MDS in practice:
 - Inform micromobility policy making – number of scooters, distribution, etc.
 - Develop ways to communicate dynamic information on unplanned events, such as emergency road closures, water main breaks, etc. to mobility providers to help them keep their users and contractors informed for better route planning and re-balancing efforts.
 
+More details and examples can be seen on our [Wiki](https://github.com/openmobilityfoundation/governance/wiki/MDS-Use-Cases).
+
+[Top][toc]
+
 ## Related Projects
 
 ### Open Mobility Foundation
@@ -127,6 +165,9 @@ Some examples of how cities are using MDS in practice:
 
 Please open a pull request if you create open source or private tools for implementing or working with MDS data.
 
+[Top][toc]
+
 [agency]: /agency/README.md
 [provider]: /provider/README.md
 [policy]: /policy/README.md
+[toc]: #table-of-contents

MDS-state-machine-diagram.svg

@@ -2,16 +2,14 @@
 
 > Release Date: TBD
 
-> Release Candidate Date: week of June 29, 2020
+> Release Candidate submitted 2020-07-01
 
-The 1.0.0 release reconciles many parts of the MDS specifiction and adds features and updates requested by the community, including support for Stops (for docked vehicles, dockless corrals, parking areas) and adding rates to Policy.
+The 1.0.0 release reconciles many parts of the MDS specification and adds features and updates requested by the community, including support for Stops (for docked vehicles, dockless corrals, parking areas) and adding rates to Policy.
 
 ### CHANGES
 
 See the PRs tagged with [Milestone 1.0.0](https://github.com/openmobilityfoundation/mobility-data-specification/milestone/9) for a full list of changes.
 
-_Here is some of what was added or changed._
-
 *_MDS_*
 
 * [Reconcile the Provider and Agency language differences](https://github.com/openmobilityfoundation/mobility-data-specification/pull/506)
@@ -24,11 +22,11 @@ _Here is some of what was added or changed._
   * Update [Austin](https://github.com/openmobilityfoundation/mobility-data-specification/pull/488), [Louisville](https://github.com/openmobilityfoundation/mobility-data-specification/pull/515) links
   * [Add link to State of Practice](https://github.com/openmobilityfoundation/mobility-data-specification/pull/477)
   * [Update GBFS references and links](https://github.com/openmobilityfoundation/mobility-data-specification/pull/508)
-  * Move [Code of Conduct](https://github.com/openmobilityfoundation/mobility-data-specification/pull/514), [Contributing Guide](https://github.com/openmobilityfoundation/mobility-data-specification/pull/513), and [Release Guidelines](https://github.com/openmobilityfoundation/mobility-data-specification/pull/512) to new [Governace repo](https://github.com/openmobilityfoundation/governance)
+  * Move [Code of Conduct](https://github.com/openmobilityfoundation/mobility-data-specification/pull/514), [Contributing Guide](https://github.com/openmobilityfoundation/mobility-data-specification/pull/513), and [Release Guidelines](https://github.com/openmobilityfoundation/mobility-data-specification/pull/512) to new [Governance repo](https://github.com/openmobilityfoundation/governance)
    * [Updating 'master' to 'main' as default branch name](https://github.com/openmobilityfoundation/mobility-data-specification/pull/522)
    * [Update providers.csv to add Superpedestrian](https://github.com/openmobilityfoundation/mobility-data-specification/pull/535)
    * [Removed Options version negotiation](https://github.com/openmobilityfoundation/mobility-data-specification/pull/536#pullrequestreview-439364663)
-   * [Added 'other' vechicle type](https://github.com/openmobilityfoundation/mobility-data-specification/issues/518)
+   * [Added 'other' vehicle type](https://github.com/openmobilityfoundation/mobility-data-specification/issues/518)
 
 *_Provider_*
 

README.md

@@ -1,6 +1,8 @@
 # Mobility Data Specification: **Agency**
 
-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.
+The Agency API endpoints are intended to be implemented by regulatory agencies and consumed by mobility providers. Providers query the Agency API when events (such as a trip start or vehicle status change) occur in their systems.
+
+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.
 
 ## Table of Contents
 
@@ -108,7 +110,6 @@ Body Params:
 | `vehicle_id` | String  | Required          | Vehicle Identification Number (vehicle_id) visible on vehicle        |
 | `vehicle_type`       | Enum    | Required          | [Vehicle Type][vehicle-types]                                        |
 | `propulsion_types` | Enum[]  | Required          | Array of [Propulsion Type][propulsion-types]; allows multiple values |
-| `provider_id`| UUID    | Optional          | Provider to which the vehicle belongs if different from the authenticated provider |
 | `year`       | Integer | Optional          | Year Manufactured                                                    |
 | `mfgr`       | String  | Optional          | Vehicle Manufacturer                                                 |
 | `model`      | String  | Optional          | Vehicle Model                                                        |

ReleaseNotes.md

@@ -47,7 +47,7 @@
         "capacity": {
           "$id": "#/definitions/stop/properties/capacity",
           "$ref": "#/definitions/vehicle_type_counts",
-          "description": "Number of total spaces per vehicle_type"
+          "description": "Number of total places per vehicle_type"
         },
         "num_vehicles_available": {
           "$id": "#/definitions/stop/properties/num_vehicles_available",
@@ -94,15 +94,15 @@
           "$ref": "#/definitions/string",
           "description": "Cross street of where Stop is located"
         },
-        "num_spaces_available": {
-          "$id": "#/definitions/stop/properties/num_spaces_available",
+        "num_places_available": {
+          "$id": "#/definitions/stop/properties/num_places_available",
           "$ref": "#/definitions/vehicle_type_counts",
-          "description": "Number of spaces free to be populated per vehicle_type"
+          "description": "Number of places free to be populated per vehicle_type"
         },
-        "num_spaces_disabled": {
-          "$id": "#/definitions/stop/properties/num_spaces_disabled",
+        "num_places_disabled": {
+          "$id": "#/definitions/stop/properties/num_places_disabled",
           "$ref": "#/definitions/vehicle_type_counts",
-          "description": "Number of spaces disabled an unable to accept vehicles per vehicle_type"
+          "description": "Number of places disabled an unable to accept vehicles per vehicle_type"
         },
         "parent_stop": {
           "$id": "#/definitions/stop/properties/parent_stop",

agency/README.md

@@ -47,7 +47,7 @@
         "capacity": {
           "$id": "#/definitions/stop/properties/capacity",
           "$ref": "#/definitions/vehicle_type_counts",
-          "description": "Number of total spaces per vehicle_type"
+          "description": "Number of total places per vehicle_type"
         },
         "num_vehicles_available": {
           "$id": "#/definitions/stop/properties/num_vehicles_available",
@@ -94,15 +94,15 @@
           "$ref": "#/definitions/string",
           "description": "Cross street of where Stop is located"
         },
-        "num_spaces_available": {
-          "$id": "#/definitions/stop/properties/num_spaces_available",
+        "num_places_available": {
+          "$id": "#/definitions/stop/properties/num_places_available",
           "$ref": "#/definitions/vehicle_type_counts",
-          "description": "Number of spaces free to be populated per vehicle_type"
+          "description": "Number of places free to be populated per vehicle_type"
         },
-        "num_spaces_disabled": {
-          "$id": "#/definitions/stop/properties/num_spaces_disabled",
+        "num_places_disabled": {
+          "$id": "#/definitions/stop/properties/num_places_disabled",
           "$ref": "#/definitions/vehicle_type_counts",
-          "description": "Number of spaces disabled an unable to accept vehicles per vehicle_type"
+          "description": "Number of places disabled an unable to accept vehicles per vehicle_type"
         },
         "parent_stop": {
           "$id": "#/definitions/stop/properties/parent_stop",

agency/get_stops.json

@@ -61,11 +61,6 @@
     "propulsion_types"
   ],
   "properties": {
-    "provider_id": {
-      "$id": "#/definitions/vehicle/properties/provider_id",
-      "$ref": "#/definitions/uuid",
-      "description": "The UUID for the Provider, unique within MDS"
-    },
     "device_id": {
       "$id": "#/definitions/vehicle/properties/device_id",
       "$ref": "#/definitions/uuid",