Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Remove Geographies from Policy and make public #824

Merged
merged 8 commits into from
Jan 23, 2023
Merged

Remove Geographies from Policy and make public #824

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
a95cfe9
Removing Geography from Policy
schnuerle Jan 23, 2023
2c8a0c0
Fixing TOC
schnuerle Jan 23, 2023
f264942
Adding TOC link
schnuerle Jan 23, 2023
5cce620
Fixed link to geography types, public Geography
schnuerle Jan 23, 2023
2c0a3fd
Make Policy public
schnuerle Jan 23, 2023
3d1c0e4
Clarifying authentication for 3 APIs
schnuerle Jan 23, 2023
dca52d2
Updated to Jurisdiction to public
schnuerle Jan 23, 2023
1a9c659
Spelling fixes
schnuerle Jan 23, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
4 changes: 2 additions & 2 deletions agency/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
|---------------------|-------------------|---------------------------------------------|
Expand All @@ -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

Expand Down
20 changes: 10 additions & 10 deletions general-information.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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]

Expand Down
17 changes: 4 additions & 13 deletions geography/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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.
Expand All @@ -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.

Expand All @@ -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]

Expand All @@ -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`. |
Expand Down Expand Up @@ -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 |
Expand Down
4 changes: 2 additions & 2 deletions jurisdiction/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand Down
41 changes: 7 additions & 34 deletions policy/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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)
Expand Down Expand Up @@ -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

Expand All @@ -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]

Expand All @@ -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.

Expand Down Expand Up @@ -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
Expand Down