updating state machine in schemas

* use new field names and plurality
* common state and event defintions merged by schema generator
* valid state/event combinations merged by schema generator

Author: thekaveman

agency/README.md

@@ -76,7 +76,7 @@ A vehicle record is as follows:
 | `mfgr`        | String    | Vehicle Manufacturer                                                          |
 | `model`       | String    | Vehicle Model                                                                 |
 | `state`       | Enum      | Current vehicle state. See [Vehicle State][vehicle-states]                    |
-| `prev_event`  | Enum      | Last [Vehicle Event][vehicle-event]                                           |
+| `prev_events`  | Enum[]      | Last [Vehicle Event][vehicle-event]                                           |
 | `updated`     | [timestamp][ts] | Date of last event update                                                     |
 
 404 Failure Response:

provider/README.md

@@ -266,7 +266,7 @@ Unless stated otherwise by the municipality, this endpoint must return only thos
 | `vehicle_type` | Enum | Required | see [vehicle types][vehicle-types] table |
 | `propulsion_types` | Enum[] | Required | Array of [propulsion types][propulsion-types]; allows multiple values |
 | `vehicle_state` | Enum | Required | See [vehicle state][vehicle-states] table |
-| `event_type` | Enum[] | Required | [Vehicle event(s)][vehicle-events] for state change, allowable values determined by `vehicle_state`. |
+| `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 | |
@@ -398,8 +398,8 @@ In addition to the standard [Provider payload wrapper](#response-format), respon
 | `vehicle_type` | Enum | Required | see [vehicle types][vehicle-types] table |
 | `propulsion_types` | Enum[] | Required | Array of [propulsion types][propulsion-types]; allows multiple values |
 | `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 of most recent state change. See [vehicle states][vehicle-states] table |
-| `last_vehicle_events` | Enum[] | Required | [Vehicle event(s)][vehicle-events] of most recent state change, allowable values determined by `last_vehicle_state`. |
+| `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 |
 | `battery_pct` | Float | Required if Applicable | Percent battery charge of device, expressed between 0 and 1 |

schema/generate_schemas.py

@@ -5,6 +5,7 @@
     python generate_schemas.py [--agency] [--provider]
 """
 
+import copy
 import json
 import jsonschema
 import requests
@@ -20,6 +21,55 @@ def load_json(path):
         return data
 
 
+def vehicle_model(common_definitions, provider_name=True, provider_id=True):
+    """
+    Extract a deep-copy of the common vehicle model definition to allow for customization.
+    """
+    vehicle = copy.deepcopy(common_definitions["vehicle"])
+
+    if not provider_name:
+        vehicle["required"].remove("provider_name")
+        del vehicle["properties"]["provider_name"]
+
+    if not provider_id:
+        vehicle["required"].remove("provider_id")
+        del vehicle["properties"]["provider_id"]
+
+    return vehicle
+
+
+def vehicle_state_machine(common_definitions, vehicle_state=None, vehicle_events=None):
+    """
+    Return a tuple (definitions, transitions) with the common vehicle state schema.
+        * defitions is the common definitions for vehicle state fields
+        * transitions is the rule for valid state/event combinations
+
+    Optionally pass field names for the vehicle_state and vehicle_events schemas
+    to override those in transitions.
+    """
+    state_machine_defs = {
+        "vehicle_state": common_definitions["vehicle_state"],
+        "vehicle_event": common_definitions["vehicle_event"],
+        "vehicle_events": common_definitions["vehicle_events"],
+    }
+
+    transitions = copy.deepcopy(common_definitions["vehicle_state_transitions"])
+
+    if vehicle_state:
+        for option in transitions["oneOf"]:
+            state = option["properties"]["vehicle_state"]
+            del option["properties"]["vehicle_state"]
+            option["properties"][vehicle_state] = state
+
+    if vehicle_events:
+        for option in transitions["oneOf"]:
+            events = option["properties"]["vehicle_events"]
+            del option["properties"]["vehicle_events"]
+            option["properties"][vehicle_events] = events
+
+    return (state_machine_defs, transitions)
+
+
 def agency_get_vehicle_schema(common_definitions):
     """
     Create the schema for the Agency GET /vehicles endpoint.
@@ -29,18 +79,18 @@ def agency_get_vehicle_schema(common_definitions):
     schema["definitions"] = {
         "propulsion_types": common_definitions["propulsion_types"],
         "string": common_definitions["string"],
-        "vehicle_state": common_definitions["vehicle_state"],
-        "vehicle_events": common_definitions["vehicle_events"],
         "vehicle_type": common_definitions["vehicle_type"],
         "timestamp": common_definitions["timestamp"],
         "uuid": common_definitions["uuid"]
     }
 
-    # merge common vehicle information, with Agency tweaks
-    vehicle = dict(common_definitions["vehicle"])
-    vehicle["required"].remove("provider_name")
-    del vehicle["properties"]["provider_name"]
+    # merge the state machine definitions and transition combinations rule
+    state_machine_defs, transitions = vehicle_state_machine(common_definitions, "state", "prev_events")
+    schema["definitions"].update(state_machine_defs)
+    schema["allOf"].append(transitions)
 
+    # merge common vehicle information, with Agency tweaks
+    vehicle = vehicle_model(common_definitions, provider_name=False)
     schema["required"] = vehicle["required"] + schema["required"]
     schema["properties"] = { **vehicle["properties"], **schema["properties"] }
 
@@ -64,10 +114,8 @@ def agency_post_vehicle_schema(common_definitions):
     }
 
     # merge common vehicle information, with Agency tweaks
-    vehicle = dict(common_definitions["vehicle"])
-    vehicle["required"].remove("provider_name")
+    vehicle = vehicle_model(common_definitions, provider_name=False)
     vehicle["required"].remove("provider_id")
-    del vehicle["properties"]["provider_name"]
 
     schema["required"] = vehicle["required"] + schema["required"]
     schema["properties"] = { **vehicle["properties"], **schema["properties"] }
@@ -85,12 +133,15 @@ def agency_post_vehicle_event_schema(common_definitions):
     # load schema template and insert definitions
     schema = load_json("./templates/agency/post_vehicle_event.json")
     schema["definitions"] = {
-        "vehicle_state": common_definitions["vehicle_state"],
-        "vehicle_events": common_definitions["vehicle_events"],
         "telemetry": common_definitions["telemetry"],
         "timestamp": common_definitions["timestamp"],
     }
 
+    # merge the state machine definitions and transition combinations rule
+    state_machine_defs, transitions = vehicle_state_machine(common_definitions, "vehicle_state", "event_types")
+    schema["definitions"].update(state_machine_defs)
+    schema["allOf"].append(transitions)
+
     # add the conditionally-required trip_id rule
     trip_id_ref = common_definitions["trip_id_reference"]
     schema["allOf"].append(trip_id_ref)
@@ -298,9 +349,10 @@ def provider_schema(endpoint, common_definitions, extra_definitions={}):
     # merge endpoint-specific schema with standard vehicle info
     endpoint_schema = load_json(f"./templates/provider/{endpoint}.json")
     items = endpoint_schema[endpoint]["items"]
-    vehicle_schema = dict(common_definitions["vehicle"])
-    items["required"] = vehicle_schema["required"] + items["required"]
-    items["properties"] = { **vehicle_schema["properties"], **items["properties"] }
+
+    vehicle = vehicle_model(common_definitions)
+    items["required"] = vehicle["required"] + items["required"]
+    items["properties"] = { **vehicle["properties"], **items["properties"] }
 
     # merge this endpoint-specific schema into the endpoint template
     data_schema = schema["properties"]["data"]
@@ -340,6 +392,11 @@ def provider_status_changes_schema(common_definitions):
     schema = provider_schema("status_changes", common_definitions)
     items = schema["properties"]["data"]["properties"]["status_changes"]["items"]
 
+    # merge the state machine definitions and transition combinations rule
+    state_machine_defs, transitions = vehicle_state_machine(common_definitions, "vehicle_state", "event_types")
+    schema["definitions"].update(state_machine_defs)
+    items["allOf"].append(transitions)
+
     trip_id_ref = common_definitions["trip_id_reference"]
     items["allOf"].append(trip_id_ref)
 
@@ -356,9 +413,10 @@ def provider_events_schema(common_definitions):
     links_prop, links_def = property_definition("links", common_definitions)
 
     # events is the same as status_changes, but allows paging
-    schema = provider_schema("status_changes", common_definitions, links_def)
+    schema = provider_status_changes_schema(common_definitions)
     schema["$id"] = schema["$id"].replace("status_changes", "events")
     schema["title"] = schema["title"].replace("status_changes", "events")
+    schema["definitions"].update(links_def)
     schema["properties"].update(links_prop)
 
     # verify schema validity
@@ -384,12 +442,18 @@ def provider_vehicles_schema(common_definitions):
     definitions.update(defn)
     properties.update(prop)
 
+    state_machine_defs, transitions = vehicle_state_machine(common_definitions, "last_vehicle_state", "last_event_types")
+    definitions.update(state_machine_defs)
+
     schema = provider_schema("vehicles", common_definitions, definitions)
 
     # update list of required and properties object
     schema["required"].extend(["last_updated", "ttl"])
     schema["properties"].update(properties)
 
+    # add state machine transition rules
+    schema["properties"]["data"]["properties"]["vehicles"]["items"]["allOf"].append(transitions)
+
     # verify schema validity
     jsonschema.Draft6Validator.check_schema(schema)
 

schema/templates/agency/get_vehicle.json

@@ -8,8 +8,8 @@
     "year",
     "mfgr",
     "model",
-    "status",
-    "prev_event",
+    "state",
+    "prev_events",
     "updated"
   ],
   "properties": {
@@ -32,20 +32,21 @@
       "$ref": "#/definitions/string",
       "description": "The vehicle model"
     },
-    "status": {
-      "$id": "#/properties/status",
-      "$ref": "#/definitions/vehicle_status",
-      "description": "Current vehicle status"
+    "state": {
+      "$id": "#/properties/state",
+      "$ref": "#/definitions/vehicle_state",
+      "description": "Current vehicle state"
     },
-    "prev_event": {
-      "$id": "#/properties/prev_event",
-      "$ref": "#/definitions/vehicle_event",
+    "prev_events": {
+      "$id": "#/properties/prev_events",
+      "$ref": "#/definitions/vehicle_events",
       "description": "Last vehicle event"
     },
     "updated": {
       "$id": "#/properties/updated",
       "$ref": "#/definitions/timestamp"
     }
   },
-  "additionalProperties": false
+  "additionalProperties": false,
+  "allOf": []
 }

schema/templates/agency/post_vehicle_event.json

@@ -5,12 +5,20 @@
   "type": "object",
   "definitions": {},
   "required": [
-    "event_type",
+    "vehicle_state",
+    "event_types",
+    "timestamp",
     "telemetry"
   ],
   "properties": {
-    "event_type": {
-      "$ref": "#/definitions/vehicle_event"
+    "vehicle_state": {
+      "$ref": "#/definitions/vehicle_state"
+    },
+    "event_types": {
+      "$ref": "#/definitions/vehicle_events"
+    },
+    "timestamp": {
+      "$ref": "#/definitions/timestamp"
     },
     "telemetry": {
       "$ref": "#/definitions/telemetry"
@@ -19,5 +27,6 @@
       "$ref": "#/definitions/uuid"
     }
   },
-  "additionalProperties": false
+  "additionalProperties": false,
+  "allOf": []
 }