Skip to content

Commit 872ed60

Browse files
jmcanterafonsecajmcanterafonseca
authored
First take. Add Shape Data Model (FIWARE#337)
1 parent 4b66f1f commit 872ed60

File tree

9 files changed

+248
-85
lines changed

9 files changed

+248
-85
lines changed

‎mkdocs.yml

+2-1
Original file line numberDiff line numberDiff line change
@@ -86,7 +86,8 @@ pages:
8686
- GtfsCalendarDateRule : UrbanMobility/GtfsCalendarDateRule/doc/spec.md
8787
- GtfsFrequency : UrbanMobility/GtfsFrequency/doc/spec.md
8888
- GtfsTransferRule : UrbanMobility/GtfsTransferRule/doc/spec.md
89-
- ArrivalEstimation : UrbanMobility/ArrivalEstimation/doc/spec.md
89+
- GtfsShape : UrbanMobility/GtfsShape/doc/spec.md
90+
- ArrivalEstimation : UrbanMobility/ArrivalEstimation/doc/spec.md
9091
- Weather:
9192
- Introduction : Weather/doc/introduction.md
9293
- WeatherObserved : Weather/WeatherObserved/doc/spec.md

‎specs/UrbanMobility/GtfsShape/doc/spec.md

+128
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
# GtfsShape
2+
3+
## Description
4+
5+
See
6+
[https://developers.google.com/transit/gtfs/reference/#shapestxt](https://developers.google.com/transit/gtfs/reference/#shapestxt)
7+
8+
It represents a GTFS `shape`.
9+
10+
## Data Model
11+
12+
The data model is defined as shown below:
13+
14+
- `id`: Entity ID
15+
16+
- It shall be `urn:ngsi-ld:GtfsShape:<shape_identifier>` being
17+
`shape_identifier` a value that can derived from the GTFS `shape_id`
18+
field.
19+
20+
- `type`: Entity Type
21+
22+
- It shall be equal to `GtfsShape`
23+
24+
- `source` : A sequence of characters giving the source of the entity data.
25+
26+
- Attribute type: Text or URL
27+
- Optional
28+
29+
- `dataProvider` : Specifies the URL to information about the provider of this information
30+
31+
- Attribute type: URL
32+
- Optional
33+
34+
- `dateCreated` : Entity's creation timestamp.
35+
36+
- Attribute type: [DateTime](https://schema.org/DateTime)
37+
- Read-Only. Automatically generated.
38+
39+
- `dateModified` : Last update timestamp of this Entity.
40+
41+
- Attribute type: [DateTime](https://schema.org/DateTime)
42+
- Read-Only. Automatically generated.
43+
44+
- `location`: The geographical shape associated to this entity encoded as GeoJSON
45+
`LineString` or `MultiLineString`. The coordinates shall be obtained from
46+
the `shapes.txt` feed file as per the value of `shape_id`, `shape_pt_lat`, `shape_pt_lon`, `shape_pt_sequence`.
47+
48+
- Attribute type: GeoProperty. `geo:json`
49+
- Optional
50+
51+
- `distanceTravelled`: An array of the distance travelled when reaching each of the points that make the `LineString` or `MultiLineString` that represents this shape. It shall match the
52+
same number of elements as the corresponding `LineString` or `MultiLineString`.
53+
54+
- Attribute type: List of Number if the Shape is defined by a `LineString`. List of List of Number if the Shape is defined by a `MultiLineString`.
55+
- Optional
56+
57+
### Example 1 (Normalized Format)
58+
59+
```json
60+
{
61+
"id": "urn:ngsi-ld:GtfsShape:S234",
62+
"type": "GtfsShape",
63+
"location": {
64+
"type": "geo:json",
65+
"value": {
66+
"type": "LineString",
67+
"coordinates": [
68+
[-4.421394, 36.73826],
69+
[-4.421428, 36.73825],
70+
[-4.421505, 36.738186],
71+
[-4.421525, 36.738033]
72+
]
73+
}
74+
},
75+
"distanceTravelled": {
76+
"type": "List",
77+
"value": [
78+
0,
79+
6.10,
80+
9.78
81+
13.45
82+
]
83+
}
84+
}
85+
```
86+
87+
### Example 2 (?options=keyValues simplified representation for data consumers)
88+
89+
```json
90+
{
91+
"id": "urn:ngsi-ld:GtfsShape:S234",
92+
"type": "GtfsShape",
93+
"location": {
94+
"type": "LineString",
95+
"coordinates": [
96+
[-4.421394, 36.73826],
97+
[-4.421428, 36.73825],
98+
[-4.421505, 36.738186],
99+
[-4.421525, 36.738033]
100+
]
101+
},
102+
"distanceTravelled": [
103+
0,
104+
6.10,
105+
9.78
106+
13.45
107+
]
108+
}
109+
```
110+
111+
## Summary of mappings to GTFS
112+
113+
### Properties
114+
115+
| GTFS Field | NGSI Attribute | LinkedGTFS | Comment |
116+
| :-------------------- | :--------------------- | :-------------------------- | :------------------------------------------------------- |
117+
| `shape_pt_lat` | `location` | `geo:lat` | Latitude of points. |
118+
| `shape_pt_lon` | `location` | `geo:long` | Longitude of points. |
119+
| `shape_pt_sequence` | `location` | `gtfs:pointSequence` | Sequence of points. |
120+
| `shape_dist_traveled` | `distanceTravelled` | `gtfs:distanceTravelled` | Distance travelled |
121+
122+
### Relationships
123+
124+
| GTFS Field | NGSI Attribute | LinkedGTFS | Comment |
125+
| :--------------- | :----------------- | :------------------- | :--------------------------------------------------- |
126+
127+
128+
## Open issues

‎specs/UrbanMobility/GtfsShape/example-normalized.json

+28
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
{
2+
"id": "urn:ngsi-ld:GtfsShape:101",
3+
"type": "GtfsShape",
4+
"location": {
5+
"type": "geo:json",
6+
"value": {
7+
"type": "LineString",
8+
"coordinates": [
9+
[
10+
-4.421394,
11+
36.73826
12+
],
13+
[
14+
-4.421428,
15+
36.73825
16+
],
17+
[
18+
-4.421505,
19+
36.738186
20+
],
21+
[
22+
-4.421525,
23+
36.738033
24+
]
25+
]
26+
}
27+
}
28+
}

‎specs/UrbanMobility/GtfsShape/example.json

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
{
2+
"id": "urn:ngsi-ld:GtfsShape:101",
3+
"type": "GtfsShape",
4+
"location": {
5+
"type": "LineString",
6+
"coordinates": [
7+
[-4.421394,36.73826],
8+
[-4.421428,36.73825],
9+
[-4.421505,36.738186],
10+
[-4.421525,36.738033]
11+
]
12+
}
13+
}

‎specs/UrbanMobility/GtfsShape/schema.json

+58
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
{
2+
"$schema": "http://json-schema.org/schema#",
3+
"id": "https://fiware.github.io/dataModels/specs/UrbanMobility/GtfsShape/schema.json",
4+
"title": "NGSI GTFS Schema",
5+
"description": "GTFS Shape",
6+
"type": "object",
7+
"allOf": [
8+
{ "$ref": "https://fiware.github.io/dataModels/common-schema.json#/definitions/GSMA-Commons" },
9+
{
10+
"properties": {
11+
"type": {
12+
"type": "string",
13+
"enum": [
14+
"GtfsShape"
15+
],
16+
"description": "NGSI Entity type"
17+
},
18+
"distanceTravelled": {
19+
"type": "array",
20+
"items": {
21+
"type": "number",
22+
"minimum": 0
23+
},
24+
"minItems": 1
25+
},
26+
"location": {
27+
"type": "object",
28+
"oneOf": [{
29+
"properties": {
30+
"type": {
31+
"type": "string",
32+
"enum": ["LineString"]
33+
},
34+
"coordinates": { "$ref": "http://json-schema.org/geojson/geometry.json#/definitions/lineString" }
35+
}
36+
},
37+
{
38+
"properties": {
39+
"type": {
40+
"type": "string",
41+
"enum": ["MultiLineString"]
42+
},
43+
"coordinates": {
44+
"type": "array",
45+
"items": { "$ref": "http://json-schema.org/geojson/geometry.json#/definitions/lineString" }
46+
}
47+
}
48+
}]
49+
}
50+
}
51+
}
52+
],
53+
"required": [
54+
"id",
55+
"type",
56+
"location"
57+
]
58+
}

‎specs/UrbanMobility/GtfsTrip/doc/spec.md

+11-28
Original file line numberDiff line numberDiff line change
@@ -65,13 +65,12 @@ The data model is defined as shown below:
6565
- Attribute type: Relationship. It shall point to an Entity of Type
6666
[GtfsService](../../GtfsService/doc/spec.md)
6767
- Optional
68+
69+
- `hasShape`: Same as GTFS `shape_id`.
6870

69-
- `location`: The geographical shape associated to the trip encoded as GeoJSON
70-
`LineString` or `MultiLineString`. The coordinates shall be obtained from
71-
the `shapes.txt` feed file as per the value of `shape_id`.
72-
73-
- Attribute type: GeoProperty. `geo:json`
74-
- Optional
71+
- Attribute type: Relationship. It shall point to an Entity of Type
72+
[GtfsShape](../../GtfsShape/doc/spec.md)
73+
- Optional
7574

7675
- `hasRoute`: Same as `route_id`.
7776

@@ -116,17 +115,9 @@ Normalized NGSI response
116115
"type": "Relationship",
117116
"value": "urn:ngsi-ld:GtfsService:Malaga_LAB"
118117
},
119-
"location": {
120-
"type": "geo:json",
121-
"value": {
122-
"type": "LineString",
123-
"coordinates": [
124-
[-4.421394, 36.73826],
125-
[-4.421428, 36.73825],
126-
[-4.421505, 36.738186],
127-
[-4.421525, 36.738033]
128-
]
129-
}
118+
"hasShape": {
119+
"type": "Relationship",
120+
"value": "urn:ngsi-ld:GtfsShape:Shape01"
130121
}
131122
}
132123
```
@@ -142,16 +133,8 @@ Sample uses simplified representation for data consumers `?options=keyValues`
142133
"hasService": "urn:ngsi-ld:GtfsService:Malaga_LAB",
143134
"headSign": "San Andrés",
144135
"direction": "0",
145-
"hasRoute": "urn:ngsi-ld:GtfsRoute:Spain:Malaga:1",
146-
"location": {
147-
"type": "LineString",
148-
"coordinates": [
149-
[-4.421394, 36.73826],
150-
[-4.421428, 36.73825],
151-
[-4.421505, 36.738186],
152-
[-4.421525, 36.738033]
153-
]
154-
}
136+
"hasRoute": "urn:ngsi-ld:gtfs:Route:Spain:Malaga:1",
137+
"hasShape": "urn:ngsi-ld:GtfsShape:Shape01"
155138
}
156139
```
157140

@@ -164,7 +147,6 @@ Sample uses simplified representation for data consumers `?options=keyValues`
164147
| `trip_headsign` | `headSign` | `gtfs:headsign` | |
165148
| `trip_short_name` | `shortName` | `gtfs:shortName` | |
166149
| `direction_id` | `direction` | `gtfs:direction` | |
167-
| `shape_id` | `location` | `gtfs:shape` | Coordinates shall be taken from `shapes.txt` feed file. |
168150
| `block_id` | `block` | `gtfs:block` | |
169151
| `wheelchair_accessible` | `wheelchairAccessible` | `gtfs:wheelchairAccessible` | |
170152
| `bikes_allowed` | `bikesAllowed` | `gtfs:bikesAllowed` | |
@@ -175,5 +157,6 @@ Sample uses simplified representation for data consumers `?options=keyValues`
175157
| :----------- | :------------- | :------------- | :------------------------------------------------- |
176158
| `route_id` | `hasRoute` | | |
177159
| `service_id` | `hasService` | `gtfs:service` | It shall point to an Entity of Type `GtfsService` |
160+
| `shape_id` | `hasShape` | `gtfs:shape` | It shall point to an Entity of Type `GtfsShape` |
178161

179162
### Open issues

‎specs/UrbanMobility/GtfsTrip/example-normalized.json

+4-24
Original file line numberDiff line numberDiff line change
@@ -14,29 +14,9 @@
1414
"hasService": {
1515
"type": "Relationship",
1616
"value": "urn:ngsi-ld:GtfsService:Malaga_LAB"
17-
},
18-
"location": {
19-
"type": "geo:json",
20-
"value": {
21-
"type": "LineString",
22-
"coordinates": [
23-
[
24-
-4.421394,
25-
36.73826
26-
],
27-
[
28-
-4.421428,
29-
36.73825
30-
],
31-
[
32-
-4.421505,
33-
36.738186
34-
],
35-
[
36-
-4.421525,
37-
36.738033
38-
]
39-
]
40-
}
17+
},
18+
"hasShape": {
19+
"type": "Relationship",
20+
"value": "urn:ngsi-ld:GtfsShape:Shape01"
4121
}
4222
}

‎specs/UrbanMobility/GtfsTrip/example.json

+1-9
Original file line numberDiff line numberDiff line change
@@ -5,13 +5,5 @@
55
"headSign": "San Andrés",
66
"direction": 0,
77
"hasRoute": "urn:ngsi-ld:GtfsRoute:Spain:Malaga:1",
8-
"location": {
9-
"type": "LineString",
10-
"coordinates": [
11-
[-4.421394,36.73826],
12-
[-4.421428,36.73825],
13-
[-4.421505,36.738186],
14-
[-4.421525,36.738033]
15-
]
16-
}
8+
"hasShape": "urn:ngsi-ld:GtfsShape:Shape01"
179
}

‎specs/UrbanMobility/GtfsTrip/schema.json

+3-23
Original file line numberDiff line numberDiff line change
@@ -25,29 +25,9 @@
2525
"type": "string",
2626
"format": "uri"
2727
},
28-
"location": {
29-
"type": "object",
30-
"oneOf": [{
31-
"properties": {
32-
"type": {
33-
"type": "string",
34-
"enum": ["LineString"]
35-
},
36-
"coordinates": { "$ref": "http://json-schema.org/geojson/geometry.json#/definitions/lineString" }
37-
}
38-
},
39-
{
40-
"properties": {
41-
"type": {
42-
"type": "string",
43-
"enum": ["MultiLineString"]
44-
},
45-
"coordinates": {
46-
"type": "array",
47-
"items": { "$ref": "http://json-schema.org/geojson/geometry.json#/definitions/lineString" }
48-
}
49-
}
50-
}]
28+
"hasShape": {
29+
"type": "string",
30+
"format": "uri"
5131
},
5232
"block": {
5333
"type": "string"

0 commit comments

Comments
 (0)