Skip to content

Commit afaaedb

Browse files
schnuerleschnuerle
authored
Merge pull request #718 from compilerla/schemas/geography
1.2.0 schemas: geography
2 parents 70e36a1 + 8f65f3e commit afaaedb

17 files changed

Lines changed: 578 additions & 1102 deletions

‎geography/README.md‎

Lines changed: 37 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -11,12 +11,12 @@ Geographical data will be stored as GeoJSON and read from either `geographies.js
1111
## Table of Contents
1212

1313
* [General Information](#general-information)
14-
* [Versioning](#versioning)
15-
* [Transition from Policy](#transition-from-policy)
14+
* [Versioning](#versioning)
15+
* [Transition from Policy](#transition-from-policy)
1616
* [Distribution](#distribution)
17-
* [Flat Files](#flat-files)
18-
* [Response Format](#response-format)
19-
* [Authorization](#authorization)
17+
* [Flat Files](#flat-files)
18+
* [Response Format](#response-format)
19+
* [Authorization](#authorization)
2020
* [Schema](#schema)
2121
* [Geography Fields](#geography-fields)
2222
* [Previous Geographies](#previous-geographies)
@@ -45,7 +45,7 @@ Versioning must be implemented as specified in the [Versioning section][versioni
4545

4646
To ensure this Geography API is not creating a breaking change for the 1.1.0 release, it's expected that the data contained in the [`/geographies`](/policy#geography) endpoint in the Policy API is identical to this Geography API. This will ensure that when a Geography ID is used anywhere in this release, the data could be retrieved from either location.
4747

48-
This temporary requirement is to ensure backwards compatibility, but the overall intent is to remove the /policy/geographies endpoint at the next major MDS release.
48+
This temporary requirement is to ensure backwards compatibility, but the overall intent is to remove the /policy/geographies endpoint at the next major MDS release.
4949

5050
[Top][toc]
5151

@@ -65,7 +65,7 @@ Geographies should be re-fetched at an agreed upon interval between providers an
6565

6666
To use a flat file, geographies shall be represented in one (1) file equivalent to the /geographies endpoint:
6767

68-
- `geographies.json`
68+
* `geographies.json`
6969

7070
The files shall be structured like the output of the [REST endpoints](#rest-endpoints) above.
7171

@@ -89,7 +89,7 @@ Authorization is not required. An agency may decide to make this endpoint unauth
8989

9090
## Schema
9191

92-
Link to schema will be defined and added in a future release.
92+
See the [Endpoints](#endpoints) below for links to their specific JSON Schema documents.
9393

9494
[Top][toc]
9595

@@ -115,6 +115,8 @@ Obsoleting or otherwise changing a geography is accomplished by publishing a new
115115

116116
This field is optional can be omitted by the publishing Agency.
117117

118+
[Top][toc]
119+
118120
### Geography Type
119121

120122
Type of geography. These specific types are recommendations based on ones commonly defined by agencies. Others may be created by the Agency as needed, or the optional `geography_type` field may be omitted.
@@ -148,16 +150,17 @@ Type of geography. These specific types are recommendations based on ones common
148150
Note: to use flat files rather than REST endpoints, Geography objects should be stored in `geographies.json`. The `geographies.json` file will look like the output of `GET /geographies`.
149151

150152
Example `geographies.json`
151-
```json
153+
154+
```jsonc
152155
{
153-
"version": "1.1.0",
156+
"version": "1.2.0",
154157
"updated": "1570035222868",
155158
"geographies": [
156159
{
157-
// GeoJSON 1
160+
// Geography 1
158161
},
159162
{
160-
// GeoJSON 2
163+
// Geography 2
161164
}
162165
]
163166
}
@@ -173,26 +176,26 @@ The Geography Author API consists of the following endpoints:
173176

174177
### Geography
175178

176-
**Endpoint**: `/geographies/{geography_id}`
177-
178-
**Method**: `GET`
179+
**Endpoint**: `/geographies/{geography_id}`
180+
**Method**: `GET`
181+
**Schema:** [`geography` schema](./geography.json)
179182

180-
Path Params:
183+
#### Query Parameters
181184

182185
| Name | Type | Required/Optional | Description |
183186
| ------------- | ---- | --- | --------------------------------------------------- |
184-
| geography_id | UUID | Required | Unique identifier for a single specific Geography |
187+
| `geography_id` | UUID | Required | Unique identifier for a single specific Geography |
185188

186-
Returns: Details of a single Geography based on a UUID.
189+
Returns: Details of a single Geography based on a UUID.
187190

188191
Response body:
189192

190193
```js
191194
{
192-
"version": '1.1.0',
195+
"version": '1.2.0',
193196
"geography": {
194197
"geography_id": UUID,
195-
"geography_type": Enum,
198+
"geography_type": string,
196199
"name": string,
197200
"description": string,
198201
"published_date": timestamp,
@@ -204,31 +207,27 @@ Response body:
204207
```
205208

206209
Response codes:
207-
- 200 - success
208-
- 401 - unauthorized
209-
- 404 - no geography found
210-
- 403 - user is attempting to read an unpublished geography, but only has the `geographies:read:published` scope.
210+
211+
* 200 - success
212+
* 401 - unauthorized
213+
* 404 - no geography found
214+
* 403 - user is attempting to read an unpublished geography, but only has the `geographies:read:published` scope.
211215

212216
[Top][toc]
213217

214218
### Geographies
215219

216-
**Endpoint**: `/geographies`
217-
218-
**Method**: `GET`
219-
220-
Path Params:
221-
222-
| Name | Type | Required/Optional | Description |
223-
| ------------ | --------- | --- | ---------------------------------------------- |
224-
| `summary` | string | Optional | Return geographies, including the GeoJSON in each geography object |
220+
**Endpoint**: `/geographies`
221+
**Method**: `GET`
222+
**Schema:** [`geographies` schema](./geographies.json)
225223

226224
Returns: All geography objects
227225

228226
Response body:
229-
```js
227+
228+
```jsonc
230229
{
231-
"version": "1.1.0",
230+
"version": "1.2.0",
232231
"updated": "1570035222868",
233232
"geographies": [
234233
{
@@ -242,8 +241,9 @@ Response body:
242241
```
243242

244243
Response codes:
245-
- 200 - success
246-
- 401 - unauthorized
244+
245+
* 200 - success
246+
* 401 - unauthorized
247247

248248
[Top][toc]
249249

‎geography/examples/README.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ Shows the muncipal boundaries of a regulating entity, which may be larger than t
3232

3333
```json
3434
{
35-
"version": "1.0.0",
35+
"version": "1.2.0",
3636
"geography": {
3737
"geography_id": "e00535dd-d8ff-4b1b-920d-34e7404d0208",
3838
"geography_type": "municipal_boundary",
@@ -60,7 +60,7 @@ Boundaries of a city's permitted operating area for provider vehicles.
6060

6161
```json
6262
{
63-
"version": "1.0.0",
63+
"version": "1.2.0",
6464
"geography": {
6565
"geography_id": "8ad39dc3-005b-4348-9d61-c830c54c161b",
6666
"geography_type": "operating_area",
@@ -89,7 +89,7 @@ Boundaries of one of 9 areas in a city where vehicles can be distibuted and rebl
8989

9090
```json
9191
{
92-
"version": "1.0.0",
92+
"version": "1.2.0",
9393
"geography": {
9494
"geography_id": "70a91abc-0d9f-43a9-8e6a-763142dc6c94",
9595
"geography_type": "distribution_zone",
@@ -119,7 +119,7 @@ Boundaries of areas in a city where vehicles are not allowed be ridden by riders
119119

120120
```json
121121
{
122-
"version": "1.0.0",
122+
"version": "1.2.0",
123123
"geography": {
124124
"geography_id": "fc277865-79d3-4f0e-8459-53e9a647db99",
125125
"geography_type": "slow_ride_zone",
@@ -144,7 +144,7 @@ Boundaries of areas in a city where vehicles are to be ridden at a slower top sp
144144

145145
```json
146146
{
147-
"version": "1.0.0",
147+
"version": "1.2.0",
148148
"geography": {
149149
"geography_id": "8ad39dc3-005b-4348-9d61-c830c54c161b",
150150
"geography_type": "operating_area",
@@ -174,7 +174,7 @@ Designated stoping areas for vehicles. In this example the recommended parking l
174174

175175
```json
176176
{
177-
"version": "1.0.0",
177+
"version": "1.2.0",
178178
"geography": {
179179
"geography_id": "d1328cdb-92fe-4267-85e0-a9fe5653268e",
180180
"geography_type": "stop",

‎geography/examples/distribution-zone-8.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
2-
"version": "1.0.0",
2+
"version": "1.2.0",
33
"geography": {
44
"geography_id": "70a91abc-0d9f-43a9-8e6a-763142dc6c94",
55
"geography_type": "distribution_zone",

‎geography/examples/geographies.json‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
{
2-
"version": "1.1.0",
2+
"version": "1.2.0",
33
"updated": "1570035222868",
44
"geographies": [
55
{
6-
"version": "1.0.0",
6+
"version": "1.2.0",
77
"geography": {
88
"geography_id": "e00535dd-d8ff-4b1b-920d-34e7404d0208",
99
"geography_type": "municipal_boundary",
@@ -208,7 +208,7 @@
208208
}
209209
},
210210
{
211-
"version": "1.0.0",
211+
"version": "1.2.0",
212212
"geography": {
213213
"geography_id": "8ad39dc3-005b-4348-9d61-c830c54c161b",
214214
"geography_type": "operating_area",
@@ -15450,7 +15450,7 @@
1545015450
}
1545115451
},
1545215452
{
15453-
"version": "1.0.0",
15453+
"version": "1.2.0",
1545415454
"geography": {
1545515455
"geography_id": "70a91abc-0d9f-43a9-8e6a-763142dc6c94",
1545615456
"geography_type": "distribution_zone",
@@ -17290,7 +17290,7 @@
1729017290
}
1729117291
},
1729217292
{
17293-
"version": "1.0.0",
17293+
"version": "1.2.0",
1729417294
"geography": {
1729517295
"geography_id": "e00535dd-d8ff-4b1b-920d-34e7404d0208",
1729617296
"geography_type": "no_ride_zone",
@@ -17844,7 +17844,7 @@
1784417844
}
1784517845
},
1784617846
{
17847-
"version": "1.0.0",
17847+
"version": "1.2.0",
1784817848
"geography": {
1784917849
"geography_id": "fc277865-79d3-4f0e-8459-53e9a647db99",
1785017850
"geography_type": "slow_ride_zone",
@@ -19855,7 +19855,7 @@
1985519855
}
1985619856
},
1985719857
{
19858-
"version": "1.0.0",
19858+
"version": "1.2.0",
1985919859
"geography": {
1986019860
"geography_id": "d1328cdb-92fe-4267-85e0-a9fe5653268e",
1986119861
"geography_type": "stop",
@@ -20001,4 +20001,4 @@
2000120001
}
2000220002
}
2000320003
]
20004-
}
20004+
}

‎geography/examples/municipal-boundary.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
2-
"version": "1.0.0",
2+
"version": "1.2.0",
33
"geography": {
44
"geography_id": "e00535dd-d8ff-4b1b-920d-34e7404d0208",
55
"geography_type": "municipal_boundary",
@@ -202,4 +202,4 @@
202202
]
203203
}
204204
}
205-
}
205+
}

‎geography/examples/no-ride-zone.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
2-
"version": "1.0.0",
2+
"version": "1.2.0",
33
"geography": {
44
"geography_id": "e00535dd-d8ff-4b1b-920d-34e7404d0208",
55
"geography_type": "no_ride_zone",
@@ -551,4 +551,4 @@
551551
]
552552
}
553553
}
554-
}
554+
}

‎geography/examples/operating-area.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
2-
"version": "1.0.0",
2+
"version": "1.2.0",
33
"geography": {
44
"geography_id": "8ad39dc3-005b-4348-9d61-c830c54c161b",
55
"geography_type": "operating_area",

‎geography/examples/slow-ride-zone.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
2-
"version": "1.0.0",
2+
"version": "1.2.0",
33
"geography": {
44
"geography_id": "fc277865-79d3-4f0e-8459-53e9a647db99",
55
"geography_type": "slow_ride_zone",
@@ -2008,4 +2008,4 @@
20082008
]
20092009
}
20102010
}
2011-
}
2011+
}

‎geography/examples/stop.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
2-
"version": "1.0.0",
2+
"version": "1.2.0",
33
"geography": {
44
"geography_id": "d1328cdb-92fe-4267-85e0-a9fe5653268e",
55
"geography_type": "stop",
@@ -143,4 +143,4 @@
143143
]
144144
}
145145
}
146-
}
146+
}

0 commit comments

Comments
 (0)