Skip to content

Commit b45460a

Browse files
thekavemanthekaveman
committed
alphabetize sections, links to TOC
1 parent 5b41e20 commit b45460a

1 file changed

Lines changed: 111 additions & 79 deletions

File tree

‎general-information.md‎

Lines changed: 111 additions & 79 deletions
Original file line numberDiff line numberDiff line change
@@ -4,56 +4,60 @@ This document contains specifications that are shared between the various MDS AP
44

55
## Table of Contents
66

7-
* [Versioning](#versioning)
87
* [Beta Features](#beta-features)
9-
* [Responses](#responses)
10-
* [Error Message Format](#error-message-format)
11-
* [Timestamps](#timestamps)
12-
* [Strings](#strings)
13-
* [UUIDs](#uuids)
148
* [Costs and Currencies](#costs-and-currencies)
159
* [Devices](#devices)
16-
* [Vehicle Types](#vehicle-types)
1710
* [Propulsion Types](#propulsion-types)
11+
* [Responses](#responses)
12+
* [Error Messages](#error-messages)
13+
* [Strings](#strings)
14+
* [Timestamps](#timestamps)
15+
* [UUIDs](#uuids)
1816
* [Vehicle States](#vehicle-states)
19-
* [Vehicle Events](#vehicle-events)
17+
* [Vehicle State Events](#vehicle-state-events)
18+
* [Vehicle Types](#vehicle-types)
19+
* [Versioning](#versioning)
2020

21-
## Versioning
21+
## Beta Features
2222

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.
2424

25-
Versioning must be implemented through the use of 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.
2626

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.
2828

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.
3030

31-
```http
32-
Accept: application/vnd.mds+json;version=0.3
33-
```
31+
[Top][toc]
3432

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
3934

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).
4136

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.
4338

44-
```http
45-
OPTIONS /trips/ HTTP/1.1
46-
Host: provider.example.com
47-
Accept: application/vnd.mds+json;version=0.2,application/vnd.mds+json;version=0.3;q=0.9
48-
```
39+
[Top][toc]
4940

50-
The response will include the most preferred supported version in the `Content-Type` header. For example, if only `0.3` is supported:
41+
## Devices
5142

52-
```http
53-
Content-Type: application/vnd.mds+json;version=0.3
54-
```
43+
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.
5544

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.
46+
47+
[Top][toc]
48+
49+
## Propulsion Types
50+
51+
| `propulsion` | Description |
52+
| ----------------- | ------------------------------------------------------ |
53+
| `human` | Pedal or foot propulsion |
54+
| `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]
5761

5862
## Responses
5963

@@ -65,73 +69,43 @@ The client can use the returned value verbatim as a version request in the `Acce
6569
* **409:** Conflict: `POST` operations when an object already exists and an update is not possible.
6670
* **500:** Internal server error: In this case, the answer may contain a `text/plain` body with an error message for troubleshooting.
6771

68-
## Error Message Format
72+
### Error Messages
73+
74+
```json
75+
{
76+
"error": "...",
77+
"error_description": "...",
78+
"error_details": [ "...", "..." ]
79+
}
80+
```
6981

7082
| Field | Type | Field Description |
7183
| ------------------- | -------- | ---------------------- |
7284
| `error` | String | Error message string |
7385
| `error_description` | String | Human readable error description (can be localized) |
7486
| `error_details` | String[] | Array of error details |
7587

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]
8189

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
8391

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.
8593

86-
[Top](#table-of-contents)
94+
[Top][toc]
8795

8896
## Timestamps
8997

9098
A `timestamp` refers to integer milliseconds since Unix epoch.
9199

92-
## Strings
93-
94-
All String fields, such as `vehicle_id`, are limited to a maximum of 255 characters.
100+
[Top][toc]
95101

96102
## UUIDs
97103

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.
99105

100106
MDS uses Version 1 UUIDs.
101107

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 |
124-
125-
## Propulsion Types
126-
127-
| `propulsion` | Description |
128-
| ----------------- | ------------------------------------------------------ |
129-
| `human` | Pedal or foot propulsion |
130-
| `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]
135109

136110
## Vehicle States
137111

@@ -149,7 +123,9 @@ In a multi-jurisdiction environment, the status of a vehicle is per-jurisdiction
149123
| `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. |
150124
| `unknown` | unknown | Provider has lost contact with the vehicle and its disposition is unknown. Examples include: taken into a private residence, thrown in river. |
151125

152-
## Vehicle Events
126+
[Top][toc]
127+
128+
### Vehicle State Events
153129

154130
This is the list of `vehicle_state` and `event_type` pairings that constitute the valid transitions of the vehicle state machine.
155131

@@ -190,3 +166,59 @@ NOTES:
190166
Should we try to handle "unlicensed movements"?
191167

192168
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+
> - The `provider` API must respond as if version `0.2` was requested.
201+
> - The `agency` API must respond as if version `0.3` was requested.
202+
> - The `policy` API must respond as if version `0.4` was requested.
203+
204+
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.
205+
206+
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:
207+
208+
```http
209+
OPTIONS /trips/ HTTP/1.1
210+
Host: provider.example.com
211+
Accept: application/vnd.mds+json;version=0.2,application/vnd.mds+json;version=0.3;q=0.9
212+
```
213+
214+
The response will include the most preferred supported version in the `Content-Type` header. For example, if only `0.3` is supported:
215+
216+
```http
217+
Content-Type: application/vnd.mds+json;version=0.3
218+
```
219+
220+
The client can use the returned value verbatim as a version request in the `Accept` header.
221+
222+
[Top][toc]
223+
224+
[toc]: #table-of-contents

0 commit comments

Comments
 (0)