Skip to content

Commit e97e17a

Browse files
thekavemanthekaveman
authored
Schema fixes/updates (#458)
* correct path in schema ids * improve titles * correct $id format * trips and status_changes do not support paging * generate events schema from status_changes * link to events schema * vehicles allow paging
1 parent 5306eda commit e97e17a

10 files changed

Lines changed: 340 additions & 42 deletions

File tree

‎provider/README.md‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -76,10 +76,10 @@ MDS defines [JSON Schema](https://json-schema.org/) files for [`trips`][trips-sc
7676

7777
### Pagination
7878

79-
The `/trips` and `/status_changes` APIs must not use pagination.
80-
If providers choose to use pagination for the `/events` endpoint the pagination
81-
must comply with the [JSON API](http://jsonapi.org/format/#fetching-pagination)
82-
specification.
79+
The `/trips` and `/status_changes` endpoints must not use pagination.
80+
81+
If providers choose to use pagination for either of the `/events` or `/vehicles` endpoints, the pagination
82+
must comply with the [JSON API](http://jsonapi.org/format/#fetching-pagination) specification.
8383

8484
The following keys must be used for pagination links:
8585

@@ -376,7 +376,7 @@ The schema and datatypes are the same as those defined for [`/status_changes`][s
376376
**Endpoint:** `/events`
377377
**Method:** `GET`
378378
**Required/Optional:** Optional starting with `0.4.0`, moving to Required in a future version (`0.5.0`+)
379-
**Schema:** [`status_changes` schema][sc-schema]
379+
**Schema:** [`events` schema][events-schema]
380380
**`data` Payload:** `{ "status_changes": [] }`, an array of objects with the same structure as in [`/status_changes`][status]
381381

382382
#### Event Times
@@ -445,6 +445,7 @@ ttl | Yes | Integer representing the number of millisecond
445445

446446
[general-information/versioning]: /general-information.md#versioning
447447
[geo]: #geographic-data
448+
[events-schema]: dockless/events.json
448449
[sc-schema]: dockless/status_changes.json
449450
[status]: #status-changes
450451
[toc]: #table-of-contents

‎provider/dockless/events.json‎

Lines changed: 294 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,294 @@
1+
{
2+
"$id": "https://raw.githubusercontent.com/openmobilityfoundation/mobility-data-specification/master/provider/dockless/events.json",
3+
"$schema": "http://json-schema.org/draft-06/schema#",
4+
"title": "The MDS Provider Schema, events payload",
5+
"type": "object",
6+
"definitions": {
7+
"links": {
8+
"$id": "#/definitions/links",
9+
"type": "object",
10+
"required": [
11+
"next"
12+
],
13+
"properties": {
14+
"first": {
15+
"$id": "#/definitions/links/first",
16+
"type": [
17+
"null",
18+
"string"
19+
],
20+
"title": "The URL to the first page of data",
21+
"examples": [
22+
"https://data.provider.co/trips/first"
23+
],
24+
"format": "uri"
25+
},
26+
"last": {
27+
"$id": "#/definitions/links/last",
28+
"type": [
29+
"null",
30+
"string"
31+
],
32+
"title": "The URL to the last page of data",
33+
"examples": [
34+
"https://data.provider.co/trips/last"
35+
],
36+
"format": "uri"
37+
},
38+
"prev": {
39+
"$id": "#/definitions/links/prev",
40+
"type": [
41+
"null",
42+
"string"
43+
],
44+
"title": "The URL to the previous page of data",
45+
"examples": [
46+
"https://data.provider.co/trips/prev"
47+
],
48+
"format": "uri"
49+
},
50+
"next": {
51+
"$id": "#/definitions/links/next",
52+
"type": [
53+
"null",
54+
"string"
55+
],
56+
"title": "The URL to the next page of data",
57+
"examples": [
58+
"https://data.provider.co/trips/next"
59+
],
60+
"format": "uri",
61+
"pattern": "^(.*)$"
62+
}
63+
},
64+
"additionalProperties": false
65+
}
66+
},
67+
"required": [
68+
"version",
69+
"data"
70+
],
71+
"properties": {
72+
"version": {
73+
"$id": "#/properties/version",
74+
"$ref": "#/definitions/version"
75+
},
76+
"data": {
77+
"$id": "#/properties/data",
78+
"type": "object",
79+
"title": "The page of data",
80+
"required": [
81+
"status_changes"
82+
],
83+
"properties": {
84+
"status_changes": {
85+
"$id": "#/properties/data/properties/status_changes",
86+
"type": "array",
87+
"title": "The status_changes payload",
88+
"items": {
89+
"$id": "#/properties/data/properties/status_changes/items",
90+
"type": "object",
91+
"title": "The status_change item schema",
92+
"required": [
93+
"provider_name",
94+
"provider_id",
95+
"device_id",
96+
"vehicle_id",
97+
"vehicle_type",
98+
"propulsion_type",
99+
"event_type",
100+
"event_type_reason",
101+
"event_time",
102+
"event_location"
103+
],
104+
"properties": {
105+
"provider_name": {
106+
"$id": "#/properties/data/properties/status_changes/items/properties/provider_name",
107+
"type": "string",
108+
"description": "The public-facing name of the Provider",
109+
"examples": [
110+
"Provider Name"
111+
],
112+
"pattern": "^(.*)$"
113+
},
114+
"provider_id": {
115+
"$id": "#/properties/data/properties/status_changes/items/properties/provider_id",
116+
"description": "The UUID for the Provider, unique within MDS",
117+
"$ref": "#/definitions/uuid"
118+
},
119+
"device_id": {
120+
"$id": "#/properties/data/properties/status_changes/items/properties/device_id",
121+
"description": "A unique device ID in UUID format",
122+
"$ref": "#/definitions/uuid"
123+
},
124+
"vehicle_id": {
125+
"$id": "#/properties/data/properties/status_changes/items/properties/vehicle_id",
126+
"type": "string",
127+
"description": "The Vehicle Identification Number visible on the vehicle itself",
128+
"default": "",
129+
"examples": [
130+
"ABC123"
131+
],
132+
"pattern": "^(.*)$"
133+
},
134+
"vehicle_type": {
135+
"$id": "#/properties/data/properties/status_changes/items/properties/vehicle_type",
136+
"$ref": "#/definitions/vehicle_type",
137+
"description": "The type of vehicle"
138+
},
139+
"propulsion_type": {
140+
"$id": "#/properties/data/properties/status_changes/items/properties/propulsion_type",
141+
"description": "The type of propulsion; allows multiple values",
142+
"$ref": "#/definitions/propulsion_type"
143+
},
144+
"event_time": {
145+
"$id": "#/properties/data/properties/status_changes/items/properties/event_time",
146+
"description": "The time the event occurred, expressed as a Unix Timestamp",
147+
"$ref": "#/definitions/timestamp"
148+
},
149+
"publication_time": {
150+
"$id": "#/properties/data/properties/status_changes/items/properties/publication_time",
151+
"description": "The time the event became available through the status changes endpoint, expressed as a Unix Timestamp",
152+
"$ref": "#/definitions/timestamp"
153+
},
154+
"event_location": {
155+
"$id": "#/properties/data/properties/status_changes/items/properties/event_location",
156+
"description": "The GPS or GNSS coordinates of where the event occurred",
157+
"$ref": "#/definitions/MDS_Feature_Point"
158+
},
159+
"event_type": {
160+
"type": "string",
161+
"description": "The type of the event"
162+
},
163+
"event_type_reason": {
164+
"type": "string",
165+
"description": "The reason for the event"
166+
},
167+
"battery_pct": {
168+
"$id": "#/properties/data/properties/status_changes/items/properties/battery_pct",
169+
"type": [
170+
"number",
171+
"null"
172+
],
173+
"description": "Percent charge of device battery, expressed between 0 and 1",
174+
"examples": [
175+
0.89
176+
],
177+
"minimum": 0,
178+
"maximum": 1
179+
},
180+
"associated_trip": {
181+
"$id": "#/properties/data/properties/status_changes/items/properties/associated_trip",
182+
"description": "Trip UUID, required if event_type_reason is user_pick_up or user_drop_off",
183+
"$ref": "#/definitions/uuid"
184+
},
185+
"associated_ticket": {
186+
"type": "string",
187+
"description": "Identifier for an associated ticket inside an Agency-maintained 311 or CRM system."
188+
}
189+
},
190+
"allOf": [
191+
{
192+
"description": "valid event_type and event_type_reason combinations",
193+
"oneOf": [
194+
{
195+
"properties": {
196+
"event_type": {
197+
"enum": [
198+
"available"
199+
]
200+
},
201+
"event_type_reason": {
202+
"enum": [
203+
"service_start",
204+
"user_drop_off",
205+
"rebalance_drop_off",
206+
"maintenance_drop_off",
207+
"agency_drop_off"
208+
]
209+
}
210+
}
211+
},
212+
{
213+
"properties": {
214+
"event_type": {
215+
"enum": [
216+
"reserved"
217+
]
218+
},
219+
"event_type_reason": {
220+
"enum": [
221+
"user_pick_up"
222+
]
223+
}
224+
}
225+
},
226+
{
227+
"properties": {
228+
"event_type": {
229+
"enum": [
230+
"unavailable"
231+
]
232+
},
233+
"event_type_reason": {
234+
"enum": [
235+
"low_battery",
236+
"maintenance"
237+
]
238+
}
239+
}
240+
},
241+
{
242+
"properties": {
243+
"event_type": {
244+
"enum": [
245+
"removed"
246+
]
247+
},
248+
"event_type_reason": {
249+
"enum": [
250+
"service_end",
251+
"rebalance_pick_up",
252+
"maintenance_pick_up",
253+
"agency_pick_up"
254+
]
255+
}
256+
}
257+
}
258+
]
259+
},
260+
{
261+
"description": "conditionally require associated_trip when applicable",
262+
"anyOf": [
263+
{
264+
"not": {
265+
"properties": {
266+
"event_type_reason": {
267+
"enum": [
268+
"user_pick_up",
269+
"user_drop_off"
270+
]
271+
}
272+
}
273+
}
274+
},
275+
{
276+
"required": [
277+
"associated_trip"
278+
]
279+
}
280+
]
281+
}
282+
]
283+
}
284+
}
285+
},
286+
"additionalProperties": false
287+
},
288+
"links": {
289+
"$id": "#/properties/links",
290+
"$ref": "#/definitions/links"
291+
}
292+
},
293+
"additionalProperties": false
294+
}

‎provider/dockless/status_changes.json‎

Lines changed: 3 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
2-
"$id": "https://raw.githubusercontent.com/openmobilityfoundation/mobility-data-specification/master/provider/status_changes.json",
2+
"$id": "https://raw.githubusercontent.com/openmobilityfoundation/mobility-data-specification/master/provider/dockless/status_changes.json",
33
"$schema": "http://json-schema.org/draft-06/schema#",
44
"title": "The MDS Provider Schema, status_change payload",
55
"type": "object",
@@ -216,11 +216,11 @@
216216
"status_changes": {
217217
"$id": "#/properties/data/properties/status_changes",
218218
"type": "array",
219-
"title": "The status_changes Schema",
219+
"title": "The status_changes payload",
220220
"items": {
221221
"$id": "#/properties/data/properties/status_changes/items",
222222
"type": "object",
223-
"title": "The Items Schema",
223+
"title": "The status_change item schema",
224224
"required": [
225225
"provider_name",
226226
"provider_id",
@@ -416,10 +416,6 @@
416416
}
417417
},
418418
"additionalProperties": false
419-
},
420-
"links": {
421-
"$id": "#properties/links",
422-
"$ref": "#/definitions/links"
423419
}
424420
},
425421
"additionalProperties": false

‎provider/dockless/trips.json‎

Lines changed: 3 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
2-
"$id": "https://raw.githubusercontent.com/openmobilityfoundation/mobility-data-specification/master/provider/trips.json",
2+
"$id": "https://raw.githubusercontent.com/openmobilityfoundation/mobility-data-specification/master/provider/dockless/trips.json",
33
"$schema": "http://json-schema.org/draft-06/schema#",
44
"title": "The MDS Provider Schema, trips payload",
55
"type": "object",
@@ -247,11 +247,11 @@
247247
"trips": {
248248
"$id": "#/properties/data/properties/trips",
249249
"type": "array",
250-
"title": "The Trips Schema",
250+
"title": "The trips payload",
251251
"items": {
252252
"$id": "#/properties/data/properties/trips/items",
253253
"type": "object",
254-
"title": "The Trip Schema",
254+
"title": "The trip item schema",
255255
"required": [
256256
"provider_name",
257257
"provider_id",
@@ -410,10 +410,6 @@
410410
}
411411
}
412412
}
413-
},
414-
"links": {
415-
"$id": "#properties/links",
416-
"$ref": "#/definitions/links"
417413
}
418414
},
419415
"additionalProperties": false

0 commit comments

Comments
 (0)