You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: agency/README.md
+8-12Lines changed: 8 additions & 12 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -23,15 +23,11 @@ This specification uses data types including timestamps, UUIDs, and vehicle stat
23
23
24
24
`agency` APIs must handle requests for specific versions of the specification from clients.
25
25
26
-
Versioning must be implemented as specified in the [`General information versioning section`][versioning].
26
+
Versioning must be implemented as specified in the [Versioning section][versioning].
27
27
28
-
### Responses
28
+
### Responses and Error Messages
29
29
30
-
See [responses][responses]
31
-
32
-
### Error Message Format
33
-
34
-
See [error message format][error-message-format]
30
+
See the [Responses][responses] and [Error Messages][error-messages] sections.
35
31
36
32
### Authorization
37
33
@@ -54,10 +50,10 @@ Path Params:
54
50
55
51
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:
56
52
57
-
```
53
+
```json
58
54
{
59
-
"vehicles": [ ... ]
60
-
"links": {
55
+
"vehicles": [ ... ]
56
+
"links": {
61
57
"first": "https://...",
62
58
"last": "https://...",
63
59
"prev": "https://...",
@@ -240,9 +236,9 @@ A standard point of vehicle telemetry. References to latitude and longitude impl
# Mobility Data Specification: **General information**
2
2
3
-
This document contains specifications that are shared between the various MDS APIs such as `agency`, `provider` and `policy`.
3
+
This document contains specifications that are shared between the various MDS APIs such as [`agency`][agency], [`policy`][policy], and [`provider`][provider].
4
4
5
5
## Table of Contents
6
6
7
-
*[Versioning](#versioning)
8
7
*[Beta Features](#beta-features)
9
-
*[Responses](#responses)
10
-
*[Error Message Format](#error-message-format)
11
-
*[Timestamps](#timestamps)
12
-
*[Strings](#strings)
13
-
*[UUIDs](#uuids)
14
8
*[Costs and Currencies](#costs-and-currencies)
15
9
*[Devices](#devices)
16
-
*[Vehicle Types](#vehicle-types)
17
10
*[Propulsion Types](#propulsion-types)
11
+
*[Responses](#responses)
12
+
*[Error Messages](#error-messages)
13
+
*[Strings](#strings)
14
+
*[Timestamps](#timestamps)
15
+
*[UUIDs](#uuids)
18
16
*[Vehicle States](#vehicle-states)
19
-
*[Vehicle Events](#vehicle-events)
17
+
*[Vehicle State Events](#vehicle-state-events)
18
+
*[Vehicle Types](#vehicle-types)
19
+
*[Versioning](#versioning)
20
20
21
-
## Versioning
21
+
## Beta Features
22
22
23
-
MDS APIs must handle requests for specific versions of the specification from clients.
23
+
In some cases, features within MDS may be marked as "beta." These are typically recently added endpoints or fields. Because beta features are new, they may not yet be fully mature and proven in real-world operation. The design of beta features may have undiscovered gaps, ambiguities, or inconsistencies. Implementations of those features are typically also quite new and are more likely to contain bugs or other flaws. Beta features are likely to evolve more rapidly than other parts of the specification.
24
24
25
-
Versioning must be implemented through the useof a custom media-type, `application/vnd.mds+json`, combined with a required `version` parameter.
25
+
Despite this, MDS users are highly encouraged to use beta features. New features can only become proven and trusted through implementation, use, and the learning that comes with it. Users should be thoughtful about the role of beta features in their operations. Beta features may be suitable for enabling some new tools and analysis, but may not be appropriate for mission-critical applications or regulatory decisions where certainty and reliability are essential.
26
26
27
-
The version parameter specifies the dot-separated combination of major and minor versions from a published version of the specification. For example, the media-type for version `1.0.1` would be specified as `application/vnd.mds+json;version=1.0`
27
+
Users of beta features are strongly encouraged to share their experiences, learnings, and challenges with the broader MDS community via GitHub issues or pull requests. This will inform the refinements that transform beta features into fully proven, stable parts of the specification.
28
28
29
-
Clients must specify the version they are targeting through the `Accept` header. For example:
29
+
Working Groups and their Steering Committees are expected to review beta designated features with each release cycle and determine whether the feature has reached the level of stability and maturity needed to remove the beta designation. In a case where a beta feature fails to reach substantial adoption after an extended time, Working Group Steering Committees should discuss whether or not the feature should remain in the specification.
30
30
31
-
```http
32
-
Accept: application/vnd.mds+json;version=0.3
33
-
```
31
+
[Top][toc]
34
32
35
-
> Since versioning was not available from the start, the following APIs provide a fallback version if the `Accept` header is not set as specified above:
36
-
> - The `provider` API must respond as if version `0.2` was requested.
37
-
> - The `agency` API must respond as if version `0.3` was requested.
38
-
> - The `policy` API must respond as if version `0.4` was requested.
33
+
## Costs and currencies
39
34
40
-
If an unsupported or invalid version is requested, the API must respond with a status of `406 Not Acceptable`. If this occurs, a client can explicitly negotiate available versions.
35
+
Fields specifying a monetary cost use a currency as specified in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes). All costs should be given as integers in the currency's smallest unit. As an example, to represent $1 USD, specify an amount of `100` (100 cents).
41
36
42
-
A client negotiates available versions using the `OPTIONS` method to an MDS endpoint. For example, to check if `trips` supports either version `0.2` or `0.3` with a preference for `0.2`, the client would issue the following request:
37
+
If the currency field is null, USD cents is implied.
MDS defines the *device* as the unit that transmits GPS or GNSS signals for a particular vehicle. A given device must have a UUID (`device_id` below) that is unique within the Provider's fleet.
55
44
56
-
The client can use the returned value verbatim as a version request in the `Accept` header.
45
+
Additionally, `device_id` must remain constant for the device's lifetime of service, regardless of the vehicle components that house the device.
|`electric_assist`| Provides power only alongside human propulsion |
55
+
|`electric`| Contains throttle mode with a battery-powered motor |
56
+
|`combustion`| Contains throttle mode with a gas engine-powered motor |
57
+
58
+
A vehicle may have one or more values from the `propulsion`, depending on the number of modes of operation. For example, a scooter that can be powered by foot or by electric motor would have the `propulsion` represented by the array `['human', 'electric']`. A bicycle with pedal-assist would have the `propulsion` represented by the array `['human', 'electric_assist']` if it can also be operated as a traditional bicycle.
59
+
60
+
[Top][toc]
57
61
58
62
## Responses
59
63
@@ -65,73 +69,43 @@ The client can use the returned value verbatim as a version request in the `Acce
65
69
***409:** Conflict: `POST` operations when an object already exists and an update is not possible.
66
70
***500:** Internal server error: In this case, the answer may contain a `text/plain` body with an error message for troubleshooting.
|`error_description`| String | Human readable error description (can be localized) |
74
86
|`error_details`| String[]| Array of error details |
75
87
76
-
## Beta Features
77
-
78
-
In some cases, features within MDS may be marked as "beta." These are typically recently added endpoints or fields. Because beta features are new, they may not yet be fully mature and proven in real-world operation. The design of beta features may have undiscovered gaps, ambiguities, or inconsistencies. Implementations of those features are typically also quite new and are more likely to contain bugs or other flaws. Beta features are likely to evolve more rapidly than other parts of the specification.
79
-
80
-
Despite this, MDS users are highly encouraged to use beta features. New features can only become proven and trusted through implementation, use, and the learning that comes with it. Users should be thoughtful about the role of beta features in their operations. Beta features may be suitable for enabling some new tools and analysis, but may not be appropriate for mission-critical applications or regulatory decisions where certainty and reliability are essential.
88
+
[Top][toc]
81
89
82
-
Users of beta features are strongly encouraged to share their experiences, learnings, and challenges with the broader MDS community via GitHub issues or pull requests. This will inform the refinements that transform beta features into fully proven, stable parts of the specification.
90
+
## Strings
83
91
84
-
Working Groups and their Steering Committees are expected to review beta designated features with each release cycle and determine whether the feature has reached the level of stability and maturity needed to remove the beta designation. In a case where a beta feature fails to reach substantial adoption after an extended time, Working Group Steering Committees should discuss whether or not the feature should remain in the specification.
92
+
All String fields, such as `vehicle_id`, are limited to a maximum of 255 characters.
85
93
86
-
[Top](#table-of-contents)
94
+
[Top][toc]
87
95
88
96
## Timestamps
89
97
90
98
A `timestamp` refers to integer milliseconds since Unix epoch.
91
99
92
-
## Strings
93
-
94
-
All String fields, such as `vehicle_id`, are limited to a maximum of 255 characters.
100
+
[Top][toc]
95
101
96
102
## UUIDs
97
103
98
-
Object identifiers are described via Universally Unique Identifiers [(UUIDs)](https://en.wikipedia.org/wiki/Universally_unique_identifier). For example, the `device_id` field used to uniquely identify a vehicle is a UUID.
104
+
Object identifiers are described via Universally Unique Identifiers [(UUIDs)](https://en.wikipedia.org/wiki/Universally_unique_identifier). For example, the `device_id` field used to uniquely identify a vehicle is a UUID.
99
105
100
106
MDS uses Version 1 UUIDs.
101
107
102
-
## Costs and currencies
103
-
104
-
Fields specifying a monetary cost use a currency as specified in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes). All costs should be given as integers in the currency's smallest unit. As an example, to represent $1 USD, specify an amount of `100` (100 cents).
105
-
106
-
If the currency field is null, USD cents is implied.
107
-
108
-
## Devices
109
-
110
-
MDS defines the *device* as the unit that transmits GPS or GNSS signals for a particular vehicle. A given device must have a UUID (`device_id` below) that is unique within the Provider's fleet.
111
-
112
-
Additionally, `device_id` must remain constant for the device's lifetime of service, regardless of the vehicle components that house the device.
113
-
114
-
## Vehicle Types
115
-
116
-
The list of allowed `vehicle_type` values in MDS is:
117
-
118
-
|`vehicle_type`| Description |
119
-
|--------------| --- |
120
-
| bicycle | Anything with pedals, including recumbents; can include powered assist |
121
-
| car | Any automobile |
122
-
| scooter | Any motorized mobility device intended for one rider |
123
-
| moped | A motorcycle/bicycle hybrid that can be powered or pedaled |
|`electric_assist`| Provides power only alongside human propulsion |
131
-
|`electric`| Contains throttle mode with a battery-powered motor |
132
-
|`combustion`| Contains throttle mode with a gas engine-powered motor |
133
-
134
-
A vehicle may have one or more values from the `propulsion`, depending on the number of modes of operation. For example, a scooter that can be powered by foot or by electric motor would have the `propulsion` represented by the array `['human', 'electric']`. A bicycle with pedal-assist would have the `propulsion` represented by the array `['human', 'electric_assist']` if it can also be operated as a traditional bicycle.
108
+
[Top][toc]
135
109
136
110
## Vehicle States
137
111
@@ -149,7 +123,9 @@ In a multi-jurisdiction environment, the status of a vehicle is per-jurisdiction
149
123
|`elsewhere`| no | Outside of regulator's jurisdiction, and thus not subject to cap-counts or other regulations. Example: a vehicle that started a trip in L.A. has transitioned to Santa Monica. |
150
124
|`unknown`| unknown | Provider has lost contact with the vehicle and its disposition is unknown. Examples include: taken into a private residence, thrown in river. |
151
125
152
-
## Vehicle Events
126
+
[Top][toc]
127
+
128
+
### Vehicle State Events
153
129
154
130
This is the list of `vehicle_state` and `event_type` pairings that constitute the valid transitions of the vehicle state machine.
155
131
@@ -185,8 +161,68 @@ Note that to handle out-of-order events, the validity of the prior-state shall n
185
161
| any |`unknown`|`missing`| The vehicle is not at its last reported GPS location, or that location is wildly in error |
186
162
| any |`unknown`|`out_of_comms`| The vehicle is unable to transmit its GPS location |
187
163
188
-
NOTES:
164
+
NOTES:
189
165
190
166
Should we try to handle "unlicensed movements"?
191
167
192
-
What's the best way to return from `unknown`?
168
+
What's the best way to return from `unknown`?
169
+
170
+
[Top][toc]
171
+
172
+
## Vehicle Types
173
+
174
+
The list of allowed `vehicle_type` values in MDS is:
175
+
176
+
|`vehicle_type`| Description |
177
+
|--------------| --- |
178
+
| bicycle | Anything with pedals, including recumbents; can include powered assist |
179
+
| car | Any automobile |
180
+
| scooter | Any motorized mobility device intended for one rider |
181
+
| moped | A motorcycle/bicycle hybrid that can be powered or pedaled |
182
+
183
+
[Top][toc]
184
+
185
+
## Versioning
186
+
187
+
MDS APIs must handle requests for specific versions of the specification from clients.
188
+
189
+
Versioning must be implemented through the use of a custom media-type, `application/vnd.mds+json`, combined with a required `version` parameter.
190
+
191
+
The version parameter specifies the dot-separated combination of major and minor versions from a published version of the specification. For example, the media-type for version `1.0.1` would be specified as `application/vnd.mds+json;version=1.0`
192
+
193
+
Clients must specify the version they are targeting through the `Accept` header. For example:
194
+
195
+
```http
196
+
Accept: application/vnd.mds+json;version=0.3
197
+
```
198
+
199
+
> Since versioning was not available from the start, the following APIs provide a fallback version if the `Accept` header is not set as specified above:
200
+
>
201
+
> * The `provider` API must respond as if version `0.2` was requested.
202
+
> * The `agency` API must respond as if version `0.3` was requested.
203
+
> * The `policy` API must respond as if version `0.4` was requested.
204
+
205
+
If an unsupported or invalid version is requested, the API must respond with a status of `406 Not Acceptable`. If this occurs, a client can explicitly negotiate available versions.
206
+
207
+
A client negotiates available versions using the `OPTIONS` method to an MDS endpoint. For example, to check if `trips` supports either version `0.2` or `0.3` with a preference for `0.2`, the client would issue the following request:
|`error_description`| String | Human readable error description (can be localized) |
90
-
|`error_details`| String[] (optional) | Array of error details |
70
+
See the [Responses section][responses] for information on valid MDS response codes and the [Error Messages section][error-messages] for information on formatting error messages.
91
71
92
72
#### Policies
93
73
@@ -281,13 +261,13 @@ The internal mechanics of ordering are up to the Policy editing and hosting soft
0 commit comments