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
The 1.1.0 minor release adds new top level APIs (geography, jurisdictions), privacy options (provider reports, geography-driven events, metrics), and transparency features (public endpoints).
8
+
9
+
### CHANGES
10
+
11
+
See the closed PRs tagged with [Milestone 1.1.0](https://github.com/openmobilityfoundation/mobility-data-specification/pulls?q=is%3Apr+is%3Aclosed+milestone%3A1.1.0) and [Issues](https://github.com/openmobilityfoundation/mobility-data-specification/issues?q=is%3Aissue+milestone%3A1.1.0+is%3Aclosed) for a full list of changes.
12
+
13
+
**_MDS_**
14
+
15
+
-[Policy and Geography can be public](https://github.com/openmobilityfoundation/mobility-data-specification/pull/585)
-[Response time expectations](https://github.com/openmobilityfoundation/mobility-data-specification/pull/563)
24
+
-[Geography publish date field consistency](https://github.com/openmobilityfoundation/mobility-data-specification/pull/597)
25
+
-[Adding more cities using MDS](https://github.com/openmobilityfoundation/mobility-data-specification/pull/591)
26
+
-[Adding more providers using MDS](https://github.com/openmobilityfoundation/mobility-data-specification/blob/dev/providers.csv)
27
+
-[Added a section for third party software companies using MDS](https://github.com/openmobilityfoundation/mobility-data-specification/issues/552) and cleaned up home page, moving list content to the OMF website
28
+
-[Update geography_json field type](https://github.com/openmobilityfoundation/mobility-data-specification/issues/635)
-[Elevating Geography to a first class API](https://github.com/openmobilityfoundation/mobility-data-specification/pull/582): [PR](https://github.com/openmobilityfoundation/mobility-data-specification/pull/499), [Issue](https://github.com/openmobilityfoundation/mobility-data-specification/issues/500)
The 1.0.0 release reconciles and aligns many parts of the MDS specification and adds features and updates requested by the community, including many new detailed vehicle states and event types, support for Stops (for docked vehicles, dockless corrals, parking areas), and adding rates (fees/subsidies) to Policy.
The Agency API endpoints are intended to be implemented by regulatory agencies and consumed by mobility providers. Providers query the Agency API when events (such as a trip start or vehicle status change) occur in their systems.
4
6
5
7
This specification contains a collection of RESTful APIs used to specify the digital relationship between *mobility as a service* providers and the agencies that regulate them.
@@ -184,7 +186,7 @@ Body Params:
184
186
|`event_types`| Enum[]| Required | see [Vehicle Events][vehicle-events]|
185
187
|`timestamp`|[timestamp][ts]| Required | Date of last event update |
186
188
|`telemetry`|[Telemetry](#telemetry-data)| Required | Single point of telemetry. |
187
-
|`event_geographies`| UUID[]| Optional |**[Beta feature](/general-information.md#beta-features):***Yes (as of 1.1.0)*. Array of Geography UUIDs consisting of every Geography that contains the location of the event. See [Geography Driven Events](#geography-driven-events). Required if `telemetry` is not present. |
189
+
|`event_geographies`| UUID[]| Optional |**[Beta feature](/general-information.md#beta-features):***Yes (as of 1.1.0)*. Array of Geography UUIDs consisting of every Geography that contains the location of the event. See [Geography Driven Events][geography-driven-events]. Required if `telemetry` is not present. |
188
190
|`trip_id`| UUID | Optional | UUID provided by Operator to uniquely identify the trip. Required if `event_types` contains `trip_start`, `trip_end`, `trip_cancel`, `trip_enter_jurisdiction`, or `trip_leave_jurisdiction`|
189
191
190
192
201 Success Response:
@@ -330,7 +332,7 @@ If `stop_id` is specified, `GET` will return an array with a single stop record,
Copy file name to clipboardExpand all lines: general-information.md
+9-8Lines changed: 9 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
# Mobility Data Specification: **General information**
2
2
3
-
This document contains specifications that are shared between the various MDS APIs such as [`agency`][agency], [`policy`][policy], and [`provider`][provider].
3
+
This document contains specifications that are shared between the various MDS APIs such as [`agency`][agency], [`policy`][policy], [`provider`][provider], etc.
4
4
5
5
## Table of Contents
6
6
@@ -11,6 +11,8 @@ This document contains specifications that are shared between the various MDS AP
@@ -32,9 +34,9 @@ This document contains specifications that are shared between the various MDS AP
32
34
33
35
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.
34
36
35
-
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.
37
+
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. 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.
36
38
37
-
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.
39
+
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. In subsequent releases existing beta features may include breaking changes, even in a minor release. Note that [schemas](/schema) may not be defined for some beta features until they are promoted out of beta.
38
40
39
41
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.
40
42
@@ -121,7 +123,9 @@ For the purposes of this specification, the intersection of two geographic datat
121
123
122
124
[Top][toc]
123
125
124
-
## Geography-Driven Events **[Beta feature](/general-information.md#beta-features):***Yes (as of 1.1.0)*
126
+
## Geography-Driven Events
127
+
128
+
**[Beta feature](/general-information.md#beta-features):***Yes (as of 1.1.0)*
125
129
126
130
Geography-Driven Events is a new MDS feature for Agencies to perform complete Policy compliance monitoring without precise location data. Geography-Driven Events describe individual vehicles in realtime – not just aggregate data. However, rather than receiving the exact location of a vehicle, Agencies receive information about the vehicle's current geographic region. The regions used for Geography-Driven Events correspond to the Geographies in an Agency's current Policy. In this way, the data-shared using Geography-Driven Events is matched to an Agency's particular regulatory needs.
127
131
@@ -139,20 +143,17 @@ Here's how it works in practice:
139
143
140
144
*Agency adds rule disallowing parking on waterfront path, begins receiving data on events within area.*
141
145
142
-
143
-
144
146
Agencies that wish to use Geography-Driven Events do so by requiring a new `event_geographies` field in status events. When an Agency is using Geography-Driven Events, Providers must emit a new `changed_geographies` status event whenever a vehicle in a trip enters or leaves a Geography managed by a Policy.
145
147
146
148
During the Beta period for this feature, location and telemtry data remain required fields. This allows Aggencies to test Geography-Driven Events, measuring its accuracy and efficacy against regulatory systems based on precise location data. After the beta period, if Geography-Driven Events is deemed by OMF to be accurate and effective, the specification will evolve to allow cities to use Geography-Driven Events in lieu of location or telemtry data.
147
149
148
-
149
150
[Top][toc]
150
151
151
152
## Optional Authentication
152
153
153
154
Authorization of the Policy and Geography APIs is no longer required and will be deprecated in next major release with these endpoints becoming optionally private instead of optionally public. An agency may optionally decide to make both the Policy and Geography endpoints unauthenticated and public. This allows transparency for the public to see how the city is regulating, holds the city accountable for their policy decisions, and reduces the technical burden on providers to use these endpoints. A side benefit is that this allows third parties to ingest this information into their applications and services for public benefit.
154
155
155
-
Note if implementing the beta features[Geography Driven Events](/general-information.md#geography-driven-events), both Policy and Geography must be public.
156
+
Note if implementing the beta feature[Geography Driven Events](/general-information.md#geography-driven-events), both Policy and Geography must be public.
This specification contains a collection of RESTful APIs used to read Geographies (descriptions of geographical information, e.g. multi-polygons, currently represented via GeoJSON).
4
6
5
7
Geographical data has many applications in the context of mobility, such as the description of municipal boundaries, locations for pick-up and drop-off zones, and areas of temporary closure for special events or emergencies. This API is intended to support a variety of other APIs, including the Policy API.
@@ -87,7 +89,7 @@ Authorization is not required. An agency may decide to make this endpoint unauth
87
89
88
90
## Schema
89
91
90
-
Placeholder -- link to schema to be added later.
92
+
Link to schema will be defined and added in a future release.
91
93
92
94
[Top][toc]
93
95
@@ -99,7 +101,7 @@ Placeholder -- link to schema to be added later.
99
101
|`description`| String | Optional | Detailed description of geography |
100
102
|`geography_type`| String | Optional | Type of geography, e.g. `municipal_boundary` or `council_district` or custom text. See [Geography Types](#geography-types). |
101
103
|`geography_id`| UUID | Required | Unique ID of geography |
102
-
|`geography_json`|UUID| Required | The GeoJSON that defines the geographical coordinates. |
104
+
|`geography_json`|JSON| Required | The GeoJSON that defines the geographical coordinates. |
103
105
|`effective_date`|[timestamp][ts]| Optional | The date at which a Geography is considered "live". Must be at or after `published_date`. |
104
106
|`published_date`|[timestamp][ts]| Required | Time that the geography was published, i.e. made immutable |
105
107
|`retire_date`|[timestamp][ts]| Optional | Time that the geography is slated to retire. Once the retire date is passed, new policies can no longer reference it and old policies referencing it should be updated. Retired geographies should continue to be returned in the geographies list. Must be after `effective_date`. |
0 commit comments