diff --git a/README.md b/README.md index 99d3e230..6ba2fa6b 100644 --- a/README.md +++ b/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 diff --git a/agencies.csv b/agencies.csv new file mode 100644 index 00000000..efcd112d --- /dev/null +++ b/agencies.csv @@ -0,0 +1,21 @@ +agency_country_iso_code,agency_state,agency_city,agency_name,agency_id,department_url,requirement_url +CA,British Columbia,Kelowna,City of Kelowna,31e836fc-72da-4b2e-b553-8227d77a9b7a,https://www.kelowna.ca/roads-transportation/active-transportation/cycling/bikeshare-permit-program, +CO,Cundinamarca,Bogotá,Bogotá,85eac875-ab70-469f-8a85-cc5ef22e78d0,https://www.movilidadbogota.gov.co/web/, +DE,Baden-Württemberg,Ulm,Stadt Ulm,68f28fb8-d177-43f4-b7e8-a286fe0ddca0,https://www.ulm.de/de-de, +US,CA,Long Beach,City of Long Beach,188ed65d-a81e-40b9-b0b2-aeb85436610a,https://www.longbeach.gov/goactivelb/, +US,CA,Los Angeles,Los Angeles,d82d8584-dfa6-4396-93f0-5a36288b9eb1,https://ladot.lacity.org/projects/transportation-services/shared-mobility/micromobility, +US,CA,San Francisco,San Francisco,8e03693b-0153-446c-8bc0-c31f8a5a7ed8,https://www.sfmta.com/projects/powered-scooter-share-permit-and-pilot-program, +US,CA,San Jose,San Jose,801cb4b8-8725-449c-bdb9-7e9ac0e10b5b,https://www.sanjoseca.gov/your-government/departments-offices/transportation/micro-mobility, +US,CA,Santa Monica,Santa Monica,e4e7c0f6-c6aa-4919-a4de-565e4fe9fa57,https://www.smgov.net/Departments/PCD/Transportation/Shared-Mobility-Services/, +US,CO,Denver,Denver,c3d07b63-f602-4837-9525-7285f5ef286b,https://www.denvergov.org/content/denvergov/en/transportation-infrastructure/programs-services/dockless-mobility.html, +US,DC,Washington,District of Columbia,8aca1cf2-ffa5-46d8-b747-20cf00a7c7f1,https://ddot.dc.gov/page/dockless-vehicle-permits-district, +US,FL,Miami,City of Miami,5b36be11-7d5d-45ab-9c89-105cf6aa8645,https://www.miamigov.com/Services/Transportation/Miami-Scooter-Pilot-Program, +US,IL,Chicago,Chicago,d2ed9de6-2d2d-477c-a843-7d150d2310ed,https://www.chicago.gov/city/en/depts/cdot/supp_info/escooter-share-pilot-project.html, +US,KY,Louisville,Louisville Metro,44bc31a7-464b-4ed9-b52e-8e74630826bd,https://louisvilleky.gov/government/public-works/dockless-find-and-ride-vehicles, +US,MI,Detroit,Detroit,5814742e-78ba-4ac1-a628-c414ecc45448,https://detroitmi.gov/departments/department-public-works/complete-streets/scooters, +US,MN,Minneapolis,Minneapolis,88303227-48d6-4088-a690-65b4dcf381f7,http://www.minneapolismn.gov/publicworks/trans/WCMSP-212816, +US,OR,Portland,Portland,7d600eb6-f967-40ea-a212-33917f9b48ae,https://www.portlandoregon.gov/transportation/, +US,PA,Philadelphia,Philadelphia,fa2d0c5a-a716-473c-808b-be3b23e022ee,http://www.phillyotis.com/portfolio-item/dockless-bike-share-pilot/, +US,PA,Pittsburgh,Pittsburgh,f3c50422-7e3e-4efe-88c7-99da3b36c24d,https://pittsburghpa.gov/domi/bikeplan, +US,TX,Austin,City of Austin,296220ae-c90a-4383-9a97-0bc6cf1adf18,https://austintexas.gov/department/shared-mobility-services, +US,WA,Seattle,City of Seattle,9acf6e41-f145-49ad-be7f-d910e978fc36,https://www.seattle.gov/transportation/projects-and-programs/programs/bike-program/bike-share, diff --git a/general-information.md b/general-information.md index 9e17c241..bc121e60 100644 --- a/general-information.md +++ b/general-information.md @@ -147,7 +147,9 @@ For the purposes of this specification, the intersection of two geographic datat **[Beta feature](/general-information.md#beta-features):** *Yes (as of 1.1.0)* -Geography-Driven Events is a new MDS feature for Agencies to perform complete Policy compliance monitoring without precise location data. Geography-Driven Events describe individual vehicles in realtime – not just aggregate data. However, rather than receiving the exact location of a vehicle, Agencies receive information about the vehicle's current geographic region. The regions used for Geography-Driven Events correspond to the Geographies in an Agency's current Policy. In this way, the data-shared using Geography-Driven Events is matched to an Agency's particular regulatory needs. +Geography-Driven Events (GDE) is a new MDS feature for Agencies to perform complete Policy compliance monitoring without precise location data. Geography-Driven Events describe individual vehicles in realtime – not just aggregate data. However, rather than receiving the exact location of a vehicle, Agencies receive information about the vehicle's current geographic region. The regions used for Geography-Driven Events correspond to the Geographies in an Agency's current Policy. In this way, the data-shared using Geography-Driven Events is matched to an Agency's particular regulatory needs. + +See [this example](/policy/examples/requirements.md#geography-driven-events) for how to implement GDE using [Policy Requirements](/policy#requirement). Here's how it works in practice: @@ -163,9 +165,9 @@ Here's how it works in practice: *Agency adds rule disallowing parking on waterfront path, begins receiving data on events within area.* -Agencies that wish to use Geography-Driven Events do so by requiring a new `event_geographies` field in status events. When an Agency is using Geography-Driven Events, Providers must emit a new `changed_geographies` status event whenever a vehicle in a trip enters or leaves a Geography managed by a Policy. +Agencies that wish to use Geography-Driven Events do so by requiring a new `event_geographies` field in status events. When an Agency is using Geography-Driven Events, Providers must emit a new `changed_geographies` status event whenever a vehicle in a trip enters or leaves a Geography managed by a Policy. -During the Beta period for this feature, location and telemtry data remain required fields. This allows Aggencies to test Geography-Driven Events, measuring its accuracy and efficacy against regulatory systems based on precise location data. After the beta period, if Geography-Driven Events is deemed by OMF to be accurate and effective, the specification will evolve to allow cities to use Geography-Driven Events in lieu of location or telemtry data. +During the Beta period for this feature, location and telemetry data remain required fields. This allows Agencies to test Geography-Driven Events, measuring its accuracy and efficacy against regulatory systems based on precise location data. After the beta period, if Geography-Driven Events is deemed by the OMF to be accurate and effective, the specification will evolve to allow cities to use Geography-Driven Events in lieu of location or telemetry data. [Top][toc] @@ -313,7 +315,7 @@ In a multi-jurisdiction environment, the status of a vehicle is per-jurisdiction ### Event Types -Event types are the possible transitions bewteen some vehicle states. +Event types are the possible transitions between some vehicle states. | `event_type` | Description | |---|---| diff --git a/policy/README.md b/policy/README.md index 7de2bae6..b1576e2a 100644 --- a/policy/README.md +++ b/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,16 @@ 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) + - [Update Frequency](#requirement-update-frequency) + - [Public Hosting](#public-hosting) + - [Beta Limitations](#beta-limitations) + - [Format](#requirement-format) + - [Metadata](#requirement-metadata) + - [Programs](#requirement-programs) + - [Data Specs](#requirement-data-specs) + - [APIs](#requirement-apis) + ## General information The following information applies to all `policy` API endpoints. @@ -82,7 +94,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 +105,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 +115,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,15 +135,15 @@ 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 | | ------------ | --------- | --- | ---------------------------------------------- | @@ -139,8 +151,18 @@ Method: `GET` [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)*. [Leave feedback](https://github.com/openmobilityfoundation/mobility-data-specification/issues/682) + +See [Policy Requirements 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 +175,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 +197,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 +318,8 @@ 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. + | Name | Type | Required / Optional | Description | | ---------------- | --------- | --- | ----------------------------------------------------------------------------------- | | `name` | String | Required | Name of geography | @@ -365,6 +389,280 @@ 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 + +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. + +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. + +See [Policy Requirements Examples](/policy/examples/requirements.md) for ideas on how this can be implemented. + +#### Public Hosting + +This endpoint is not authenticated (ie. public), and allows the discovery of other public endpoints within Geography, Policy, and Jurisdiction. The agency can host this as a file or dynamic endpoint on their servers, on a third party server, or the OMF can host on behalf of an agency in the [agency program requirements repo](https://github.com/openmobilityfoundation/agency-program-requirements). 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, and [updated digitally as needed](#requirement-update-frequency). + +#### Requirement Update Frequency + +The OMF recommends updating the Requirements feed no more than monthly, and you may specify your expected timeframe with the `max_update_interval` in the [metadata](#requirement-metadata) section so providers have some idea of how often to check the feed. More specifically the OMF recommends giving the following notice to providers: 1 month for optional field additions, 3 months for endpoint/API changes/additions, 3 months for new minor releases, and 4 months for major releases. You should also communicate these future changes ahead of time with the `start_date` field. Finally, the OMF recommends any changes need to be part of a discussion between agencies and affected providers. + +#### 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)). + +```jsonc +{ + "metadata": { + // metadata fields per the "Requirement Metadata" section + }, + "programs" [ + { + "description" : "[PROGRAM DESCRIPTION]", + "provider_ids": [ + // provider id array + ], + "vehicle_types": [ + // optional vehicle_type array + ], + "start_date": [timestamp], + "end_date": [timestamp], + "required_data_specs": [ + { + "data_spec_name": "[NAME OF DATA SPEC]", + "version": "[VERSION NUMBER]", + "required_apis": [ + { + "api_name" : "[API NAME]": { + // Data spec endpoints, urls, optional fields + } + ] + } + }, + // other data specs per the "Requirement Data Specs" 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. | +| `programs` | Array | Required | Array of [Requirement Programs](#requirement-programs) data. | +| `required_data_specs` | Array | Required | Array of [Requirement Data Specs](#requirement-data-specs) data. | +| `required_apis` | Array | Required | Array of [Requirement APIs](#requirement-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. + +```jsonc +{ + "metadata": { + "mds_release": "[TEXT]", + "file_version": "[INTEGER]", + "last_updated": "[TIMESTAMP]", + "max_update_interval": "[DURATION]", + "agency_id": "[UUID]", + "agency_name": "[TEXT]", + "agency_timezone": "[TIMEZONE]", + "agency_language": "[TEXT]", + "agency_currency": "[TEXT]", + "agency_website_url": "[URL]" + "url": "[URL]" + }, + "mds_versions" [ + // Requirement MDS Versions + ] +} +``` + +| 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" | +| `file_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. "P1M" | +| `agency_id` | 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_website_url` | URL | Required | URL of the agency's general transportation page. E.g. "https://www.cityname.gov/transportation/" | +| `url` | URL | Required | URL of this file. E.g. "https://mds.cityname.gov/requirements/1.2.0" | + +[Top][toc] + +#### Requirement Programs + +Contains information about an agency's programs, with links to policy documents, and a list of providers and data specs/APIs/endpoints/fields that the program applies to over a certain time frame in its [Requirement](#requirement) data feed in the `required_data_specs` section. + +Unique combinations for data specs, specific providers, vehicle types, policies, and dates (past, current, or future) can be defined. For example an agency can define MDS version 1.2.0 and GBFS 2.2 for Provider #1 in a pilot with beta endpoints and optional fields, MDS version 1.2.0 for other providers without beta features starting a month from now, and MDS version 1.1.0 for Provider #2 with docked bikeshare. + +```jsonc +// ... + "programs": [ + { + "description" : "[PROGRAM DESCRIPTION]", + "program_website_url": "[URL]", + "program_document_url": "[URL]", + "provider_ids": [ + "[PROVIDER UUID]", + // ... + ], + "vehicle_types": [ + "[vehicle_type]", + // ... + ], + "start_date": [timestamp], + "end_date": [timestamp], + "required_data_specs" [ + { + // Required Data Specs array + }, + // other data specs + ] + } + ] +// ... +``` + +| Name | Type | Required / Optional | Description | +| ---------------------------- | --------------- | -------- | ----------------------------------- | +| `description` | text | Required | Simple agency program description of this combination of MDS, providers, vehicles, and time frame. | +| `program_website_url` | URL | Required | URL of the agency's transportation policy page. E.g. "https://www.cityname.gov/transportation/shared-devices.htm" | +| `program_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" | +| `provider_ids` | UUID[] | Required | Array of provider UUIDs that apply to this group the requirements | +| `vehicle_type` | Enum | Optional | Array of [Vehicle Types](../general-information.md#vehicle-types) that apply to this requirement. If absent it applies to all vehicle types. | +| `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_data_specs` | Array | Required | Array of required [Data Specs](#requirement-data-specs) | + +[Top][toc] + +#### Requirement Data Specs + +For each combination of items in a program, you can specify the data specs, APIs, endpoints, and optional fields that are required per your agency's program policies. This is an array within the [Requirement MDS Versions](#requirement-mds-versions) `mds_apis` section in the [Requirement](#requirement) data feed. + +```jsonc +// ... + "required_data_specs": [ + { + "data_spec_name": "[DATA SPEC NAME]", + "version": "[VERSION NUMBER]", + "required_apis": [ + { + // Required APIs array + } + ], + "available_apis": [ + { + // Available APIs array + } + ] + }, + // other data specs + ] +// ... +``` + +| 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). | +| `version` | Text | Required | Version number of the data spec required. E.g. '1.2.0' | +| `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. | +| `available_apis` | Array | Conditionally Required | Name of the [Requirement APIs](#requirement-apis) that are being served by agencies. Not applicable to GBFS. APIs not listed will not be available to the provider. | + +[Top][toc] + +#### 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. + +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. + +**Note: any APIs, endpoints, or fields that are _required_ by a data specification are not to be listed, and are still required. Only optional items are enumerated here. You may however list `disallowed_fields` to exclude required fields. Optional APIs or endpoints should _NOT_ be returned unless specified.** + +You may also show which APIs, endpoints, and fields your agency is serving to providers and the public. This is an `available_apis` array within the [Requirement Data Specs](#requirement-data-specs) section in the [Requirement](#requirement) data feed. + +```jsonc +// ... + "required_apis": [ + { + "api_name" : "[API NAME]", + "required_endpoints": [ + { + "endpoint_name" : "[ENDPOINT NAME]", + "required_fields": [ + "[FIELD NAME]", + // other field names + ], + "disallowed_fields": [ + "[FIELD NAME]", + // other field names + ] + }, + // other endpoints + ] + }, + // other APIs in same data spec + ], + "available_apis": [ + { + "api_name" : "[API NAME]", + "available_endpoints": [ + { + "endpoint_name" : "[ENDPOINT NAME]", + "url": "[ENDPOINT URL]", + "available_fields": [ + "[FIELD NAME]", + // other field names + ] + }, + // other endpoints + ] + } + ] +// ... +``` + +| Name | Type | Required/Optional | Description | +| -------------------- | ----- | -------- | ----------------------------------- | +| `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' | + +**Provider Endpoints** - Specific to the `required_apis` array + +| Name | Type | Required/Optional | Description | +| -------------------- | ----- | -------- | ----------------------------------- | +| `required_endpoints` | Array | Required | Array of optional endpoints required by the agency. At least one is required. Endpoints not listed will not be available to the agency. | +| `required_fields` | Array | Optional | Array of optional field names required by the agency. Can be omitted if no optional fields are required. Use dot notation for nested fields. See **special notes** below. | +| `disallowed_fields` | Array | Optional | Array of optional field names which must not be returned by in the endpoint, even if required in MDS. Use dot notation for nested fields. See **special notes** below. | + +**Agency Endpoints** - Specific to the `available_apis` array + +| Name | Type | Required/Optional | Description | +| -------------------- | ----- | -------- | ----------------------------------- | +| `available_endpoints`| Array | Required | Array of endpoints provided by the agency. At least one is required. Endpoints not listed will not be available to the provider. | +| `url` | URL | Optional | Location of API endpoint url. 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" | +| `available_fields` | Array | Optional | Array of optional field names provided by the agency. Can be omitted if none are required. Use dot notation for nested fields. See **special notes** below. | + +**Special notes about `required_fields` and `disallowed_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, 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. [Top][toc] diff --git a/policy/examples/README.md b/policy/examples/README.md index 9fb59f93..ff3b1890 100644 --- a/policy/examples/README.md +++ b/policy/examples/README.md @@ -1,6 +1,6 @@ # Policy Examples -This file presents a series of example [Policy documents](../README.md#schema) for Agencies to use as templates. +This file presents a series of example [Policy documents](../README.md#policy) for Agencies to use as templates. ## Table of Contents diff --git a/policy/examples/requirements.md b/policy/examples/requirements.md new file mode 100644 index 00000000..41b17cd3 --- /dev/null +++ b/policy/examples/requirements.md @@ -0,0 +1,717 @@ +# Policy Requirement Examples + +This file presents a series of example [Requirements](../README.md#requirement) documents for Agencies to use as templates. + +## Table of Contents + +- [Policy and Geography](#policy-and-geography) +- [Vehicles Only](#vehicles-only) +- [Trips Only](#trips-only) +- [Trips with No Routes, Vehicles IDs, or Dates](#trips-with-no-routes-vehicle-ids-or-dates) +- [Provider and Other APIs](#provider-and-other-apis) +- [Agency](#agency) +- [Geography Driven Events](#geography-driven-events) +- [GBFS Only](#gbfs-only) + +## Policy and Geography + +Version 1.2.0 of MDS Policy and Geography for agencies to publish rules/fees/incentives and operating/equity/no-ride/slow speed/parking areas to all providers, and require GBFS's geofencing_zones. + +```json +{ + "metadata": { + "mds_release": "1.2.0", + "file_version": "4", + "last_updated": "1611729218", + "max_update_interval": "P1M", + "agency_id": "737a9c62-c0cb-4c93-be43-271d21b784b5", + "agency_name": "Louisville Metro", + "agency_timezone": "America/New_York", + "agency_language": "en-US", + "agency_currency": "USD", + "agency_website_url": "https://www.cityname.gov/transportation/", + "url": "https://mds.cityname.gov/policy/requirements/1.2.0" + }, + "programs": [ + { + "description": "City Micromobility Program Policy Rules", + "program_website_url": "https://www.cityname.gov/transportation/shared-devices.html", + "program_document_url": "https://www.cityname.gov/mds_data_policy.pdf", + "provider_ids": [ + "70aa475d-1fcd-4504-b69c-2eeb2107f7be", + "2411d395-04f2-47c9-ab66-d09e9e3c3251", + "04ab5c86-ab6f-4abc-b866-e4c92da39a3e", + "bd530feb-936f-40eb-ae04-ce931de216e1", + "a8c54e3e-fe67-4c5a-90a6-4a1d2c2808da" + ], + "start_date": 1611958740, + "end_date": null, + "required_data_specs": [ + { + "data_spec_name": "MDS", + "version": "1.2.0", + "available_apis": [ + { + "api_name": "policy", + "available_endpoints": [ + { + "endpoint_name": "policies", + "url": "https://mds.cityname.com/policy/policies/1.2.0" + } + ] + }, + { + "api_name": "geography", + "available_endpoints": [ + { + "endpoint_name": "geographies", + "url": "https://mds.cityname.com/geography/geographies/1.2.0", + "available_fields": [ + "geography_type", + "description" + ] + } + ] + } + ] + }, + { + "data_spec_name": "GBFS", + "version": "2.2", + "required_apis": [ + { + "required_endpoints": [ + { + "endpoint_name": "geofencing_zones.json", + "required_fields": [ + "features.properties.rules.vehicle_type_id" + ] + } + ] + } + ] + } + ] + } + ] +} +``` + +[Top](#table-of-contents) + +## Vehicles Only + +Version 1.1.0 for one provider with scooters, and 1.0.0 for another provider for bicycles, 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, while still requiring GBFS 2.1 for the public. + +```json +{ + "metadata": { + "mds_release": "1.2.0", + "file_version": "2", + "last_updated": "1611958740", + "max_update_interval": "P1M", + "agency_id": "737a9c62-c0cb-4c93-be43-271d21b784b5", + "agency_name": "Louisville Metro", + "agency_timezone": "America/New_York", + "agency_language": "en-US", + "agency_currency": "USD", + "agency_website_url": "https://www.cityname.gov/transportation/", + "url": "https://mds.cityname.gov/policy/requirements/1.2.0" + }, + "programs": [ + { + "description": "City Scooter Monitoring Program 2021", + "program_website_url": "https://www.cityname.gov/transportation/shared-devices.html", + "program_document_url": "https://www.cityname.gov/mds_data_policy.pdf", + "provider_ids": [ + "70aa475d-1fcd-4504-b69c-2eeb2107f7be" + ], + "vehicle_types": [ + "scooter" + ], + "start_date": 1611958740, + "end_date": null, + "required_data_specs": [ + { + "data_spec_name": "MDS", + "version": "1.1.0", + "required_apis": [ + { + "api_name": "provider", + "required_endpoints": [ + { + "endpoint_name": "vehicles" + } + ] + } + ] + }, + { + "data_spec_name": "GBFS", + "version": "2.1" + } + ] + }, + { + "description": "City Bikeshare Monitoring Program 2021", + "program_website_url": "https://www.cityname.gov/transportation/bikeshare.html", + "program_document_url": "https://www.cityname.gov/mds_data_policy.pdf", + "provider_ids": [ + "2411d395-04f2-47c9-ab66-d09e9e3c3251" + ], + "vehicle_types": [ + "bicycle" + ], + "start_date": 1611958740, + "end_date": null, + "required_data_specs": [ + { + "data_spec_name": "MDS", + "version": "1.0.0", + "required_apis": [ + { + "api_name": "provider", + "required_endpoints": [ + { + "endpoint_name": "vehicles" + } + ] + } + ] + }, + { + "data_spec_name": "GBFS", + "version": "2.1" + } + ] + } + ] +} +``` + +[Top](#table-of-contents) + +## Trips Only + +Version 1.1.0 for 2 providers requiring only historic Provider `/trips` with the optional `parking_verificaiton_url` field, linked to a specific MDS Policy. + +```json +{ + "metadata": { + "mds_release": "1.2.0", + "file_version": "3", + "last_updated": "1611958740", + "max_update_interval": "P1M", + "agency_id": "737a9c62-c0cb-4c93-be43-271d21b784b5", + "agency_name": "Louisville Metro", + "agency_timezone": "America/New_York", + "agency_language": "en-US", + "agency_currency": "USD", + "agency_website_url": "https://www.cityname.gov/transportation/", + "url": "https://mds.cityname.gov/policy/requirements/1.2.0" + }, + "programs": [ + { + "description": "City Vehicle Program Pilot 2021", + "program_website_url": "https://www.cityname.gov/transportation/shared-devices.html", + "program_document_url": "https://www.cityname.gov/mds_data_policy.pdf", + "provider_ids": [ + "70aa475d-1fcd-4504-b69c-2eeb2107f7be", + "2411d395-04f2-47c9-ab66-d09e9e3c3251" + ], + "start_date": 1611958740, + "end_date": 1611970539, + "required_data_specs": [ + { + "data_spec_name": "MDS", + "version": "1.1.0", + "required_apis": [ + { + "api_name": "provider", + "required_endpoints": [ + { + "endpoint_name": "trips", + "required_fields": [ + "parking_verification_url" + ] + } + ] + } + ] + }, + { + "data_spec_name": "GBFS", + "version": "2.2" + } + ] + } + ] +} +``` + +[Top](#table-of-contents) + +## Trips with No Routes, Vehicle IDs, or Dates + +Version 1.1.0 for 2 providers asking for only historic [Provider `/trips`](/provider#trips) with the typically required `device_id`, `vehicle_id`, `start_time`, `end_time`, and `route` array data, and the optional `parking_verification_url` photo URL, not returned in the endpoint. + +```json +{ + "metadata": { + "mds_release": "1.2.0", + "file_version": "3", + "last_updated": "1611958740", + "max_update_interval": "P1M", + "agency_id": "737a9c62-c0cb-4c93-be43-271d21b784b5", + "agency_name": "Louisville Metro", + "agency_timezone": "America/New_York", + "agency_language": "en-US", + "agency_currency": "USD", + "agency_website_url": "https://www.cityname.gov/transportation/", + "url": "https://mds.cityname.gov/policy/requirements/1.2.0" + }, + "programs": [ + { + "description": "City Vehicle Program Pilot Research for 2021", + "program_website_url": "https://www.cityname.gov/transportation/shared-devices.html", + "program_document_url": "https://www.cityname.gov/mds_data_policy.pdf", + "provider_ids": [ + "70aa475d-1fcd-4504-b69c-2eeb2107f7be", + "2411d395-04f2-47c9-ab66-d09e9e3c3251" + ], + "start_date": 1611958740, + "end_date": 1611970539, + "required_data_specs": [ + { + "data_spec_name": "MDS", + "version": "1.1.0", + "required_apis": [ + { + "api_name": "provider", + "required_endpoints": [ + { + "endpoint_name": "trips", + "disallowed_fields": [ + "route", + "device_id", + "vehicle_id", + "start_time", + "end_time", + "parking_verification_url" + ] + } + ] + } + ] + }, + { + "data_spec_name": "GBFS", + "version": "2.2" + } + ] + } + ] +} +``` + +[Top](#table-of-contents) + +## Provider and Other APIs + +Version 1.1.0 or 0.4.1 for 3 providers with many APIs and endpoints. + +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. + +```json +{ + "metadata": { + "mds_release": "1.2.0", + "file_version": "3", + "last_updated": "1611958740", + "max_update_interval": "P1M", + "agency_id": "737a9c62-c0cb-4c93-be43-271d21b784b5", + "agency_name": "Louisville Metro", + "agency_timezone": "America/New_York", + "agency_language": "en-US", + "agency_currency": "USD", + "agency_website_url": "https://www.cityname.gov/transportation/", + "url": "https://mds.cityname.gov/policy/requirements/1.2.0" + }, + "programs": [ + { + "description": "City Shared Device Program and Policies 2021", + "program_website_url": "https://www.cityname.gov/transportation/shared-devices.html", + "program_document_url": "https://www.cityname.gov/mds_data_policy.pdf", + "provider_ids": [ + "70aa475d-1fcd-4504-b69c-2eeb2107f7be", + "2411d395-04f2-47c9-ab66-d09e9e3c3251", + "420e6e94-55a6-4946-b6b3-4398fe22e912" + ], + "start_date": 1611958740, + "end_date": 1611970539, + "required_data_specs": [ + { + "data_spec_name": "MDS", + "version": "1.1.0", + "required_apis": [ + { + "api_name": "provider", + "required_endpoints": [ + { + "endpoint_name": "trips", + "required_fields": [ + "parking_verification_url", + "standard_cost", + "actual_cost" + ] + }, + { + "endpoint_name": "status_changes", + "required_fields": [ + "event_geographies", + "trip_id" + ] + }, + { + "endpoint_name": "reports" + }, + { + "endpoint_name": "events", + "required_fields": [ + "trip_id", + "associated_ticket" + ] + }, + { + "endpoint_name": "stops", + "required_fields": [ + "geography_id", + "address", + "devices", + "image_url" + ] + }, + { + "endpoint_name": "vehicles", + "required_fields": [ + "current_location" + ] + } + ] + } + ], + "available_apis": [ + { + "api_name": "policy", + "available_endpoints": [ + { + "endpoint_name": "policies", + "url": "https://mds.cityname.gov/policy/policies/1.1.0" + } + ] + }, + { + "api_name": "geography", + "available_endpoints": [ + { + "endpoint_name": "geographies", + "url": "https://mds.cityname.gov/geography/geographies/1.1.0" + } + ] + }, + { + "api_name": "jurisdiction", + "available_endpoints": [ + { + "endpoint_name": "trips", + "url": "https://mds.cityname.gov/jurisdiction/jurisdictions/1.1.0" + } + ] + }, + { + "api_name": "metrics" + } + ] + }, + { + "data_spec_name": "GBFS", + "version": "2.2" + } + ] + }, + { + "description": "City Docked Device Program 2021", + "program_website_url": "https://www.cityname.gov/transportation/shared-devices.html", + "program_document_url": "https://www.cityname.gov/mds_data_policy.pdf", + "version": "0.4.1", + "provider_ids": [ + "70aa475d-1fcd-4504-b69c-2eeb2107f7be", + "2411d395-04f2-47c9-ab66-d09e9e3c3251", + "420e6e94-55a6-4946-b6b3-4398fe22e912" + ], + "start_date": 1611958740, + "end_date": 1611970539, + "required_data_specs": [ + { + "data_spec_name": "MDS", + "version": "0.4.1", + "required_apis": [ + { + "api_name": "provider", + "required_endpoints": [ + { + "endpoint_name": "trips", + "required_fields": [ + "parking_verification_url", + "standard_cost", + "actual_cost" + ] + }, + { + "endpoint_name": "status_changes" + }, + { + "endpoint_name": "events" + }, + { + "endpoint_name": "stops", + "required_fields": [ + "geography_id", + "address", + "devices", + "image_url" + ] + }, + { + "endpoint_name": "vehicles" + } + ] + } + ] + }, + { + "data_spec_name": "GBFS", + "version": "2.1" + } + ] + } + ] +} +``` + +[Top](#table-of-contents) + +## Agency + +Version 1.1.0 for 3 providers and serving Agency only linking to a defined MDS Policy. + +```json +{ + "metadata": { + "mds_release": "1.2.0", + "file_version": "2", + "last_updated": "1611958740", + "max_update_interval": "P1M", + "agency_id": "737a9c62-c0cb-4c93-be43-271d21b784b5", + "agency_name": "Louisville Metro", + "agency_timezone": "America/New_York", + "agency_language": "en-US", + "agency_currency": "USD", + "agency_website_url": "https://www.cityname.gov/transportation/", + "url": "https://mds.cityname.gov/policy/requirements/1.2.0" + }, + "programs": [ + { + "description": "City Shared Device Management Program 2021-2022", + "program_website_url": "https://www.cityname.gov/transportation/shared-devices.html", + "program_document_url": "https://www.cityname.gov/mds_data_policy.pdf", + "provider_ids": [ + "70aa475d-1fcd-4504-b69c-2eeb2107f7be", + "2411d395-04f2-47c9-ab66-d09e9e3c3251", + "420e6e94-55a6-4946-b6b3-4398fe22e912" + ], + "start_date": 1611958740, + "end_date": 1611970539, + "required_data_specs": [ + { + "data_spec_name": "MDS", + "version": "1.1.0", + "required_apis": [ + { + "api_name": "agency", + "required_endpoints": [ + { + "endpoint_name": "vehicles" + }, + { + "endpoint_name": "vehicle_register", + "required_fields": [ + "year", + "mfg", + "model" + ] + }, + { + "endpoint_name": "vehicle_update" + }, + { + "endpoint_name": "vehicle_event", + "required_fields": [ + "event_geographies", + "trip_id" + ] + }, + { + "endpoint_name": "vehicle_telemetry" + }, + { + "endpoint_name": "stops", + "required_fields": [ + "status", + "num_spots_disabled" + ] + } + ] + } + ] + }, + { + "data_spec_name": "GBFS", + "version": "2.2" + } + ] + } + ] +} +``` + +[Top](#table-of-contents) + +## Geography Driven Events + +Version 1.1.0 for 2 providers requiring Provider `/status_changes` with the minimum required for beta feature [Geography Driven Events](/general-information.md#geography-driven-events). + +```json +{ + "metadata": { + "mds_release": "1.2.0", + "file_version": "1", + "last_updated": "1611958740", + "max_update_interval": "P1M", + "agency_id": "737a9c62-c0cb-4c93-be43-271d21b784b5", + "agency_name": "Portland Metro", + "agency_timezone": "America/Los_Angeles", + "agency_language": "en-US", + "agency_currency": "USD", + "agency_website_url": "https://www.cityname.gov/transportation/", + "url": "https://mds.cityname.gov/policy/requirements/1.2.0" + }, + "programs": [ + { + "description": "City Shared Vehicle Program", + "program_website_url": "https://www.cityname.gov/transportation/shared-devices.html", + "program_document_url": "https://www.cityname.gov/mds_data_policy.pdf", + "provider_ids": [ + "70aa475d-1fcd-4504-b69c-2eeb2107f7be", + "2411d395-04f2-47c9-ab66-d09e9e3c3251" + ], + "start_date": 1611958740, + "end_date": 1611970539, + "required_data_specs": [ + { + "data_spec_name": "MDS", + "version": "1.1.0", + "required_apis": [ + { + "api_name": "provider", + "required_endpoints": [ + { + "endpoint_name": "status_changes", + "required_fields": [ + "event_geographies" + ] + } + ] + } + ] + }, + { + "data_spec_name": "GBFS", + "version": "2.1" + } + ] + } + ] +} +``` + +[Top](#table-of-contents) + +## GBFS Only + +Since Requirements allows the GBFS versions and optional endpoints and fields to be defined, an agency could use it to only require public GBFS feeds, and not require MDS at all. + +```json +{ + "metadata": { + "mds_release": "1.2.0", + "file_version": "2", + "last_updated": "1611958740", + "max_update_interval": "P1M", + "agency_id": "737a9c62-c0cb-4c93-be43-271d21b784b5", + "agency_name": "Louisville Metro", + "agency_timezone": "America/New_York", + "agency_language": "en-US", + "agency_currency": "USD", + "agency_website_url": "https://www.cityname.gov/transportation/", + "url": "https://mds.cityname.gov/policy/requirements/1.2.0" + }, + "programs": [ + { + "description": "City Scooter Public Data Feeds 2021", + "program_website_url": "https://www.cityname.gov/transportation/shared-devices.html", + "program_document_url": "https://www.cityname.gov/data_policy.pdf", + "provider_ids": [ + "70aa475d-1fcd-4504-b69c-2eeb2107f7be", + "2411d395-04f2-47c9-ab66-d09e9e3c3251" + ], + "start_date": 1611958740, + "end_date": null, + "required_data_specs": [ + { + "data_spec_name": "GBFS", + "version": "2.2", + "required_apis": [ + { + "required_endpoints": [ + { + "endpoint_name": "geofencing_zones.json", + "required_fields": [ + "features.properties.name", + "features.properties.start", + "features.properties.end", + "features.properties.rules.vehicle_type_id" + ] + }, + { + "endpoint_name": "system_calendar.json" + }, + { + "endpoint_name": "system_pricing_plans.json", + "required_fields": [ + "per_km_pricing", + "per_km_pricing", + "surge_pricing" + ] + } + ] + } + ] + } + ] + } + ] +} +``` + +[Top](#table-of-contents)