Merge pull request #532 from schnuerle/ms-links-definitions

Adding Definitions. Updating links, formatting.

Author: schnuerle

README.md

@@ -30,11 +30,10 @@ You can also get involved in development by joining an OMF working group. The wo
 Working Group | Mailing List | Description
 --- | --- | ---
 Provider Services | [mds-provider-services](https://groups.google.com/a/groups.openmobilityfoundation.org/forum/#!forum/mds-provider-services) | Manages the [`provider`][provider] API within MDS.
-City Services | [mds-city-services](https://groups.google.com/a/groups.openmobilityfoundation.org/forum/#!forum/mds-city-services) | Manages the [`agency`][agency] and [`policy`][policy] APIs within MDS, as well as the [`mds-core`](https://github.com/openmobilityfoundation/mds-core) reference implementation.
+City Services | [mds-city-services](https://groups.google.com/a/groups.openmobilityfoundation.org/forum/#!forum/mds-city-services) | Manages the [`agency`][agency] and [`policy`][policy] APIs within MDS, as well as the [`mds-core`](https://github.com/openmobilityfoundation/mds-core) and [`mds-compliance-mobile`](https://github.com/openmobilityfoundation/mds-compliance-mobile) reference implementations.
 
 You can view info about past releases and planning calls in the [wiki](https://github.com/openmobilityfoundation/mobility-data-specification/wiki).
 
-
 For questions about MDS please contact [info@openmobilityfoundation.org](mailto:info@openmobilityfoundation.org). Media inquiries to [media@openmobilityfoundation.org](mailto:media@openmobilityfoundation.org)
 
 ## Versions
@@ -77,7 +76,7 @@ Some examples of how cities are using MDS in practice:
 
 ### Open Mobility Foundation
 * [`mds-core`](https://github.com/openmobilityfoundation/mds-core) - A reference implementation of an MDS Agency Server, built using PostgresQL, TypeScript, NodeJS.
-* [`mds-compliance-mobile`](`https://github.com/openmobilityfoundation/mds-compliance-mobile`) - A mobile app for performing in-the-field data validation and compliance monitoring.
+* [`mds-compliance-mobile`](https://github.com/openmobilityfoundation/mds-compliance-mobile) - A mobile app for performing in-the-field data validation and compliance monitoring.
 
 ### City of Los Angeles
 * [`mds-dev`](https://github.com/cityoflosangeles/mds-dev) - Code to do cap checking, fake data generation and more with provider data.

agency/README.md

@@ -76,7 +76,7 @@ A vehicle record is as follows:
 | `model`       | String    | Vehicle Model                                                                 |
 | `state`       | Enum      | Current vehicle state. See [Vehicle State][vehicle-states]                    |
 | `prev_event`  | Enum      | Last [Vehicle Event][vehicle-event]                                           |
-| `updated`     | Timestamp | Date of last event update                                                     |
+| `updated`     | [timestamp][ts] | Date of last event update                                                     |
 
 404 Failure Response:
 
@@ -166,7 +166,7 @@ Body Params:
 | -----------     | ----------------------------- | -------- | -------------------------------------------------------------------------------- |
 | `vehicle_state` | Enum                          | Required | see [Vehicle States][vehicle-states] |
 | `event_types`   | Enum[]                        | Required | see [Vehicle Events][vehicle-events] |
-| `timestamp`     | Timestamp                     | Required | Date of last event update |
+| `timestamp`     | [timestamp][ts]                     | Required | Date of last event update |
 | `telemetry`     | [Telemetry](#telemetry-data)  | Required | Single point of telemetry |
 | `trip_id`       | UUID                          | Optional | UUID provided by Operator to uniquely identify the trip. Required for `trip_start`, `trip_end`, `trip_enter`, and `trip_leave` event types |
 
@@ -220,7 +220,7 @@ A standard point of vehicle telemetry. References to latitude and longitude impl
 | Field          | Type           | Required/Optional     | Field Description                                            |
 | -------------- | -------------- | --------------------- | ------------------------------------------------------------ |
 | `device_id`    | UUID           | Required              | ID used in [Register](#vehicle-register)                     |
-| `timestamp`    | Timestamp      | Required              | Date/time that event occurred. Based on GPS or GNSS clock            |
+| `timestamp`    | [timestamp][ts]      | Required              | Date/time that event occurred. Based on GPS or GNSS clock            |
 | `gps`          | Object         | Required              | Telemetry position data                                      |
 | `gps.lat`      | Double         | Required              | Latitude of the location                                     |
 | `gps.lng`      | Double         | Required              | Longitude of the location                                    |
@@ -234,13 +234,14 @@ A standard point of vehicle telemetry. References to latitude and longitude impl
 
 [Top][toc]
 
-[toc]: #table-of-contents
 [general]: /general-information.md
-[versioning]: /general-information.md#versioning
-[responses]: /general-information.md#responses
 [error-messages]: /general-information.md#error-messages
+[hdop]: https://support.esri.com/en/other-resources/gis-dictionary/term/358112bd-b61c-4081-9679-4fca9e3eb926
+[propulsion-types]: /general-information.md#propulsion-types
+[responses]: /general-information.md#responses
+[toc]: #table-of-contents
+[ts]: /general-information.md#timestamps
 [vehicle-types]: /general-information.md#vehicle-types
 [vehicle-states]: /general-information.md#vehicle-states
 [vehicle-events]: /general-information.md#vehicle-state-events
-[propulsion-types]: /general-information.md#propulsion-types
-[hdop]: https://support.esri.com/en/other-resources/gis-dictionary/term/358112bd-b61c-4081-9679-4fca9e3eb926
+[versioning]: /general-information.md#versioning

general-information.md

@@ -6,6 +6,7 @@ This document contains specifications that are shared between the various MDS AP
 
 * [Beta Features](#beta-features)
 * [Costs and Currencies](#costs-and-currencies)
+* [Definitions](#definitions)
 * [Devices](#devices)
 * [Propulsion Types](#propulsion-types)
 * [Responses](#responses)
@@ -38,6 +39,17 @@ If the currency field is null, USD cents is implied.
 
 [Top][toc]
 
+## Definitions
+
+Defining terminology and abbreviations used throughout MDS.
+
+- **API** - Application Programming Interface - A function or set of functions that allow one software application to access or communicate with features of a different software application or service. 
+- **API Endpoint** - A point at which an API connects with a software application or service.
+- **DOT** - Department of Transportation, usually a city-run agency.
+- **PROW** - Public Right of Way - the physical infrastructure reserved for transportation purposes, examples include sidewalks, curbs, bike lanes, transit lanes and stations, traffic lanes and signals, and public parking.
+
+[Top][toc]
+
 ## Devices
 
 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.

policy/README.md

@@ -277,7 +277,7 @@ The internal mechanics of ordering are up to the Policy editing and hosting soft
 [iana]: https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml
 [muni-boundary]: ../provider/README.md#municipality-boundary
 [propulsion-types]: /general-information.md#propulsion-types
-[timestamps]: /general-information.md#timestamps
+[ts]: /general-information.md#timestamps
 [toc]: #table-of-contents
 [vehicle-events]: /general-information.md#vehicle-state-events
 [vehicle-states]: /general-information.md#vehicle-states

provider/README.md

@@ -310,7 +310,7 @@ The schema and datatypes are the same as those defined for [`/status_changes`][s
 
 **Endpoint:** `/events`  
 **Method:** `GET`  
-**[Beta feature][beta]:** Yes (as of 0.4.0)  
+**[Beta feature][beta]:** No (as of 1.0.0)  
 **Schema:** [`events` schema][events-schema]  
 **`data` Payload:** `{ "status_changes": [] }`, an array of objects with the same structure as in [`/status_changes`][status]