Merge pull request #824 from openmobilityfoundation/feature-geography

schnuerle · web-flow · commit 860be27bf0eb · 2023-01-23T15:50:03.000-05:00
Remove Geographies from Policy and make public
diff --git a/README.md b/README.md
@@ -220,7 +220,7 @@ Please [let us know](https://docs.google.com/forms/d/e/1FAIpQLScrMPgeb1TKMYCjjKs
 
 Community projects are those efforts by individual contributors or informal groups that take place outside Open Mobility Foundation’s formalized process, complementing MDS. These related projects often push new ideas forward through experimental or locally-focused development, and are an important part of a thriving open source community. Some of these projects may eventually be contributed to and managed by the Open Mobility Foundation.
 
-The OMF's [Communitiy Projects](https://www.openmobilityfoundation.org/community-projects/) page has an every growing list of projects related to MDS, and see our [Privacy Committee's State of Practice](https://github.com/openmobilityfoundation/privacy-committee/blob/main/products/state-of-the-practice.md) for more examples.
+The OMF's [Community Projects](https://www.openmobilityfoundation.org/community-projects/) page has an every growing list of projects related to MDS, and see our [Privacy Committee's State of Practice](https://github.com/openmobilityfoundation/privacy-committee/blob/main/products/state-of-the-practice.md) for more examples.
 
 Please [let us know](https://www.openmobilityfoundation.org/get-in-touch/) if you create open source or private tools for implementing or working with MDS data.
 
diff --git a/agency/README.md b/agency/README.md
@@ -202,7 +202,7 @@ See [Bulk Responses](#bulk-responses)
 
 **Endpoint:** `/stops`  
 **Method:** `PUT`  
-**Payload**: An array of of [Stop][stops] information, where the permitted changable fields are defined as:
+**Payload**: An array of of [Stop][stops] information, where the permitted changeable fields are defined as:
 
 | Field               | Required/Optional | Description                                 |
 |---------------------|-------------------|---------------------------------------------|
@@ -220,7 +220,7 @@ See [Bulk Responses](#bulk-responses)
 | -------------------- | ------------------------------------------------- | ------------------------------- |
 | `bad_param`          | A validation error occurred                       | Array of parameters with errors |
 | `missing_param`      | A required parameter is missing                   | Array of missing parameters     |
-| `unregisterd` | No stop with `stop_id` is already registered       |                                 |
+| `unregistered` | No stop with `stop_id` is already registered       |                                 |
 
 ### Stops - Readback
 
diff --git a/general-information.md b/general-information.md
@@ -4,6 +4,7 @@ This document contains specifications that are shared between the various MDS [A
 
 ## Table of Contents
 
+- [Authentication](#authentication)
 - [Beta Features](#beta-features)
 - [Costs and Currencies](#costs-and-currencies)
 - [Data Types](#data-types)
@@ -14,14 +15,21 @@ This document contains specifications that are shared between the various MDS [A
   - [Stop-based Geographic Data](#stop-based-geographic-data)
   - [Intersection Operation](#intersection-operation)
 - [Geography-Driven Events](#geography-driven-events)
-- [Optional Authentication](#optional-authentication)
 - [Responses](#responses)
   - [Error Messages](#error-messages)
 - [Strings](#strings)
 - [Timestamps](#timestamps)
 - [UUIDs](#uuids)
 - [Versioning](#versioning)
 
+## Authentication
+
+If implementing MDS Policy, Geography, and/or Jurisdiction APIs and endpoints, an agency must make them unauthenticated and public. This allows transparency for the public to see how the city is regulating, holds the city accountable for their policy decisions, and reduces the technical burden on providers to use these endpoints. A side benefit is that this allows third parties to ingest this information into their applications and services for public benefit.
+
+All other MDS APIs require authentication, as outlined.
+
+[Top][toc]
+
 ## Beta Features
 
 In some cases, features within MDS may be marked as "beta." These are typically recently added endpoints or fields. Because beta features are new, they may not yet be fully mature and proven in real-world operation. The design of beta features may have undiscovered gaps, ambiguities, or inconsistencies. Implementations of those features are typically also quite new and are more likely to contain bugs or other flaws. Beta features are likely to evolve more rapidly than other parts of the specification.
@@ -110,14 +118,6 @@ During the Beta period for this feature, location and telemetry data remain requ
 
 [Top][toc]
 
-## Optional Authentication
-
-Authorization of the Policy and Geography APIs is no longer required and will be deprecated in next major release with these endpoints (plus Jurisdictions) becoming 'optionally private' instead of 'optionally public'. An agency may optionally decide to make the Policy and Geography endpoints, as well as Jurisdictions, unauthenticated and public. This allows transparency for the public to see how the city is regulating, holds the city accountable for their policy decisions, and reduces the technical burden on providers to use these endpoints. A side benefit is that this allows third parties to ingest this information into their applications and services for public benefit.
-
-Note if implementing the beta feature [Geography Driven Events](/general-information.md#geography-driven-events), both Policy and Geography must be public.
-
-[Top][toc]
-
 ## Responses
 
 * **200:** OK: operation successful.
@@ -219,7 +219,7 @@ the vehicle and canceling or ending the trip in under 60 seconds.
 
 Providers are still expected to report all trips and trip related events in
 all MDS endpoints, but parties may use this definition as a shared reference
-at the recommendation of the MDS community when analysing trips.
+at the recommendation of the MDS community when analyzing trips.
 
 [Top][toc]
 
diff --git a/geography/README.md b/geography/README.md
@@ -12,7 +12,6 @@ Geographical data will be stored as GeoJSON and read from either `geographies.js
 
 * [General Information](#general-information)
   * [Versioning](#versioning)
-  * [Transition from Policy](#transition-from-policy)
 * [Distribution](#distribution)
   * [Flat Files](#flat-files)
   * [Response Format](#response-format)
@@ -41,14 +40,6 @@ Versioning must be implemented as specified in the [Versioning section][versioni
 
 [Top][toc]
 
-### Transition from Policy
-
-To ensure this Geography API is not creating a breaking change for the 1.1.0 release, it's expected that the data contained in the [`/geographies`](/policy#geography) endpoint in the Policy API is identical to this Geography API. This will ensure that when a Geography ID is used anywhere in this release, the data could be retrieved from either location.
-
-This temporary requirement is to ensure backwards compatibility, but the overall intent is to remove the /policy/geographies endpoint at the next major MDS release.
-
-[Top][toc]
-
 ## Distribution
 
 Geographies shall be published by regulatory agencies or their authorized delegates as JSON objects. These JSON objects shall be served by either [flat files](#flat-files) or via [REST API endpoints](#rest-endpoints). In either case, geography data shall follow the [schema](#schema) outlined below.
@@ -65,7 +56,7 @@ Geographies should be re-fetched at an agreed upon interval between providers an
 
 To use a flat file, geographies shall be represented in one (1) file equivalent to the /geographies endpoint:
 
-* `geographies.json`
+* `geographies.json` in Geography API
 
 The files shall be structured like the output of the [REST endpoints](#rest-endpoints) above.
 
@@ -83,7 +74,7 @@ See the [Responses][responses] and [Error Messages][error-messages] sections.
 
 ### Authorization
 
-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.
+This endpoint should be made public. Authorization is not required.
 
 [Top][toc]
 
@@ -99,7 +90,7 @@ See the [Endpoints](#endpoints) below for links to their specific JSON Schema do
 | ----------------   | --------- | --- | --------------------------------------------------------------------------------------------- |
 | `name`             | String    | Required   | Name of geography                                                                      |
 | `description`      | String    | Optional   | Detailed description of geography                                                      |
-| `geography_type`   | String     | Optional   | Type of geography, e.g. `municipal_boundary` or `council_district` or custom text.  See [Geography Types](#geography-types). |
+| `geography_type`   | String     | Optional   | Type of geography, e.g. `municipal_boundary` or `council_district` or custom text.  See [Geography Type](#geography-type). |
 | `geography_id`     | UUID      | Required   | Unique ID of geography                                                                 |
 | `geography_json`   | JSON      | Required   | The GeoJSON that defines the geographical coordinates.                                 |
 | `effective_date`   | [timestamp][ts] | Optional   | The date at which a Geography is considered "live".  Must be at or after `published_date`. |
@@ -134,7 +125,7 @@ Type of geography. These specific types are recommendations based on ones common
 | `neighborhood`       | Neighborhood area                    |
 | `market_area`        | Economic area                        |
 | `opportunity_zone`   | Defined Opportunity Zone             |
-| `overlay_district`   | Agengy overlay district              |
+| `overlay_district`   | Agency overlay district              |
 | `post_code`          | Zip or postal code                   |
 | `traffic_zone`       | Transportation planning area         |
 | `property_line`      | One or more property lines           |
diff --git a/jurisdiction/README.md b/jurisdiction/README.md
@@ -2,7 +2,7 @@
 
 <a href="/jurisdiction/"><img src="https://i.imgur.com/tCRCfxT.png" width="120" align="right" alt="MDS Jurisdiction Icon" border="0"></a>
 
-This specification details the purpose, use cases, and schema for Jurisdictions. Jurisdictions are an optional service that are served by a coordinated group of agencies. Jurisdictions can be '[optionally authenticated](/general-information.md#optional-authentication)', making the endpoints unauthenticated and public. In the future this will shift to 'optionally private', where Jursidictions will be public by default. Note that it serves a different purpose from the [Geography](/geography) API, though it does reference areas within Geography by ID.
+This specification details the purpose, use cases, and schema for Jurisdictions. Jurisdictions are an optional service that are served by a coordinated group of agencies. Jurisdictions should be unauthenticated and public. Note that Jurisdictions serves a different purpose from the [Geography](/geography) API, though it does reference areas within Geography by ID.
 
 ## Table of Contents
 
@@ -68,7 +68,7 @@ Those tools can be granted data access from the SaaS tool based on the jurisdict
 
 ## Distribution
 
-Jurisdictions can be served by agencies through the following REST API, or via [flat-files](#flat-files). Agencies may choose to make the endpoints public and non-authenticated.
+Jurisdictions can be served by agencies through the following REST API, or via [flat-files](#flat-files). Agencies should make the endpoints public and non-authenticated.
 
 ### REST
 
diff --git a/policy/README.md b/policy/README.md
@@ -19,7 +19,6 @@ This specification describes the digital relationship between _mobility as a ser
   - [Policies](#policies)
     - [Query Parameters](#query-parameters)
   - [Geographies](#geographies)
-    - [Query Parameters](#query-parameters-1)
   - [Requirements](#requirements)
 - [Flat Files](#flat-files)
   - [Example `policies.json`](#example-policiesjson)
@@ -30,7 +29,6 @@ This specification describes the digital relationship between _mobility as a ser
   - [Rules](#rules)
   - [Rule Types](#rule-types)
   - [Rule Units](#rule-units)
-  - [Geography](#geography)
   - [Rates](#rates)
     - [Rate Amounts](#rate-amounts)
     - [Rate Recurrences](#rate-recurrences)
@@ -124,7 +122,7 @@ See the [Responses section][responses] for information on valid MDS response cod
 
 ### Authorization
 
-Authorization is not required and agencies are encouraged to make these endpoints unauthenticated and public. See [Optional Authentication](/general-information.md#optional-authentication) for details.
+This endpoint should be made public. Authorization is not required.
 
 ### Policies
 
@@ -149,18 +147,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 transition away from this endpoint, and how to support both in MDS 1.x.0 releases.
-
-**Endpoint**: `/geographies/{id}`  
-**Method**: `GET`  
-**Schema:** [`policy` schema][json-schema]  
-**`data` Payload**: `{ geographies: [] }`, an array of GeoJSON `Feature` objects that follow the schema [outlined here](#geography) or in [Geography](/geography#general-information).
-
-#### 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.               |
+**Deprecated:** see the [Geography API](/geography#transition-from-policy) for the current home of this endpoint.
 
 [Top][toc]
 
@@ -180,12 +167,12 @@ See [Policy Requirements Examples](/policy/examples/requirements.md) for how thi
 
 To use flat files, policies shall be represented in two (2) files:
 
-- `policies.json`
-- `geographies.json`
+- `policies.json` in Policy API
+- `geographies.json` in Geography API
 
 The files shall be structured like the output of the [REST endpoints](#rest-endpoints) above.
 
-The publishing Agency should establish and communicate to providers how frequently these files should be polled.
+The publishing agency should establish and communicate to providers how frequently these files should be polled.
 
 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.
 
@@ -333,28 +320,14 @@ An individual `Rule` object is defined by the following fields:
 
 [Top][toc]
 
-### Geography
-
-**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                                                                         |
-| ---------------- | --------- | --- | ----------------------------------------------------------------------------------- |
-| `name`           | String    | Required   | Name of geography                                                                      |
-| `description`    | String    | Optional   | Detailed description of geography                                                                      |
-| `geography_id`   | UUID      | Required   | Unique ID of [Geography](/geography#general-information)                                               |
-| `geography_json`   | JSON      | Required   | The GeoJSON that defines the geographical coordinates.
-| `effective_date`   | [timestamp][ts] | Optional   | `start_date` for first published policy that uses this geo.  Server should set this when policies are published.  This may be used on the client to distinguish between “logical” geographies that have the same name. E.g. if a policy publishes a geography on 5/1/2020, and then another policy is published which references that same geography is published on 4/1/2020, the effective_date will be set to 4/1/2020.
-| `published_date`   | [timestamp][ts] | Required   | Timestamp that the policy was published, i.e. made immutable                                             |
-| `prev_geographies`  | UUID[]    | Optional   | Unique IDs of prior [geographies](/geography#general-information) replaced by this one                                   |
-
-[Top][toc]
-
 ### Rates
+
 Rate-related properties can currently be specified on all rule types except `user`, i.e. any rule that can be measured.
 
 **[Beta feature](/general-information.md#beta-features)**: *No (as of 2.0.0)*. [Leave feedback](https://github.com/openmobilityfoundation/mobility-data-specification/issues/674)  
 
 #### Rate Amounts
+
 The amount of a rate applied when this rule applies, if applicable (default zero). A positive integer rate amount represents a fee, while a negative integer represents a subsidy. Rate amounts are given in the `currency` defined in the [Policy](#policy).
 
 #### Rate Recurrences
