Skip to content

Commit 4dae43a

Browse files
thekavemanthekaveman
committed
aligning Agency and Provider schemas
* reuse common string definition in Agency templates * renaming vehicle fields in Agency to make common schema reuse easier * renaming status_changes.associated_trip --> status_changes.trip_id and reusing validation rule in Agency and Provider schemas * pluralizing propulsion_types (array field) in both * further reorganize schema generation for alignment between Agency and Provider
1 parent 748efb6 commit 4dae43a

9 files changed

Lines changed: 299 additions & 409 deletions

File tree

‎agency/README.md‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -32,11 +32,11 @@ See the [Responses][responses] and [Error Messages][error-messages] sections.
3232

3333
### Authorization
3434

35-
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.
35+
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.
3636

3737
## Vehicles
3838

39-
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.
39+
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.
4040

4141
Endpoint: `/vehicles/{device_id}`
4242
Method: `GET`
@@ -70,8 +70,8 @@ A vehicle record is as follows:
7070
| `device_id` | UUID | Provided by Operator to uniquely identify a vehicle |
7171
| `provider_id` | UUID | Issued by Agency and [tracked](../providers.csv) |
7272
| `vehicle_id` | String | Vehicle Identification Number (vehicle_id) visible on vehicle |
73-
| `type` | Enum | [Vehicle Type][vehicle-types] |
74-
| `propulsion` | Enum[] | Array of [Propulsion Type][propulsion-types]; allows multiple values |
73+
| `vehicle_type` | Enum | [Vehicle Type][vehicle-types] |
74+
| `propulsion_types` | Enum[] | Array of [Propulsion Type][propulsion-types]; allows multiple values |
7575
| `year` | Integer | Year Manufactured |
7676
| `mfgr` | String | Vehicle Manufacturer |
7777
| `model` | String | Vehicle Model |
@@ -96,8 +96,8 @@ Body Params:
9696
| ------------ | ------- | ----------------- | -------------------------------------------------------------------- |
9797
| `device_id` | UUID | Required | Provided by Operator to uniquely identify a vehicle |
9898
| `vehicle_id` | String | Required | Vehicle Identification Number (vehicle_id) visible on vehicle |
99-
| `type` | Enum | Required | [Vehicle Type][vehicle-types] |
100-
| `propulsion` | Enum[] | Required | Array of [Propulsion Type][propulsion-types]; allows multiple values |
99+
| `vehicle_type` | Enum | Required | [Vehicle Type][vehicle-types] |
100+
| `propulsion_types` | Enum[] | Required | Array of [Propulsion Type][propulsion-types]; allows multiple values |
101101
| `provider_id`| UUID | Optional | Provider to which the vehicle belongs if different from the authenticated provider |
102102
| `year` | Integer | Optional | Year Manufactured |
103103
| `mfgr` | String | Optional | Vehicle Manufacturer |
@@ -122,7 +122,7 @@ _No content returned on success._
122122

123123
## Vehicle - Update
124124

125-
The `/vehicles` update endpoint is used to update some mutable aspect of a vehicle. For now, only `vehicle_id`.
125+
The `/vehicles` update endpoint is used to update some mutable aspect of a vehicle. For now, only `vehicle_id`.
126126

127127
Endpoint: `/vehicles/{device_id}`
128128
Method: `PUT`
@@ -169,7 +169,7 @@ Body Params:
169169
| `event_types` | Enum[] | Required | see [Vehicle Events][vehicle-events] |
170170
| `timestamp` | [timestamp][ts] | Required | Date of last event update |
171171
| `telemetry` | [Telemetry](#telemetry-data) | Required | Single point of telemetry |
172-
| `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 |
172+
| `trip_id` | UUID | Optional | UUID provided by Operator to uniquely identify the trip. Required if `event_types` contains `trip_start`, `trip_end`, `trip_cancel`, `trip_enter_jurisdiction`, or `trip_leave_jurisdiction` |
173173

174174
201 Success Response:
175175

‎agency/get_vehicle.json‎

Lines changed: 27 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,17 @@
1919
},
2020
"minItems": 1
2121
},
22+
"string": {
23+
"$id": "#/definitions/string",
24+
"type": "string",
25+
"description": "A length-limited string type",
26+
"maxLength": 255,
27+
"default": "",
28+
"examples": [
29+
"ABC123"
30+
],
31+
"pattern": "^(.*)$"
32+
},
2233
"vehicle_type": {
2334
"$id": "#/definitions/vehicle_type",
2435
"type": "string",
@@ -224,24 +235,18 @@
224235
"properties": {
225236
"device_id": {
226237
"$id": "#/properties/device_id",
227-
"description": "Provided by Operator to uniquely identify a vehicle",
228-
"$ref": "#/definitions/uuid"
238+
"$ref": "#/definitions/uuid",
239+
"description": "Provided by Operator to uniquely identify a vehicle"
229240
},
230241
"provider_id": {
231242
"$id": "#/properties/provider_id",
232-
"description": "Issued by City and tracked",
233-
"$ref": "#/definitions/uuid"
243+
"$ref": "#/definitions/uuid",
244+
"description": "Issued by City and tracked"
234245
},
235246
"vehicle_id": {
236247
"$id": "#/properties/vehicle_id",
237-
"type": "string",
238-
"maxLength": 255,
239-
"description": "The Vehicle Identification Number visible on the vehicle itself",
240-
"default": "",
241-
"examples": [
242-
"ABC123"
243-
],
244-
"pattern": "^(.*)$"
248+
"$ref": "#/definitions/string",
249+
"description": "The Vehicle Identification Number visible on the vehicle itself"
245250
},
246251
"type": {
247252
"$id": "#/properties/type",
@@ -250,8 +255,8 @@
250255
},
251256
"propulsion": {
252257
"$id": "#/properties/propulsion",
253-
"description": "The type of propulsion; allows multiple values",
254-
"$ref": "#/definitions/propulsion_type"
258+
"$ref": "#/definitions/propulsion_type",
259+
"description": "The type of propulsion; allows multiple values"
255260
},
256261
"year": {
257262
"$id": "#/properties/year",
@@ -264,35 +269,23 @@
264269
},
265270
"mfgr": {
266271
"$id": "#/properties/mfgr",
267-
"type": "string",
268-
"maxLength": 255,
269-
"description": "The vehicle manufacturer",
270-
"default": "",
271-
"examples": [
272-
"ABC123"
273-
],
274-
"pattern": "^(.*)$"
272+
"$ref": "#/definitions/string",
273+
"description": "The vehicle manufacturer"
275274
},
276275
"model": {
277276
"$id": "#/properties/model",
278-
"type": "string",
279-
"maxLength": 255,
280-
"description": "The vehicle model",
281-
"default": "",
282-
"examples": [
283-
"ABC123"
284-
],
285-
"pattern": "^(.*)$"
277+
"$ref": "#/definitions/string",
278+
"description": "The vehicle model"
286279
},
287280
"status": {
288281
"$id": "#/properties/status",
289-
"description": "Current vehicle status",
290-
"$ref": "#/definitions/vehicle_status"
282+
"$ref": "#/definitions/vehicle_status",
283+
"description": "Current vehicle status"
291284
},
292285
"prev_event": {
293286
"$id": "#/properties/prev_event",
294-
"description": "Last vehicle event",
295-
"$ref": "#/definitions/vehicle_event"
287+
"$ref": "#/definitions/vehicle_event",
288+
"description": "Last vehicle event"
296289
},
297290
"updated": {
298291
"$id": "#/properties/updated",

‎agency/post_vehicle.json‎

Lines changed: 21 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,17 @@
1919
},
2020
"minItems": 1
2121
},
22+
"string": {
23+
"$id": "#/definitions/string",
24+
"type": "string",
25+
"description": "A length-limited string type",
26+
"maxLength": 255,
27+
"default": "",
28+
"examples": [
29+
"ABC123"
30+
],
31+
"pattern": "^(.*)$"
32+
},
2233
"vehicle_type": {
2334
"$id": "#/definitions/vehicle_type",
2435
"type": "string",
@@ -50,19 +61,13 @@
5061
"properties": {
5162
"device_id": {
5263
"$id": "#/properties/device_id",
53-
"description": "Provided by Operator to uniquely identify a vehicle",
54-
"$ref": "#/definitions/uuid"
64+
"$ref": "#/definitions/uuid",
65+
"description": "Provided by Operator to uniquely identify a vehicle"
5566
},
5667
"vehicle_id": {
5768
"$id": "#/properties/vehicle_id",
58-
"type": "string",
59-
"maxLength": 255,
60-
"description": "The Vehicle Identification Number visible on the vehicle itself",
61-
"default": "",
62-
"examples": [
63-
"ABC123"
64-
],
65-
"pattern": "^(.*)$"
69+
"$ref": "#/definitions/string",
70+
"description": "The Vehicle Identification Number visible on the vehicle itself"
6671
},
6772
"type": {
6873
"$id": "#/properties/type",
@@ -71,8 +76,8 @@
7176
},
7277
"propulsion": {
7378
"$id": "#/properties/propulsion",
74-
"description": "The type of propulsion; allows multiple values",
75-
"$ref": "#/definitions/propulsion_type"
79+
"$ref": "#/definitions/propulsion_type",
80+
"description": "The type of propulsion; allows multiple values"
7681
},
7782
"year": {
7883
"$id": "#/properties/year",
@@ -85,25 +90,13 @@
8590
},
8691
"mfgr": {
8792
"$id": "#/properties/mfgr",
88-
"type": "string",
89-
"maxLength": 255,
90-
"description": "The vehicle manufacturer",
91-
"default": "",
92-
"examples": [
93-
"ABC123"
94-
],
95-
"pattern": "^(.*)$"
93+
"$ref": "#/definitions/string",
94+
"description": "The vehicle manufacturer"
9695
},
9796
"model": {
9897
"$id": "#/properties/model",
99-
"type": "string",
100-
"maxLength": 255,
101-
"description": "The vehicle model",
102-
"default": "",
103-
"examples": [
104-
"ABC123"
105-
],
106-
"pattern": "^(.*)$"
98+
"$ref": "#/definitions/string",
99+
"description": "The vehicle model"
107100
}
108101
},
109102
"additionalProperties": false

‎provider/README.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -173,7 +173,7 @@ Unless stated otherwise by the municipality, the trips endpoint must return all
173173
| `device_id` | UUID | Required | A unique device ID in UUID format |
174174
| `vehicle_id` | String | Required | The Vehicle Identification Number visible on the vehicle itself |
175175
| `vehicle_type` | Enum | Required | See [vehicle types][vehicle-types] table |
176-
| `propulsion_type` | Enum[] | Required | Array of [propulsion types][propulsion-types]; allows multiple values |
176+
| `propulsion_types` | Enum[] | Required | Array of [propulsion types][propulsion-types]; allows multiple values |
177177
| `trip_id` | UUID | Required | A unique ID for each trip |
178178
| `trip_duration` | Integer | Required | Time, in Seconds |
179179
| `trip_distance` | Integer | Required | Trip Distance, in Meters |
@@ -264,15 +264,15 @@ Unless stated otherwise by the municipality, this endpoint must return only thos
264264
| `device_id` | UUID | Required | A unique device ID in UUID format |
265265
| `vehicle_id` | String | Required | The Vehicle Identification Number visible on the vehicle itself |
266266
| `vehicle_type` | Enum | Required | see [vehicle types][vehicle-types] table |
267-
| `propulsion_type` | Enum[] | Required | Array of [propulsion types][propulsion-types]; allows multiple values |
267+
| `propulsion_types` | Enum[] | Required | Array of [propulsion types][propulsion-types]; allows multiple values |
268268
| `vehicle_state` | Enum | Required | See [vehicle state][vehicle-states] table |
269269
| `event_type` | Enum[] | Required | [Vehicle event(s)][vehicle-events] for state change, allowable values determined by `vehicle_state`. |
270270
| `event_time` | [timestamp][ts] | Required | Date/time that event occurred at. See [Event Times][event-times] |
271271
| `publication_time` | [timestamp][ts] | Optional | Date/time that event became available through the status changes endpoint |
272272
| `event_location` | GeoJSON [Point Feature][geo] | Required | |
273273
| `battery_pct` | Float | Required if Applicable | Percent battery charge of device, expressed between 0 and 1 |
274-
| `associated_trip` | UUID | Required if Applicable | Trip UUID (foreign key to Trips API), required if `event_type` is `trip_start` or `trip_end`, or for any other status change event that marks the end of a trip. |
275-
| `associated_ticket` | String | Optional | Identifier for an associated ticket inside an Agency-maintained 311 or CRM system. |
274+
| `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` |
275+
| `associated_ticket` | String | Optional | Identifier for an associated ticket inside an Agency-maintained 311 or CRM system |
276276

277277
### Status Changes Query Parameters
278278

@@ -396,7 +396,7 @@ In addition to the standard [Provider payload wrapper](#response-format), respon
396396
| `device_id` | UUID | Required | A unique device ID in UUID format, should match this device in Provider |
397397
| `vehicle_id` | String | Required | The Vehicle Identification Number visible on the vehicle itself, should match this device in provider |
398398
| `vehicle_type` | Enum | Required | see [vehicle types][vehicle-types] table |
399-
| `propulsion_type` | Enum[] | Required | Array of [propulsion types][propulsion-types]; allows multiple values |
399+
| `propulsion_types` | Enum[] | Required | Array of [propulsion types][propulsion-types]; allows multiple values |
400400
| `last_event_time` | [timestamp][ts] | Required | Date/time when last state change occurred. See [Event Times][event-times] |
401401
| `last_vehicle_state` | Enum | Required | Vehicle state of most recent state change. See [vehicle states][vehicle-states] table |
402402
| `last_vehicle_events` | Enum[] | Required | [Vehicle event(s)][vehicle-events] of most recent state change, allowable values determined by `last_vehicle_state`. |

0 commit comments

Comments
 (0)