Merge branch 'dev' into reports-simplify-time

Author: wellorder

README.md

@@ -165,9 +165,9 @@ To add yourself to the [agency list](/agencies.csv) and add your [Policy Require
 
 # Providers Using MDS
 
-Over two dozen mobility service providers (MSPs) around the world use MDS, allowing them to create tools around a single data standard for multiple cities. 
+Over three dozen mobility service providers (MSPs) around the world use MDS, allowing them to create tools around a single data standard for multiple cities. 
 
-- See our **[list of providers using MDS](https://www.openmobilityfoundation.org/mds-users/#mobility-providers-using-mds)**. For a table list with unique IDs, see the MDS [provider list](/providers.csv).
+- See our **[list of providers using MDS](https://www.openmobilityfoundation.org/mds-users/#mobility-providers-using-mds)**. For a table list with unique IDs, see the MDS [provider list](/providers.csv) which includes both service operators and data solution providers.
 
 To add yourself to the provider list, please let us know [via our website](https://www.openmobilityfoundation.org/get-in-touch/) or open an [Issue](https://github.com/openmobilityfoundation/mobility-data-specification/issues) or [Pull Request](https://github.com/openmobilityfoundation/mobility-data-specification/pulls). Find out how in our [Adding an Provider ID](https://github.com/openmobilityfoundation/mobility-data-specification/wiki/Adding-an-MDS-Provider-ID) help document.
 

agency/README.md

@@ -81,6 +81,7 @@ A vehicle record is as follows:
 | ------------- | --------- | ----------------------------------------------------------------------------- |
 | `device_id`   | UUID      | Provided by Operator to uniquely identify a vehicle                           |
 | `provider_id` | UUID      | Issued by Agency and [tracked](../providers.csv)                              |
+| `data_provider_id` | UUID | Optional | If different than `provider_id`, a UUID for the data solution provider managing the data feed in this endpoint. See MDS [provider list](/providers.csv) which includes both service operators and data solution providers. |
 | `vehicle_id`  | String    | Vehicle Identification Number (vehicle_id) visible on vehicle                 |
 | `vehicle_type`        | Enum      | [Vehicle Type][vehicle-types]           |
 | `propulsion_types`  | Enum[]    | Array of [Propulsion Type][propulsion-types]; allows multiple values          |
@@ -382,6 +383,7 @@ The Trips endpoint serves two purposes:
 | trip_type                     | Enum                           | Optional               | The type of the trip |
 | trip_attributes               | `{ [String]: String}`          | Optional               | Trip attributes, given as mode-specific key-value pairs |
 | provider_id                   | UUID                           | Required               | Provider which managed this trip |
+| `data_provider_id`            | UUID                           | Optional               | If different than `provider_id`, a UUID for the data solution provider managing this data endpoint. See MDS [provider list](/providers.csv) which includes both service operators and data solution providers. |
 | reservation_method            | Enum                           | Required               | Way the customer created their reservation, see [reservation-method](#reservation-method) |
 | reservation_time              | Timestamp                      | Required               | Time the customer *requested* a reservation |
 | reservation_type              | Enum                           | Required               | Type of reservation, see [reservation-type](#reservation-type) |

general-information.md

@@ -226,7 +226,8 @@ Stops describe vehicle trip start and end locations in a pre-designated physical
 | capacity               | {vehicle_type: number}                                | Required | Number of total places per vehicle_type |
 | num_vehicles_available | {vehicle_type: number}                                | Required | How many vehicles are available per vehicle_type at this stop? |
 | num_vehicles_disabled  | {vehicle_type: number}                                | Required | How many vehicles are unavailable/reserved per vehicle_type at this stop? |
-| provider_id            | UUID                                                  | Optional | UUID for the Provider managing this stop. Null/undefined if managed by an Agency.  See MDS [provider list](/providers.csv). |
+| provider_id            | UUID                                                  | Optional | UUID for the provider managing this stop. Null/undefined if managed by an agency.  See MDS [provider list](/providers.csv). |
+| data_provider_id       | UUID                                                  | Optional | UUID for the data provider managing the data coming from this stop. Null/undefined if managed by an agency or a provider.  See MDS [provider list](/providers.csv). |
 | geography_id           | UUID                                                  | Optional | Pointer to the [Geography](/geography) that represents the Stop geospatially via Polygon or MultiPolygon. |
 | region_id              | string                                                | Optional | ID of the region where station is located, see [GBFS Station Information][gbfs-station-info] |
 | short_name             | String                                                | Optional | Abbreviated stop name |
@@ -351,7 +352,7 @@ The list of allowed `vehicle_type` values in MDS. Aligning with [GBFS vehicle ty
 
 MDS APIs must handle requests for specific versions of the specification from clients.
 
-Versioning must be implemented through the use of a custom media-type, `application/vnd.mds+json`, combined with a required `version` parameter.
+Versioning must be implemented through the use of a custom media-type, `application/vnd.mds+json`, combined with a required `version` parameter.  The one exception is the `/reports` endpoint, which returns CSV files instead of JSON, and so uses `text/vnd.mds+csv` as its media-type.
 
 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`
 

modes/car-share.md

@@ -64,7 +64,7 @@ Example 3: one trip point-to-point with an employee moving the vehicle to a new
 
 The `journey_attributes` array **may** have the following key value pairs:
 
-- ...
+- `reservation_id` (UUID, optional): unique identifier for an entire car share reservation, tied across multiple journeys and therefore trips.
 
 [Top][toc]
 
@@ -103,7 +103,7 @@ _See more available trip attributes for any mode in the [trips endpoint](/provid
 
 The `fare_attributes` array **may** have the following key value pairs:
 
-- `payment_type` (enumerated, required): `cash`, `credit_card`, `mobile`, `voucher`, `paratransit`, `no payment`, `test`
+- `payment_type` (enumerated, required): `cash`, `credit_card`, `mobile`, `voucher`, `no payment`, `test`
 - `fare_type` (enumerated, required): `meter_fare`, `upfront_pricing`, `flat_rate`. Indicator of which rate was charged.
 - `tolls` (currency, optional) - Sum of any and all tolls charged for the trip, such as bridge tolls
 - `base_rate` (currency, optional) - Minimum fare to be charged as soon as the trip starts.
@@ -113,8 +113,6 @@ The `fare_attributes` array **may** have the following key value pairs:
 - `extra_amount` (currency, optional) - miscellaneous extra amounts charged to customer not covered by other fields.
 - `taxes` (currency, optional) - amount of taxes paid for the ride
 - `surcharge` (currency, optional) - any surcharge pricing
-- `commission` (currency, optional) - any extra commission for the ride
-- `driver_trip_pay` (currency, optional) - The payment the company driver received for the trip 
 
 _See more available fare attributes for any mode in the [trips endpoint](/provider#trips)._
 

modes/delivery-robots.md

@@ -62,7 +62,7 @@ Example 2: three overlapping delivery trips in the same journey
 
 ### Journey Attributes
 
-The `journey_attributes` array **may** have the following key value pairs:
+The `journey_attributes` array is not used in this mode.
 
 - ...
 
@@ -95,7 +95,7 @@ The `trip_type` field **must** have one of the following enumerated values:
 The `trip_attributes` array **may** have the following key value pairs:
 
 - `driver_type` (ennum, required): type of driver operating the device: `human`, `semi-autonomous`, `autonomous`
-- `driver_id` (UUID, optional): consistent unique identifier of the privary driver. Could be based on software version or human
+- `driver_id` (UUID, optional): consistent unique identifier of the privary driver. Could be based on software version or an internal human driver id.
 - `app_name` (text, optional): name of the app used to reserve the trip which could be provider's app or 3rd party app
 - `request_time` (timestamp, optional): when the customer requested the trip
 - `has_payload` (boolean, optional): is there any payload for any delivery included in the device at trip start. 1 = loaded, 0 = empty

modes/micromobility.md

@@ -153,7 +153,7 @@ Valid micromobility vehicle event types are
 - `trip_start`
 - `unspecified`
 
-Note that providers should make best-effort to map their business logic onto these states, which are meant to provide a view of the fleet to an agency.  But if an agency does not perform `agency_drop_off` or `agency_pick_up`, for example, they need not be included in the parovider's implementation.
+Note that providers should make best-effort to map their business logic onto these states, which are meant to provide a view of the fleet to an agency.  But if an agency does not perform `agency_drop_off` or `agency_pick_up`, for example, they need not be included in the provider's implementation.
 
 See vehicle [Event Types][vehicle-events] for descriptions.
 

policy/README.md

@@ -138,10 +138,10 @@ Authorization is not required and agencies are encouraged to make these endpoint
 | Name         | Type      | Required / Optional | Description                                    |
 | ------------ | --------- | --- | ---------------------------------------------- |
 | `id`         | UUID      | Optional    | If provided, returns one policy object with the matching UUID; default is to return all policy objects.                       |
-| `start_date` | [timestamp][ts] | Optional    | Earliest effective date; default is policies effective as of the request time |
-| `end_date`   | [timestamp][ts] | Optional    | Latest effective date; default is all policies effective in the future    |
+| `start_date` | [timestamp][ts] | Optional    | Beginning date of the queried time range; the default value is the request time |
+| `end_date`   | [timestamp][ts] | Optional    | Ending date of the queried time range; the default value is null, which captures all policies that are effective in the future|
 
-`start_date` and `end_date` are only considered when no `id` parameter is provided.
+`start_date` and `end_date` are only considered when no `id` parameter is provided. They should return any policy whose effectiveness overlaps with or is contained with this range. Suppose there's a policy with a `start_date` of 1/1/21 and `end_date` of 1/31/21. Assuming an `end_date` that is null, 12/1/20 and 1/5/21 `start_dates` will return the policy, but 2/10/21 wouldn't. Assuming a `start_date` parameter of say, 11/1/20, then an `end_date` of 12/1/20 wouldn't return the policy, but 1/5/21 and 2/10/21 would. Lastly, a `start_date` of 1/5/21 and `end_date` of 1/6/21 would also return the policy. Please note also that while dates in the format MM:DD:YY are being used here, `start_date` and `end_date` must be numbers representing milliseconds since the Unix epoch time.
 
 Policies will be returned in order of effective date (see schema below), with pagination as in the `agency` and `provider` specs.
 
@@ -603,6 +603,7 @@ For each combination of items in a program, you can specify the data specs, APIs
         {
           "data_spec_name": "[DATA SPEC NAME]",
           "version": "[VERSION NUMBER]",
+          "mode": "[MODE SHORTNAME]",
           "required_apis": [
             {
               // Required APIs array
@@ -623,6 +624,7 @@ For each combination of items in a program, you can specify the data specs, APIs
 | -------------------- | ------ | -------- | ----------------------------------- |
 | `data_spec_name`     | Enum   | Required | Name of the data spec required. Supported values are: '[MDS](https://github.com/openmobilityfoundation/mobility-data-specification/tree/ms-requirements)', '[GBFS](https://github.com/NABSA/gbfs/tree/v2.2)'. Others like GOFS, GTFS, TOMP-API, etc can be tested by agencies and officially standardized here in the future -- leave your feedback on [this issue](https://github.com/openmobilityfoundation/mobility-data-specification/issues/682). |
 | `version`            | Text   | Required | Version number of the data spec required. E.g. '1.2.0' |
+| `mode`               | Text   | Optional | The [mode list][modes] shortname for MDS. E.g. 'passenger-services' |
 | `required_apis`      | Array  | Conditionally Required | Name of the [Requirement APIs](#requirement-apis) that need to be served by providers. At least one API is required. APIs not listed will not be available to the agency. |
 | `available_apis`     | Array  | Conditionally Required | Name of the [Requirement APIs](#requirement-apis) that are being served by agencies.  Not applicable to GBFS. APIs not listed will not be available to the provider. |