Merge pull request #442 from avatarneil/trips-route-stop-implementation

Add stop references to trips and status_changes

Author: schnuerle

general-information.md

@@ -108,6 +108,8 @@ All String fields, such as `vehicle_id`, are limited to a maximum of 255 charact
 
 ## Stops
 
+**Stops** describe vehicle trip end locations in a pre-designated physical place. They can vary from docking stations with or without charging, corrals with lock-to railings, or suggested parking areas marked with spray paint.  **Stops** are used in both [Provider](/provider#stops) (including routes and event locations) and [Agency](/agency#stops) (including telemetry data).
+
 | Field                  | Type                                                        | Required/Optional | Description                                                                                  |
 |------------------------|-------------------------------------------------------------|-------------------|----------------------------------------------------------------------------------------------|
 | stop_id                | UUID                                                        | Required          | Unique ID for stop                                                                           |
@@ -133,12 +135,24 @@ All String fields, such as `vehicle_id`, are limited to a maximum of 255 charact
 
 ### Stop Status
 
+**Stop Status** returns information about the current status of a **[Stop](#stops)**.
+
 | Field        | Type    | Required/Optional | Description                                         |
 |--------------|---------|-------------------|-----------------------------------------------------|
 | is_installed | Boolean | Required          | See GBFS [station_status.json][gbfs-station-status] |
 | is_renting   | Boolean | Required          | See GBFS [station_status.json][gbfs-station-status] |
 | is_returning | Boolean | Required          | See GBFS [station_status.json][gbfs-station-status] |
 
+Example of the **Stop Status** object with properties listed:
+
+```json
+ {
+  "is_installed": true,
+  "is_renting": false,
+  "is_returning": true
+ }
+```
+
 ### 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.
@@ -264,7 +278,7 @@ If an unsupported or invalid version is requested, the API must respond with a s
 
 [agency]: /agency/README.md
 [gbfs-station-info]: https://github.com/NABSA/gbfs/blob/master/gbfs.md#station_informationjson
-[gbfs-station-status]: https://github.com/NABSA/gbfs/blob/v2.1-RC/gbfs.md#station_statusjson
+[gbfs-station-status]: https://github.com/NABSA/gbfs/blob/master/gbfs.md#station_statusjson
 [policy]: /policy/README.md
 [provider]: /provider/README.md
 [toc]: #table-of-contents

provider/README.md

@@ -120,6 +120,28 @@ represented as a GeoJSON [`Feature`][geojson-feature] object with a correspondin
 }
 ```
 
+#### Stop-based Geographic Data
+
+When an individual location coordinate measurement corresponds to a [Stop][general-stops],
+it must be presented with a `stop_id` property:
+
+```json
+{
+    "type": "Feature",
+    "properties": {
+        "timestamp": 1529968782421,
+        "stop_id": "b813cde2-a41c-4ae3-b409-72ff221e003d"
+    },
+    "geometry": {
+        "type": "Point",
+        "coordinates": [
+            -118.46710503101347,
+            33.9909333514159
+        ]
+    }
+}
+```
+
 #### Intersection Operation
 
 For the purposes of this specification, the intersection of two geographic datatypes is defined according to the [`ST_Intersects` PostGIS operation][st-intersects]
@@ -207,13 +229,17 @@ To represent a route, MDS `provider` APIs must create a GeoJSON [`FeatureCollect
 
 Routes must include at least 2 points: the start point and end point. Routes must include all possible GPS or GNSS samples collected by a Provider. Providers may round the latitude and longitude to the level of precision representing the maximum accuracy of the specific measurement. For example, [a-GPS][agps] is accurate to 5 decimal places, [differential GPS][dgps] is generally accurate to 6 decimal places. Providers may round those readings to the appropriate number for their systems.
 
+Trips that start or end at a [Stop][general-stops] must include a `stop_id` property in the first (when starting) and last (when ending) Feature of the `route`. See [Stop-based Geographic Data][stop-based-geo] for more information.
+
 ```js
 "route": {
     "type": "FeatureCollection",
     "features": [{
         "type": "Feature",
         "properties": {
-            "timestamp": 1529968782421
+            "timestamp": 1529968782421,
+            // Required for Trips starting at a Stop
+            "stop_id": "95084833-6a3f-4770-9919-de1ab4b8989b",
         },
         "geometry": {
             "type": "Point",
@@ -226,7 +252,9 @@ Routes must include at least 2 points: the start point and end point. Routes mus
     {
         "type": "Feature",
         "properties": {
-            "timestamp": 1531007628377
+            "timestamp": 1531007628377,
+            // Required for Trips ending at a Stop
+            "stop_id": "b813cde2-a41c-4ae3-b409-72ff221e003d"
         },
         "geometry": {
             "type": "Point",
@@ -269,7 +297,7 @@ Unless stated otherwise by the municipality, this endpoint must return only thos
 | `event_types` | Enum[] | Required | [Vehicle event(s)][vehicle-events] for state change, allowable values determined by `vehicle_state` |
 | `event_time` | [timestamp][ts] | Required | Date/time that event occurred at. See [Event Times][event-times] |
 | `publication_time` | [timestamp][ts] | Optional | Date/time that event became available through the status changes endpoint |
-| `event_location` | GeoJSON [Point Feature][geo] | Required | |
+| `event_location` | GeoJSON [Point Feature][geo] | Required | See also [Stop-based Geographic Data][stop-based-geo] |
 | `battery_pct` | Float | Required if Applicable | Percent battery charge of device, expressed between 0 and 1 |
 | `trip_id` | UUID | Required if Applicable | Trip UUID (foreign key to Trips API), required if `event_types` contains `trip_start`, `trip_end`, `trip_cancel`, `trip_enter_jurisdiction`, or `trip_leave_jurisdiction` |
 | `associated_ticket` | String | Optional | Identifier for an associated ticket inside an Agency-maintained 311 or CRM system |
@@ -319,6 +347,8 @@ Unless stated otherwise by the municipality, this endpoint must return only thos
 
 > Note: As a result of this definition, consumers should query the [trips endpoint][trips] to infer when vehicles enter or leave the municipality boundary.
 
+See also [Stop-based Geographic Data][stop-based-geo].
+
 The schema and datatypes are the same as those defined for [`/status_changes`][status].
 
 **Endpoint:** `/events`  
@@ -400,8 +430,8 @@ In addition to the standard [Provider payload wrapper](#response-format), respon
 | `last_event_time` | [timestamp][ts] | Required | Date/time when last state change occurred. See [Event Times][event-times] |
 | `last_vehicle_state` | Enum | Required | [Vehicle state][vehicle-states] of most recent state change. |
 | `last_event_types` | Enum[] | Required | [Vehicle event(s)][vehicle-events] of most recent state change, allowable values determined by `last_vehicle_state`. |
-| `last_event_location` | GeoJSON [Point Feature][geo]| Required | Location of vehicle's last event |
-| `current_location` | GeoJSON [Point Feature][geo] | Required if Applicable | Current location of vehicle if different from last event, and the vehicle is not currently on a trip |
+| `last_event_location` | GeoJSON [Point Feature][geo]| Required | Location of vehicle's last event. See also [Stop-based Geographic Data][stop-based-geo]. |
+| `current_location` | GeoJSON [Point Feature][geo] | Required if Applicable | Current location of vehicle if different from last event, and the vehicle is not currently on a trip. See also [Stop-based Geographic Data][stop-based-geo]. |
 | `battery_pct` | Float | Required if Applicable | Percent battery charge of device, expressed between 0 and 1 |
 
 [Top][toc]
@@ -417,6 +447,7 @@ In addition to the standard [Provider payload wrapper](#response-format), respon
 [event-times]: #event-times
 [gbfs]: https://github.com/NABSA/gbfs
 [general-information]: /general-information.md
+[general-stops]: /general-information.md#stops
 [geo]: #geographic-data
 [geojson-feature]: https://tools.ietf.org/html/rfc7946#section-3.2
 [geojson-feature-collection]: https://tools.ietf.org/html/rfc7946#section-3.3
@@ -432,6 +463,7 @@ In addition to the standard [Provider payload wrapper](#response-format), respon
 [status]: #status-changes
 [status-schema]: status_changes.json
 [stops]: #stops
+[stop-based-geo]: #stop-based-geographic-data
 [st-intersects]: https://postgis.net/docs/ST_Intersects.html
 [toc]: #table-of-contents
 [trips]: #trips

provider/events.json

@@ -69,6 +69,9 @@
           "properties": {
             "timestamp": {
               "$ref": "#/definitions/timestamp"
+            },
+            "stop_id": {
+              "$ref": "#/definitions/uuid"
             }
           }
         },

provider/status_changes.json

@@ -69,6 +69,9 @@
           "properties": {
             "timestamp": {
               "$ref": "#/definitions/timestamp"
+            },
+            "stop_id": {
+              "$ref": "#/definitions/uuid"
             }
           }
         },

provider/trips.json

@@ -69,6 +69,9 @@
           "properties": {
             "timestamp": {
               "$ref": "#/definitions/timestamp"
+            },
+            "stop_id": {
+              "$ref": "#/definitions/uuid"
             }
           }
         },

provider/vehicles.json

@@ -69,6 +69,9 @@
           "properties": {
             "timestamp": {
               "$ref": "#/definitions/timestamp"
+            },
+            "stop_id": {
+              "$ref": "#/definitions/uuid"
             }
           }
         },

schema/generate_schemas.py

@@ -325,8 +325,16 @@ def provider_schema(endpoint, common_definitions, extra_definitions={}):
         title = "MDS GeoJSON Feature Point",
         # Only allow GeoJSON Point feature geometry
         geometry = { "$ref": definition_id("Point") },
-        # Point features *must* include a `timestamp` property.
-        properties = { "timestamp": { "$ref": definition_id("timestamp") } },
+        properties = {
+            "timestamp": {
+                "$ref": definition_id("timestamp")
+            },
+            # Locations corresponding to Stops must include a `stop_id` reference
+            "stop_id": {
+                "$ref": definition_id("uuid")
+            }
+        },
+        # Point features *must* include the `timestamp`
         required = ["timestamp"]
     )