Merge pull request #813 from openmobilityfoundation/feature-requirements-3

Policy Requirements - Use Case Support and move out of beta

Author: schnuerle

policy/README.md

@@ -149,7 +149,7 @@ Policies will be returned in order of effective date (see schema below), with pa
 
 ### Geographies
 
-**Deprecated:** see the new [Geography API](/geography#transition-from-policy) to understand the transistion away from this endpoint, and how to support both in MDS 1.x.0 releases.
+**Deprecated:** see the new [Geography API](/geography#transition-from-policy) to understand the transition away from this endpoint, and how to support both in MDS 1.x.0 releases.
 
 **Endpoint**: `/geographies/{id}`  
 **Method**: `GET`  
@@ -168,8 +168,8 @@ Policies will be returned in order of effective date (see schema below), with pa
 
 **Endpoint**: `/requirements/`  
 **Method**: `GET`  
-**[Beta feature](/general-information.md#beta-features)**: *Yes (as of 1.2.0)*. [Leave feedback](https://github.com/openmobilityfoundation/mobility-data-specification/issues/682)  
-**Schema:** TBD when out of beta
+**[Beta feature](/general-information.md#beta-features)**: *No (as of 2.0.0)*. 
+**Schema:** TBD
 **`data` Payload**: `{ requirements: [] }`, JSON objects that follow the schema [outlined here](#requirement).  
 
 See [Policy Requirements Examples](/policy/examples/requirements.md) for how this can be implemented.
@@ -337,7 +337,7 @@ An individual `Rule` object is defined by the following fields:
 
 ### Geography
 
-**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.
+**Deprecated:** see the new [Geography API](/geography#transition-from-policy) to understand the transition away from this endpoint, and how to support both in a MDS 1.x.0 release.
 
 | Name             | Type      | Required / Optional | Description                                                                         |
 | ---------------- | --------- | --- | ----------------------------------------------------------------------------------- |
@@ -434,7 +434,7 @@ The internal mechanics of ordering are up to the Policy editing and hosting soft
 
 ### Requirement
 
-A public agency's Policy program Requirements endpoint enumerates all of the parts of MDS, GBFS, and other specifications that an agency requires from providers for certain programs, including APIs, endpoints, and optional fields, as well as information for providers about the APIs the agency is hosting. The program 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.
+A public agency's Policy program Requirements endpoint enumerates all of the parts of MDS, [CDS](https://github.com/openmobilityfoundation/curb-data-specification), GBFS, and other specifications that an agency requires from providers for certain programs, including APIs, endpoints, and optional fields, as well as information for providers about the APIs the agency is hosting. The program 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.
 
 Requirements can also be used to define a scaled-down MDS implementation in situations where an agency has more limited regulatory goals, has legal limitations on the types of data they can collect, or wants to use a lightweight version of MDS for a pilot project or other experiment where aspects of a full MDS implementation would be irrelevant or unnecessary.
 
@@ -454,10 +454,6 @@ If you are upgrading to a new MDS version, it is recommended to create a new req
 
 When requirements are updated within the same MDS version, in the [metadata](#requirement-metadata) section, increment the `file_version` value by one and update the `last_updated` timestamp. Though not required, you may choose to use the  `start_date` and `end_date` fields in the [programs](#requirement-programs) section to keep retired requirements accessible. We also recommend hosting your requirements file in a location that has a publicly-accessible version history, like GitHub or Bitbucket, or keeping previous versions accessible with a versioned URL, e.g. "https://mds.cityname.gov/requirements/1.2.0/v3". 
 
-#### Beta Limitations
-
-Note that while Requirements is in [beta](#Requirements) in this **minor**, non-breaking MDS 1.2.0 release, items listed as "required" or "disallowed" will be treated as a _request_ only by default (precluding intentional formal agency communications with providers) to prevent an _unintentional_ burden on providers. For the next **major**, breaking MDS 2.0.0 release, these items will be required or disallowed as documented.
-
 #### Requirement Format
 
 An agency's program [Requirements](#requirements) endpoint contains a number of distinct parts, namely [metadata](#requirement-metadata), [program definitions](#requirement-programs), and [data specs](#requirement-data-specs) (with sub sections on relevant [required APIs](#requirement-apis)).
@@ -493,7 +489,7 @@ An agency's program [Requirements](#requirements) endpoint contains a number of
         // other data specs per the "Requirement Data Specs" section
       ]
     },
-    // other MDS versions per the "Requriement MDS Version" section
+    // other MDS versions per the "Requirement MDS Version" section
   }
 }
 ```
@@ -622,7 +618,7 @@ For each combination of items in a program, you can specify the data specs, APIs
 
 | Name                 | Type   | Required / Optional | Description              |
 | -------------------- | ------ | -------- | ----------------------------------- |
-| `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). |
+| `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)', '[CDS](https://github.com/openmobilityfoundation/curb-data-specification)' '[GBFS](https://github.com/NABSA/gbfs/tree/v2.2)'. Others like GOFS, GTFS, TOMP-API, etc may also be referenced now 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. |
@@ -632,7 +628,7 @@ For each combination of items in a program, you can specify the data specs, APIs
 
 #### Requirement APIs
 
-For each data specification, you can specify which APIs, endpoints, and fields are required from providers, and which are available from your agency.
+For each data specification, you can specify which APIs, endpoints, and fields are required from providers, and which are available from your agency, and the use cases you need the data for.
 
 An agency may require providers to serve optional APIs, endpoints, and fields that are needed for your agency's program. This is a `required_apis` array within the [Requirement Data Specs](#requirement-data-specs) section in the [Requirement](#requirement) data feed.
 
@@ -659,8 +655,7 @@ You may also show which APIs, endpoints, and fields your agency is serving to pr
                 },
                 // other endpoints
               ]
-            },
-            // other APIs in same data spec
+            }
           ],
           "available_apis": [
             {
@@ -677,6 +672,14 @@ You may also show which APIs, endpoints, and fields your agency is serving to pr
                 // other endpoints
               ]
             }
+          ],
+          // other APIs in same data spec
+          "use_cases": [
+            {
+              "external_url": "[REFERENCE URL]",
+              "ids": ["1","2","3"]
+            },
+            // next external use case source
           ]
 // ...
 ```
@@ -685,6 +688,7 @@ You may also show which APIs, endpoints, and fields your agency is serving to pr
 | -------------------- | ----- | -------- | ----------------------------------- |
 | `api_name`           | Text  | Required | Name of the applicable API required. At least one API is required. APIs not listed will not be available to the agency. E.g. for MDS: 'provider', or 'agency'. For GBFS, this field is omitted since GBFS starts at the `endpoint` level. |
 | `endpoint_name`      | Text  | Required | Name of the required endpoint under the API. At least one endpoint is required. E.g. for MDS 'provider': 'trips' |
+| `use_cases`      | Object with Array  | Optional | The list of policy uses cases that this data standard's information covers for your program. Includes an `external_url` to a HTTP reference list or database (e.g. to the [OMF Use Case Database](https://airtable.com/shrPf4QvORkjZmHIs/tblzFfU6fxQm5Sdhm)), **and** an array of `ids` of each applicable use case (e.g. "OMF-MDS-31"). You may enumerate multiple external use case sources and ids. |
 
 **Provider Endpoints** - Specific to the `required_apis` array
 
@@ -707,9 +711,8 @@ You may also show which APIs, endpoints, and fields your agency is serving to pr
 - 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, unless explicitly listed in `disallowed_fields`.
 - Fields in MDS marked 'Required if available' are still returned if available, and are not affected by the Requirements endpoint, unless explicitly listed in `disallowed_fields`.
 - If a 'Required' or 'Required if available' or 'Optional' field in MDS is listed in `disallowed_fields`, those fields should not be returned by the provider in the endpoint. The field (and therefore its value) must be completely removed from the response. If used, [schema](/schema) validation may fail on missing required fields.
-- To reference fields that are lower in a heirarchy, use [dot separated notation](https://docs.oracle.com/en/database/oracle/oracle-database/18/adjsn/simple-dot-notation-access-to-json-data.html#GUID-7249417B-A337-4854-8040-192D5CEFD576), where a dot between field names represents one nested level deeper into the data structure. E.g. 'gps.heading' or 'features.properties.rules.vehicle_type_id'.
-- 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.
-- [While in beta](#beta-limitations), items marked as required or disallowed will only be considered a 'request' by providers, unless agencies have communicated with providers outside of MDS.
+- To reference fields that are lower in a hierarchy, use [dot separated notation](https://docs.oracle.com/en/database/oracle/oracle-database/18/adjsn/simple-dot-notation-access-to-json-data.html#GUID-7249417B-A337-4854-8040-192D5CEFD576), where a dot between field names represents one nested level deeper into the data structure. E.g. 'gps.heading' or 'features.properties.rules.vehicle_type_id'.
+- To require [Geography 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]
 

policy/examples/requirements.md

@@ -318,7 +318,7 @@ Version 1.1.0 for 2 providers asking for only historic [Provider `/trips`](/prov
 
 ## Provider and Other APIs
 
-Version 1.1.0 or 0.4.1 for 3 providers with many APIs and endpoints.  
+Version 1.1.0 or 0.4.1 for 3 providers with many APIs and endpoints, for two programs: shared dockless and city docked bikes. With use cases added.
 
 Note: by specifying geography, policy, and jurisdiction here with a URL, the agency is in effect saying that they have created and are hosting these, and they are available for use if public.
 
@@ -431,6 +431,14 @@ Note: by specifying geography, policy, and jurisdiction here with a URL, the age
             {
               "api_name": "metrics"
             }
+          ],
+          "use_cases": [
+            {
+              "external_url": "https://airtable.com/shrPf4QvORkjZmHIs/tblzFfU6fxQm5Sdhm",
+              "ids": ["OMF-MDS-2","OMF-MDS-8","OMF-MDS-12","OMF-MDS-13","OMF-MDS-14","OMF-MDS-20","OMF-MDS-29","OMF-MDS-31","OMF-MDS-44"]
+            },
+              "external_url": "https://github.com/CDSM-WG/CDS-M/tree/main/use-cases",
+              "ids": ["open-data","most-used-routes","vehicle-cap","impact-on-transit","origins","vehicle-rotation","distribution-requirements-availability","distribution-requirements-availability","publish-speed-regulations"]
           ]
         },
         {
@@ -699,7 +707,6 @@ Since Requirements allows the GBFS versions and optional endpoints and fields to
                 {
                   "endpoint_name": "system_pricing_plans.json",
                   "required_fields": [
-                    "per_km_pricing",
                     "per_km_pricing",
                     "surge_pricing"
                   ]