Policy Requirements

README.md

@@ -138,6 +138,8 @@ More than 115 cities and public agencies around the world use MDS, and it has be
 
 Please let us know [via our website](https://www.openmobilityfoundation.org/get-in-touch/) or in the [public discussion area](https://github.com/openmobilityfoundation/mobility-data-specification/discussions) if you are an agency using MDS so we can add you to the city resource list, especially if you have published your policies or documents publicly.
 
+To add yourself to the [agency list](/agencies.csv) and add your [Policy Requirement link](/provider.md#requirements), 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). 
+
 [Top][toc]
 
 # Providers Using MDS

agencies.csv

@@ -0,0 +1,2 @@
+agency_name,agency_city,agency_state_abbr,agency_country_iso_code,agency_id,department_url,requirement_url
+Louisville Metro,44bc31a7-464b-4ed9-b52e-8e74630826bd,Louisville,KY,US,https://louisvilleky.gov/government/public-works/dockless-find-and-ride-vehicles,https://mds.cityname.gov/requirements/1.2.0

policy/README.md

@@ -13,8 +13,11 @@ This specification describes the digital relationship between _mobility as a ser
   - [Update Frequency](#update-frequency)  
 - [Background](#background)
 - [Distribution](#distribution)
-  - [REST Endpoints](#rest-endpoints)
-  - [Flat Files](#flat-files)
+- [REST Endpoints](#rest-endpoints)
+  - [Policies](#policies)
+  - [Geographies](#geographies)
+  - [Requirements](#requirements)
+- [Flat Files](#flat-files)
 - [Schema](#schema)
   - [Policy](#policy)
   - [Rules](#rules)
@@ -25,7 +28,11 @@ This specification describes the digital relationship between _mobility as a ser
   - [Messages](#messages)
   - [Value URL](#value-url)
   - [Order of Operations](#order-of-operations)
-
+  - [Requirement](#requirement)
+    - [Metadata](#requirement-metadata)
+    - [MDS Version](#requirement-mds-version)
+    - [MDS APIs](#requirement-mds-apis)
+
 ## General information
 
 The following information applies to all `policy` API endpoints.
@@ -82,7 +89,7 @@ Flat files have an optional `end_date` field that will apply to the file as a wh
 
 [Top][toc]
 
-### REST Endpoints
+## REST Endpoints
 
 Among other use-cases, configuring a REST API allows an Agency to:
 
@@ -93,7 +100,7 @@ Among other use-cases, configuring a REST API allows an Agency to:
 
 Responses must set the `Content-Type` header, as specified in the [versioning][versioning] section.
 
-#### Responses and Error Messages
+### Responses and Error Messages
 
 The response to a client request must include a valid HTTP status code defined in the [IANA HTTP Status Code Registry][iana].
 
@@ -103,13 +110,13 @@ See the [Responses section][responses] for information on valid MDS response cod
 
 Authorization is not required. An agency may decide to make this endpoint unauthenticated and public. See [Optional Authentication](/general-information.md#optional-authentication) for details.
 
-#### Policies
+### Policies
 
 Endpoint: `/policies/{id}`  
 Method: `GET`  
 `data` Payload: `{ "policies": [] }`, an array of objects with the structure [outlined below](#policy).
 
-##### Query Parameters
+#### Query Parameters
 
 | Name         | Type      | Required / Optional | Description                                    |
 | ------------ | --------- | --- | ---------------------------------------------- |
@@ -123,24 +130,34 @@ Policies will be returned in order of effective date (see schema below), with pa
 
 `provider_id` is an implicit parameter and will be encoded in the authentication mechanism, or a complete list of policies should be produced. If the Agency decides that Provider-specific policy documents should not be shared with other Providers (e.g. punitive policy in response to violations), an Agency should filter policy objects before serving them via this endpoint.
 
-#### Geographies
+### Geographies
 
-**Note:** see the new [Geography API](/geography#transition-from-policy) to understand the transisiton away from this endpoint, and how to support both in the MDS 1.1.0 release.
+**Depreciated:** see the new [Geography API](/geography#transition-from-policy) to understand the transisiton away from this endpoint, and how to support both in a MDS 1.x.0 release.
 
 Endpoint: `/geographies/{id}`  
 Method: `GET`  
 `data` Payload: `{ geographies: [] }`, an array of GeoJSON `Feature` objects that follow the schema [outlined here](#geography) or in [Geography](/geography#general-information).
 
-##### Query Parameters
+#### Query Parameters
 
 | Name         | Type      | Required / Optional | Description                                    |
 | ------------ | --------- | --- | ---------------------------------------------- |
 | `id`         | UUID      | Optional    | If provided, returns one [Geography](/geography#general-information) object with the matching UUID; default is to return all geography objects.               |
 
 [Top][toc]
 
+### Requirements
 
-### Flat Files
+Endpoint: `/requirements/`  
+Method: `GET`  
+`data` Payload: `{ requirements: [] }`, JSON objects that follow the schema [outlined here](#requirement).
+[Beta feature](/general-information.md#beta-features): *Yes (as of 1.2.0)*.
+
+See [Policy Requierment Examples](/policy/examples/requirements.md) for how this can be implemented.
+
+[Top][toc]
+
+## Flat Files
 
 To use flat files, policies shall be represented in two (2) files:
 
@@ -153,7 +170,7 @@ The publishing Agency should establish and communicate to providers how frequent
 
 The `updated` field in the payload wrapper should be set to the time of publishing a revision, so that it is simple to identify a changed file.
 
-#### Example `policies.json`
+### Example `policies.json`
 
 ```jsonc
 {
@@ -175,7 +192,7 @@ The `updated` field in the payload wrapper should be set to the time of publishi
 
 The optional `end_date` field applies to all policies represented in the file.
 
-#### Example `geographies.json`
+### Example `geographies.json`
 
 ```jsonc
 {
@@ -296,6 +313,8 @@ An individual `Rule` object is defined by the following fields:
 
 ### Geography
 
+**Depreciated:** see the new [Geography API](/geography#transition-from-policy) to understand the transisiton away from this endpoint, and how to support both in a MDS 1.x.0 release.
+
 | Name             | Type      | Required / Optional | Description                                                                         |
 | ---------------- | --------- | --- | ----------------------------------------------------------------------------------- |
 | `name`           | String    | Required   | Name of geography                                                                      |
@@ -365,6 +384,130 @@ If a vehicle is matched with a rule, then it _will not_ be considered in the sub
 
 The internal mechanics of ordering are up to the Policy editing and hosting software.
 
+[Top][toc]
+
+### Requirement
+
+The agency Policy Requirement file ennumerates all of the parts of MDS that an agency requires from providers, including APIs, endpoints, and optional fields, as well as information for providers about the APIs the agency is hosting. The requirements are specific to the needs and use cases of each agency, and ensures there is clarity on what data is being asked for in operating policy documents from providers, reducing the burden on both. This also allows additional public transparency and accountability around data requirements from agencies, and encourages privacy by allowing agencies to ask for only the data they need.
+
+This endpoint it not authenicated (ie. public), and allows the discovery of other public APIs like Geography, Policy, and Jurisdiction. The agency can host this as a file or API on their servers, on a third party server, or the OMF can host on behalf of an agency in the [agency requirements repo](#). See this [hosting guidance document](#) for more information.  This requirements file can be [referenced directly](https://github.com/openmobilityfoundation/governance/blob/main/technical/OMF-MDS-Policy-Language-Guidance.md) in an agency's operating permit/policy document when discussing program data requirements.
+
+See [Policy Requierment Examples](/policy/examples/requirements.md) for how this can be implemented.
+
+An agency's [Requirements](#requirements) endpoint contains a number of distinct parts, namely [metadata](#requirement-metadata) and [MDS version](#requirement-mds-version) (with sub sections on applicable providers and relevant [MDS APIs](#requirement-mds-apis)). 
+
+```jsonc
+{
+  "metadata": {
+    // metadata fields per the "Requirement Metadata" section
+  },
+  "mds_versions" [ 
+    {
+      "version" : "[MDS VERSION NUMBER]",
+      "provider_ids": [
+        // provider id array
+      ],
+      "mds_apis": [
+        {
+          "api_name" : "[MDS API]": {
+            // MDS endpoints, urls, optional fields
+          }
+        },
+        // other MDS APIs per the "Requirement MDS APIs" section
+      ]
+    }, 
+    // other MDS versions per the "Requriement MDS Version" section
+  }
+}
+```
+[Top][toc]
+
+#### Requirement Metadata
+
+Contains metadata applicable to the agency and at the top of its [Requirement](#requirement) data feed in the `metadata` section. 
+
+| Name                         | Type            | Required / Optional | Description              |
+| ---------------------------- | --------------- | -------- | ----------------------------------- |
+| `mds_release`                | text            | Required | Release of MDS that the requirements data feed aligns to, based on official MDS releases. E.g. "1.2.0" |
+| `version`                    | integer         | Required | Version of this file. Increment 1 with each modification. E.g. "3" |
+| `last_updated`               | [timestamp][ts] | Required | When this file `version` was last updated. E.g. "1611958740" |
+| `max_update_frequency`       | integer         | Required | The expected maximum frequency with which this file could be updated. E.g. "P1D" |
+| `omf_review`                 | Enum            | Required | yes/no. Was this file reviewed by OMF Staff for accuracy? E.g. "yes" |
+| `omf_review_date`            | [timestamp][ts] | Optional | If `omf_review`, add timestamp. E.g. "1611958749" |
+| `agency_uuid`                | UUID            | Required | UUID of the agency this file applies to. Must come from [agencies.csv](/agencies.csv) file. E.g. "737a9c62-c0cb-4c93-be43-271d21b784b5" |
+| `agency_name`                | text            | Required | Name of the agency this file applies to. E.g. "Louisville Metro" |
+| `agency_time_zone`           | text            | Required | Timezone used for dates and times across all MDS endpoints. E.g. "America/New_York" |
+| `agency_currency`            | text            | Required | Currency used for all monetary values across all MDS endpoints. E.g. "USD" |
+| `agency_policy_website_url`  | URL             | Required | URL of the agency's transportation policy page. E.g. "https://www.cityname.gov/transporation/shared-devices.htm" |
+| `agency_policy_document_url` | URL             | Optional | URL of the agency's operating permit rules that mention data requirements. E.g. "https://www.cityname.gov/mds_data_policy.pdf" |
+| `gbfs_required`              | Enum            | Required | yes/no. Is public GBFS required explicitly by providers? E.g. "yes" |
+| `url`                        | URL             | Required | URL of this file. E.g.  "https://mds.cityname.gov/requirements/1.2.0" |
+
+[Top][toc]
+
+#### Requirement MDS Version
+
+Contains a list of providers and APIs/endpoints/fields that a version of MDS applies to in its [Requirement](#requirement) data feed. Unique combinations for MDS versions and specific providers can be defined. For example an agency can devine MDS version 1.2.0 for Provider #1 in a pilot with beta endpoints and optional fields, version 1.2.0 for other providers without beta features, and version 1.1.0 for Provider #2 with docked bikeshare. 
+
+```jsonc
+// ...  
+  "mds_versions": [
+    {
+      "version" : "[MDS VERSION NUMBER]",
+      "provider_ids": [
+        "[PROVIDER UUID]",
+        "[PROVIDER UUID]"
+      ],
+      "mds_apis" [
+        {
+          // ...
+        },
+        // other MDS APIs
+      ]
+    }
+  ]
+// ...
+```
+
+| Name                         | Type           | Required / Optional | Description              | 
+| ---------------------------- | -------------- | -------- | ----------------------------------- | 
+| `version`                    | text           | Required | Version number of an official MDS release | 
+| `provider_ids`               | UUID[]         | Required | Array of providers that apply to this part of the requirements | 
+
+[Top][toc]
+
+#### Requirement MDS APIs
+
+For each combination of MDS version and provider list, you can specify the MDS APIs, endpoints, and optional fields that are required per your agency's policy. This is an array within the [Requirement MDS Version](#requirement-mds-version) `mds_apis` section in the [Requirement](#requirement) data feed.
+
+```jsonc
+// ...  
+      "mds_apis": [
+        {
+          "api_name" : "[MDS API]",
+          "url": "[ENDPOINT ROOT URL]",
+          "endpoints": [ 
+            {
+            "endpoint_name" : "[ENDPOINT NAME]",
+              "required_fields": [
+                "[FIELD NAME]",
+                // other field names
+              ]
+            } 
+          ]
+        },
+        // other MDS APIs
+      ]
+// ...
+```
+
+| Name              | Type  | Required / Optional | Description              | 
+| ----------------- | ----- | -------- | ----------------------------------- | 
+| `api_name`        | Enum  | Required | Name of the applicable MDS API: provider, agency, policy, geography, jurisdiction, metrics. At least one is required. | 
+| `url`             | URL   | Required / Optional | Location of API root URL (minus the endpoint name) if the API is unauthenticated and public.   | 
+| `endpoints`       | Array | Required | Array of endpoints required. At least one is required. | 
+| `endpoint_name`   | Text  | Required | Name of required endpoint. At least one is required. | 
+| `required_fields` | Array | Optional | Array of optional field names required by the agency. Can be left empty if none are required. | 
 
 [Top][toc]
 

policy/examples/requirements.md

@@ -0,0 +1,118 @@
+# Policy Requirement Examples
+
+This file presents a series of example [Policy documents](../README.md#requirement) for Agencies to use as templates.
+
+## Table of Contents
+
+- [Trips Only](#trips-only)
+- [Vehicles Only](#vehicles-only)
+
+## Trips Only
+
+Version 1.1.0 for 2 providers requiring only Provider `/trips` with the optional `parking_verificaiton_url` field.  
+
+```json
+{
+  "metadata": {
+    "mds_release": "1.2.0",
+    "version": "3",
+    "last_updated": "1611958740",
+    "max_update_frequency": "P1D",
+    "omf_review": "yes",
+    "omf_review_date": "1611958749",
+    "agency_uuid": "737a9c62-c0cb-4c93-be43-271d21b784b5",
+    "agency_name": "Louisville Metro",
+    "agency_time_zone": "America/New_York",
+    "agency_currency": "USD",
+    "agency_policy_website_url": "https:/www.cityname.gov/transporation/shared-devices.html",
+    "agency_policy_document_url": "https://www.cityname.gov/mds_data_policy.pdf",
+    "gbfs_required": "yes",
+    "url": "https://mds.cityname.gov/requirements/1.2.0"
+  },
+  "mds_versions": [
+    {
+      "version": "1.1.0",
+      "provider_ids": [
+        "70aa475d-1fcd-4504-b69c-2eeb2107f7be",
+        "2411d395-04f2-47c9-ab66-d09e9e3c3251"
+      ],
+      "mds_apis": [
+        {
+          "api_name": "provider",
+          "endpoints": [ 
+            {
+              "endpoint_name" : "trips",
+              "required_fields": [
+                "parking_verification_url"
+              ]
+            } 
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+[Top](#table-of-contents)
+
+## Vehicles Only
+
+Version 1.1.0 for one provider and 1.0.0 for another provider, requiring only the Provider `/vehicles` endpoint and no optional fields, as an authenticated [alternative to GBFS](https://github.com/openmobilityfoundation/mobility-data-specification/wiki/MDS-Vehicles) for internal use.
+
+```json
+{
+  "metadata": {
+    "mds_release": "1.2.0",
+    "version": "2",
+    "last_updated": "1611958740",
+    "max_update_frequency": "T1M",
+    "omf_review": "yes",
+    "omf_review_date": "1611958749",
+    "agency_uuid": "737a9c62-c0cb-4c93-be43-271d21b784b5",
+    "agency_name": "Louisville Metro",
+    "agency_time_zone": "America/New_York",
+    "agency_currency": "USD",
+    "agency_policy_website_url": "https:/www.cityname.gov/transporation/shared-devices.html",
+    "agency_policy_document_url": "https://www.cityname.gov/mds_data_policy.pdf",
+    "gbfs_required": "yes",
+    "url": "https://mds.cityname.gov/requirements/1.2.0"
+  },
+  "mds_versions": [
+    {
+      "version": "1.1.0",
+      "provider_ids": [
+        "70aa475d-1fcd-4504-b69c-2eeb2107f7be"
+      ],
+      "mds_apis": [
+        {
+          "api_name": "provider",
+          "endpoints": [ 
+            {
+              "endpoint_name" : "vehicles"
+            } 
+          ]
+        }
+      ]
+    },
+    {
+      "version": "1.0.0",
+      "provider_ids": [
+        "2411d395-04f2-47c9-ab66-d09e9e3c3251"
+      ],
+      "mds_apis": [
+        {
+          "api_name": "provider",
+          "endpoints": [ 
+            {
+              "endpoint_name" : "vehicles"
+            } 
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+[Top](#table-of-contents)