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_id,agency_city,agency_state_abbr,agency_country_iso_code,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 Versions](#requirement-mds-versions)
+    - [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.
+**Deprecated:** see the new [Geography API](/geography#transition-from-policy) to understand the transistion 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,149 @@ 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 enumerates 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 ensure 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 is not authenticated (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 Requirement 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 versions](#requirement-mds-versions) (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
+  }
+}
+```
+
+| Name                         | Type            | Required / Optional | Description              | 
+| ---------------------------- | --------------- | -------- | ----------------------------------- | 
+| `metadata`                   | Array           | Required | Array of [Requirement Metadata](#requirement-metadata) fields. | 
+| `mds_versions`               | Array           | Required | Array of [Requirement MDS Versions](#requirement-mds-versions) data. | 
+| `mds_apis`                   | Array           | Required | Array of [Requirement MDS APIs](#requirement-mds-apis) data. | 
+
+[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_interval`        | duration        | Required | The expected maximum frequency with which this file could be updated. [ISO 8601 duration](https://en.wikipedia.org/wiki/ISO_8601#Durations). E.g. "P1D" |
+| `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_timezone`            | timezone        | Required | [TZ Database Name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) used for dates and times in Requirements and across all MDS endpoints. E.g. "America/New_York" |
+| `agency_language`            | text            | Required | An [IETF BCP 47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt) language code, used across all MDS endpoints. E.g. "en-US" |
+| `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 Versions
+
+Contains a list of providers and APIs/endpoints/fields that a version of MDS applies to over a certain time frame in its [Requirement](#requirement) data feed in the `mds_versions` section. 
+
+Unique combinations for MDS versions, specific providers, and dates (past, current, or future) can be defined. For example an agency can define 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 starting a month from now, and version 1.1.0 for Provider #2 with docked bikeshare. 
+
+```jsonc
+// ...  
+  "mds_versions": [
+    {
+      "version": "[MDS VERSION NUMBER]",
+      "provider_ids": [
+        "[PROVIDER UUID]",
+        "[PROVIDER UUID]"
+      ],
+      "start_date": [timestamp],
+      "end_date": [timestamp],
+      "required_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 | 
+| `start_date`                 | [timestamp][ts] | Required | Beginning date/time of requirements | 
+| `end_date`                   | [timestamp][ts] | Required | End date/time of requirements. Can be null. Keep data at least one year past `end_date` before removing. | 
+| `required_mds_api`           | Array           | Required | Array of required [MDS APIs](#requirement-mds-apis) |
+
+[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 Versions](#requirement-mds-versions) `mds_apis` section in the [Requirement](#requirement) data feed.
+
+```jsonc
+// ...  
+      "required_mds_apis": [
+        {
+          "api_name" : "[MDS API]",
+          "required_endpoints": [ 
+            {
+              "endpoint_name" : "[ENDPOINT NAME]",
+              "url": "[ENDPOINT URL]",
+              "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. E.g. 'agency' | 
+| `url`                | URL   | Required / Optional | Location of API root URL (minus the endpoint name). Required if the API is unauthenticated and public, optional if endpoint is authenticated and private. E.g. "https://mds.cityname.gov/geographies/geography/1.1.0"  | 
+| `required_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. E.g. "trips" | 
+| `required_fields`    | Array | Optional | Array of optional field names required by the agency. Can be left empty if none are required. See **special notes** below. | 
+
+**Special notes about `required_fields`.** 
+
+- All fields marked 'Required' in MDS are still included by default and should not be enumerated in `required_fields`. They are not affected by the Requirements endpoint.
+- Fields in MDS marked 'Required if available' are still returned if available, and are not affected by the Requirements endpoint.
+- To require [Greography Driven Events](/general-information.md#geography-driven-events), simply include the `event_geographies` field for either the Agency or Provider API `api_name`. Per how GDEs work, `event_location` will then not be returned, and the `changed_geographies` vehicle state `event_type` will be used.
 
 [Top][toc]