Skip to content

Commit faa89bd

Browse files
thekavemanthekaveman
committed
adding Agency GET /stops schema
1 parent 8cae5a4 commit faa89bd

4 files changed

Lines changed: 344 additions & 4 deletions

File tree

‎agency/README.md‎

Lines changed: 43 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@ Path Params:
5757

5858
200 Success Response:
5959

60-
If `device_id` is specified, `GET` will return a single vehicle record, otherwise it will be a list of vehicle records with pagination details per the [JSON API](https://jsonapi.org/format/#fetching-pagination) spec:
60+
If `device_id` is specified, `GET` will return an array with a single vehicle record, otherwise it will be a list of vehicle records with pagination details per the [JSON API](https://jsonapi.org/format/#fetching-pagination) spec:
6161

6262
```json
6363
{
@@ -263,6 +263,23 @@ The `/stops` endpoint allows an agency to register city-managed Stops, or a prov
263263
**[Beta feature][beta]:** Yes (as of 1.0.0)
264264
**Request Body**: An array of [Stops][stops]
265265

266+
201 Success Response:
267+
268+
_No content returned on success._
269+
270+
400 Failure Response:
271+
272+
| `error` | `error_description` | `error_details`[] |
273+
| -------------------- | ------------------------------------------------- | ------------------------------- |
274+
| `bad_param` | A validation error occurred. | Array of parameters with errors |
275+
| `missing_param` | A required parameter is missing. | Array of missing parameters |
276+
277+
409 Failure Response:
278+
279+
| `error` | `error_description` | `error_details`[] |
280+
| -------------------- | ------------------------------------------------- | ------------------------------- |
281+
| `already_registered` | A stop with `stop_id` is already registered | |
282+
266283
**Endpoint:** `/stops`
267284
**Method:** `PUT`
268285
**[Beta feature][beta]:** Yes (as of 1.0.0)
@@ -274,12 +291,35 @@ The `/stops` endpoint allows an agency to register city-managed Stops, or a prov
274291
| status | Optional |See [Stops][stops] |
275292
| num_spots_disabled | Optional |See [Stops][stops] |
276293

294+
200 Success Response:
295+
296+
_No content returned on success._
297+
298+
400 Failure Response:
299+
300+
| `error` | `error_description` | `error_details`[] |
301+
| -------------------- | ------------------------------------------------- | ------------------------------- |
302+
| `bad_param` | A validation error occurred. | Array of parameters with errors |
303+
| `missing_param` | A required parameter is missing. | Array of missing parameters |
304+
305+
404 Failure Response:
306+
307+
_No content returned if no vehicle matching `stop_id` is found._
308+
277309
**Endpoint:** `/stops/:stop_id`
278310
**Method:** `GET`
279311
**[Beta feature][beta]:** Yes (as of 1.0.0)
280-
**`data` Payload:** `{ "stops": [] }`, an array of [Stops][stops]
312+
**Payload:** `{ "stops": [] }`, an array of [Stops][stops]
313+
314+
Path Params:
315+
316+
| Param | Type | Required/Optional | Description |
317+
| ------------ | ---- | ----------------- | ------------------------------------------- |
318+
| `stop_id` | UUID | Optional | If provided, retrieve the specified stop |
319+
320+
200 Success Response:
281321

282-
In the case that a `stop_id` query parameter is specified, the `stops` array returned will only have one entry. In the case that no `stop_id` query parameter is specified, all stops will be returned.
322+
If `stop_id` is specified, `GET` will return an array with a single stop record, otherwise it will be a list of all stop records.
283323

284324
[Top][toc]
285325

‎agency/get_stops.json‎

Lines changed: 263 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,263 @@
1+
{
2+
"$id": "https://raw.githubusercontent.com/openmobilityfoundation/mobility-data-specification/main/agency/get_stops.json",
3+
"$schema": "http://json-schema.org/draft-06/schema#",
4+
"title": "The MDS Agency Schema, GET stops payload",
5+
"type": "object",
6+
"definitions": {
7+
"stop": {
8+
"$id": "#/definitions/stop",
9+
"type": "object",
10+
"description": "The common schema elements for a Stop in MDS",
11+
"required": [
12+
"stop_id",
13+
"name",
14+
"last_reported",
15+
"location",
16+
"status",
17+
"capacity",
18+
"num_vehicles_available",
19+
"num_vehicles_disabled"
20+
],
21+
"properties": {
22+
"stop_id": {
23+
"$id": "#/definitions/stop/properties/stop_id",
24+
"$ref": "#/definitions/uuid",
25+
"description": "UUID for the Stop"
26+
},
27+
"name": {
28+
"$id": "#/definitions/stop/properties/name",
29+
"$ref": "#/definitions/string",
30+
"description": "Name of the Stop"
31+
},
32+
"last_reported": {
33+
"$id": "#/definitions/stop/properties/last_reported",
34+
"$ref": "#/definitions/timestamp",
35+
"description": "Date/Time of the last status update for this Stop"
36+
},
37+
"location": {
38+
"$id": "#/definitions/stop/properties/location",
39+
"$ref": "#/definitions/MDS_Feature_Point",
40+
"description": "Location of the stop"
41+
},
42+
"status": {
43+
"$id": "#/definitions/stop/properties/status",
44+
"$ref": "#/definitions/stop_status",
45+
"description": "The status of the Stop"
46+
},
47+
"capacity": {
48+
"$id": "#/definitions/stop/properties/capacity",
49+
"$ref": "#/definitions/vehicle_type_counts",
50+
"description": "Number of total spaces per vehicle_type"
51+
},
52+
"num_vehicles_available": {
53+
"$id": "#/definitions/stop/properties/num_vehicles_available",
54+
"$ref": "#/definitions/vehicle_type_counts",
55+
"description": "Number of available vehicles per vehicle_type"
56+
},
57+
"num_vehicles_disabled": {
58+
"$id": "#/definitions/stop/properties/num_vehicles_disabled",
59+
"$ref": "#/definitions/vehicle_type_counts",
60+
"description": "Number of non_operational/reserved vehicles per vehicle_type"
61+
},
62+
"provider_id": {
63+
"$id": "#/definitions/stop/properties/provider_id",
64+
"$ref": "#/definitions/uuid",
65+
"description": "UUID for the Provider managing this Stop. Null/undefined if managed by an Agency."
66+
},
67+
"geography_id": {
68+
"$id": "#/definitions/stop/properties/geography_id",
69+
"$ref": "#/definitions/uuid",
70+
"description": "UUID for the Stop"
71+
},
72+
"region_id": {
73+
"$id": "#/definitions/stop/properties/region_id",
74+
"$ref": "#/definitions/string",
75+
"description": "ID of the region where the Stop is located. See GBFS Station Information."
76+
},
77+
"short_name": {
78+
"$id": "#/definitions/stop/properties/short_name",
79+
"$ref": "#/definitions/string",
80+
"description": "Abbreviated Stop name"
81+
},
82+
"address": {
83+
"$id": "#/definitions/stop/properties/address",
84+
"$ref": "#/definitions/string",
85+
"description": "Postal address (useful for directions)"
86+
},
87+
"post_code": {
88+
"$id": "#/definitions/stop/properties/post_code",
89+
"$ref": "#/definitions/string",
90+
"description": "Postal code (e.g. 10036)"
91+
},
92+
"cross_street": {
93+
"$id": "#/definitions/stop/properties/cross_street",
94+
"$ref": "#/definitions/string",
95+
"description": "Cross street of where Stop is located"
96+
},
97+
"num_spaces_available": {
98+
"$id": "#/definitions/stop/properties/num_spaces_available",
99+
"$ref": "#/definitions/vehicle_type_counts",
100+
"description": "Number of spaces free to be populated per vehicle_type"
101+
},
102+
"num_spaces_disabled": {
103+
"$id": "#/definitions/stop/properties/num_spaces_disabled",
104+
"$ref": "#/definitions/vehicle_type_counts",
105+
"description": "Number of spaces disabled an unable to accept vehicles per vehicle_type"
106+
},
107+
"parent_stop": {
108+
"$id": "#/definitions/stop/properties/parent_stop",
109+
"$ref": "#/definitions/uuid",
110+
"description": "Describe a basic hierarchy of Stops (e.g. a Stop inside a greater Stop)"
111+
},
112+
"devices": {
113+
"$id": "#/definitions/stop/properties/devices",
114+
"type": "array",
115+
"description": "List of device_id for vehicles currently at this Stop.",
116+
"items": {
117+
"$ref": "#/definitions/uuid"
118+
}
119+
}
120+
}
121+
},
122+
"stop_status": {
123+
"$id": "#/definitions/stop_status",
124+
"type": "object",
125+
"description": "Status object for a Stop in MDS",
126+
"required": [
127+
"is_installed",
128+
"is_renting",
129+
"is_returning"
130+
],
131+
"properties": {
132+
"is_installed": {
133+
"$id": "#/definitions/stop_status/properties/is_installed",
134+
"type": "boolean"
135+
},
136+
"is_renting": {
137+
"$id": "#/definitions/stop_status/properties/is_renting",
138+
"type": "boolean"
139+
},
140+
"is_returning": {
141+
"$id": "#/definitions/stop_status/properties/is_returning",
142+
"type": "boolean"
143+
}
144+
}
145+
},
146+
"string": {
147+
"$id": "#/definitions/string",
148+
"type": "string",
149+
"description": "A length-limited string type",
150+
"maxLength": 255,
151+
"default": "",
152+
"examples": [
153+
"ABC123"
154+
],
155+
"pattern": "^(.*)$"
156+
},
157+
"timestamp": {
158+
"$id": "#/definitions/timestamp",
159+
"type": "number",
160+
"description": "Integer milliseconds since Unix epoch",
161+
"multipleOf": 1.0,
162+
"minimum": 0
163+
},
164+
"uuid": {
165+
"$id": "#/definitions/uuid",
166+
"type": "string",
167+
"description": "A UUID used to uniquely identifty an object",
168+
"default": "",
169+
"examples": [
170+
"3c9604d6-b5ee-11e8-96f8-529269fb1459"
171+
],
172+
"pattern": "^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$"
173+
},
174+
"vehicle_type_counts": {
175+
"$id": "#/definitions/vehicle_type_counts",
176+
"type": "object",
177+
"properties": {
178+
"bicycle": {
179+
"$id": "#/definitions/vehicle_type_counts/properties/bicycle",
180+
"type": "integer",
181+
"minimum": 0
182+
},
183+
"car": {
184+
"$id": "#/definitions/vehicle_type_counts/properties/car",
185+
"type": "integer",
186+
"minimum": 0
187+
},
188+
"scooter": {
189+
"$id": "#/definitions/vehicle_type_counts/properties/scooter",
190+
"type": "integer",
191+
"minimum": 0
192+
},
193+
"moped": {
194+
"$id": "#/definitions/vehicle_type_counts/properties/moped",
195+
"type": "integer",
196+
"minimum": 0
197+
},
198+
"other": {
199+
"$id": "#/definitions/vehicle_type_counts/properties/other",
200+
"type": "integer",
201+
"minimum": 0
202+
}
203+
},
204+
"additionalProperties": false
205+
},
206+
"MDS_Feature_Point": {
207+
"$id": "#/definitions/MDS_Feature_Point",
208+
"title": "MDS GeoJSON Feature Point",
209+
"type": "object",
210+
"required": [
211+
"type",
212+
"properties",
213+
"geometry"
214+
],
215+
"properties": {
216+
"type": {
217+
"type": "string",
218+
"enum": [
219+
"Feature"
220+
]
221+
},
222+
"properties": {
223+
"type": "object",
224+
"required": [
225+
"timestamp"
226+
],
227+
"properties": {
228+
"timestamp": {
229+
"$ref": "#/definitions/timestamp"
230+
},
231+
"stop_id": {
232+
"$ref": "#/definitions/uuid"
233+
}
234+
}
235+
},
236+
"geometry": {
237+
"$ref": "#/definitions/Point"
238+
},
239+
"bbox": {
240+
"type": "array",
241+
"minItems": 4,
242+
"items": {
243+
"type": "number"
244+
}
245+
}
246+
}
247+
}
248+
},
249+
"required": [
250+
"stops"
251+
],
252+
"properties": {
253+
"stops": {
254+
"$id": "#/properties/stops",
255+
"type": "array",
256+
"description": "The array of stops",
257+
"items": {
258+
"$ref": "#/definitions/stop"
259+
}
260+
}
261+
},
262+
"additionalProperties": false
263+
}

‎schema/generate_schemas.py‎

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -352,6 +352,21 @@ def agency_put_stops_schema(common_definitions):
352352
return schema
353353

354354

355+
def agency_get_stops_schema(common_definitions):
356+
"""
357+
Create the schema for the Agency GET /stops endpoint.
358+
"""
359+
# load schema template and insert definitions
360+
schema = load_json("./templates/agency/get_stops.json")
361+
stops = stop_definitions(common_definitions)
362+
schema["definitions"].update(stops)
363+
364+
# verify schema validity
365+
jsonschema.Draft6Validator.check_schema(schema)
366+
367+
return schema
368+
369+
355370
def write_agency_schemas(common_definitions):
356371
"""
357372
Create each of the Agency endpoint schema files in the appropriate directory.
@@ -364,7 +379,8 @@ def write_agency_schemas(common_definitions):
364379
"post_vehicle_event": agency_post_vehicle_event_schema,
365380
"post_vehicle_telemetry": agency_post_vehicle_telemetry_schema,
366381
"post_stops": agency_post_stops_schema,
367-
"put_stops": agency_put_stops_schema
382+
"put_stops": agency_put_stops_schema,
383+
"get_stops": agency_get_stops_schema
368384
}
369385

370386
for name, generator in schema_generators.items():

‎schema/templates/agency/get_stops.json‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
{
2+
"$id": "https://raw.githubusercontent.com/openmobilityfoundation/mobility-data-specification/main/agency/get_stops.json",
3+
"$schema": "http://json-schema.org/draft-06/schema#",
4+
"title": "The MDS Agency Schema, GET stops payload",
5+
"type": "object",
6+
"definitions": {},
7+
"required": [
8+
"stops"
9+
],
10+
"properties": {
11+
"stops": {
12+
"$id": "#/properties/stops",
13+
"type": "array",
14+
"description": "The array of stops",
15+
"items": {
16+
"$ref": "#/definitions/stop"
17+
}
18+
}
19+
},
20+
"additionalProperties": false
21+
}

0 commit comments

Comments
 (0)