From a32266a8b6cff814584469b43d83ff3a26c421dc Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Wed, 29 Sep 2021 10:39:42 -0400 Subject: [PATCH 01/81] Release notes for 1.2.0 --- ReleaseNotes.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/ReleaseNotes.md b/ReleaseNotes.md index ad2f6bf5..495f7216 100644 --- a/ReleaseNotes.md +++ b/ReleaseNotes.md @@ -1,3 +1,49 @@ +## 1.2.0 + +> Release Candidate submitted 2021-09-29 + +> [Release Plan](https://github.com/openmobilityfoundation/governance/wiki/Release-1.2.0) + +The 1.2.0 minor release adds digital program Requirements, new options for policies, better GPS telemetry data, and moves Provider Vehicles out of beta. + +### CHANGES + +See the closed PRs tagged with [Milestone 1.2.0](https://github.com/openmobilityfoundation/mobility-data-specification/pulls?q=is%3Apr+is%3Aclosed+milestone%3A1.2.0) and [Issues](https://github.com/openmobilityfoundation/mobility-data-specification/issues?q=is%3Aissue+milestone%3A1.2.0+is%3Aclosed) for a full list of changes. + +**_General MDS_** + +- [Richer telemetry data](https://github.com/openmobilityfoundation/mobility-data-specification/issues/589), including [616](https://github.com/openmobilityfoundation/mobility-data-specification/issues/616), [73](https://github.com/openmobilityfoundation/mobility-data-specification/pull/73), [51](https://github.com/openmobilityfoundation/mobility-data-specification/pull/51) +- [Add cargo_bike vehicle type](https://github.com/openmobilityfoundation/mobility-data-specification/pull/698) + +**_Policy_** + +- [Program Requiements](https://github.com/openmobilityfoundation/mobility-data-specification/issues/646) - For agencies to describe program requirements digitally to allow providers and the public to see what MDS and GBFS versions, APIs, endpoints, and fields are required, and communicate available MDS agency information to providers. + - [Ability to express data sharing requirements in Policy](https://github.com/openmobilityfoundation/mobility-data-specification/issues/608) + - [Method to Exclude some Provider Fields from Response](https://github.com/openmobilityfoundation/mobility-data-specification/issues/507) + - [Retrieve operational zones from operators](https://github.com/openmobilityfoundation/mobility-data-specification/issues/639) + - [Make Trip 'route' field optional for privacy](https://github.com/openmobilityfoundation/mobility-data-specification/issues/504) + +- [Multiple options added to Policy](https://github.com/openmobilityfoundation/mobility-data-specification/pull/658) + - [Add rate options to other rules types](https://github.com/openmobilityfoundation/mobility-data-specification/issues/633) + - [Support parking fees by duration](https://github.com/openmobilityfoundation/mobility-data-specification/issues/631) + - [Min and max clarity on Rules](https://github.com/openmobilityfoundation/mobility-data-specification/issues/689) + - [Add a "rate applies when" field to Rules](https://github.com/openmobilityfoundation/mobility-data-specification/issues/666) + +**_Provider_** + +- [Vehicles out of beta](https://github.com/openmobilityfoundation/mobility-data-specification/issues/637) +- [Clarify use cases between MDS Vehicles and GBFS](https://github.com/openmobilityfoundation/mobility-data-specification/issues/641) + +**_Agency_** + +- N/A + +_Minor Updates_ + +- [Clarify single object response on policy/geography](https://github.com/openmobilityfoundation/mobility-data-specification/issues/599) +- [Schema updates](https://github.com/openmobilityfoundation/mobility-data-specification/issues/693), including [645](https://github.com/openmobilityfoundation/mobility-data-specification/issues/645), [687](https://github.com/openmobilityfoundation/mobility-data-specification/issues/687), [683](https://github.com/openmobilityfoundation/mobility-data-specification/issues/683) +- Add VeoRide, Boaz Bikes, and update Superpedestrian provider IDs + ## 1.1.1 > Released: 2021-09-24 From b33dbf2117762ed1ecc9ef990595c0db70b624f1 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Wed, 29 Sep 2021 10:42:25 -0400 Subject: [PATCH 02/81] Tweaks to release notes --- ReleaseNotes.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/ReleaseNotes.md b/ReleaseNotes.md index 495f7216..defcdad4 100644 --- a/ReleaseNotes.md +++ b/ReleaseNotes.md @@ -13,7 +13,7 @@ See the closed PRs tagged with [Milestone 1.2.0](https://github.com/openmobility **_General MDS_** - [Richer telemetry data](https://github.com/openmobilityfoundation/mobility-data-specification/issues/589), including [616](https://github.com/openmobilityfoundation/mobility-data-specification/issues/616), [73](https://github.com/openmobilityfoundation/mobility-data-specification/pull/73), [51](https://github.com/openmobilityfoundation/mobility-data-specification/pull/51) -- [Add cargo_bike vehicle type](https://github.com/openmobilityfoundation/mobility-data-specification/pull/698) +- [Add cargo_bicycle vehicle type](https://github.com/openmobilityfoundation/mobility-data-specification/pull/698) **_Policy_** @@ -34,10 +34,6 @@ See the closed PRs tagged with [Milestone 1.2.0](https://github.com/openmobility - [Vehicles out of beta](https://github.com/openmobilityfoundation/mobility-data-specification/issues/637) - [Clarify use cases between MDS Vehicles and GBFS](https://github.com/openmobilityfoundation/mobility-data-specification/issues/641) -**_Agency_** - -- N/A - _Minor Updates_ - [Clarify single object response on policy/geography](https://github.com/openmobilityfoundation/mobility-data-specification/issues/599) From abccb73b805d0455afbfe79be0dce4b789212604 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Wed, 29 Sep 2021 10:59:43 -0400 Subject: [PATCH 03/81] Notes typo in requirements --- ReleaseNotes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ReleaseNotes.md b/ReleaseNotes.md index defcdad4..f9e5d9c5 100644 --- a/ReleaseNotes.md +++ b/ReleaseNotes.md @@ -17,7 +17,7 @@ See the closed PRs tagged with [Milestone 1.2.0](https://github.com/openmobility **_Policy_** -- [Program Requiements](https://github.com/openmobilityfoundation/mobility-data-specification/issues/646) - For agencies to describe program requirements digitally to allow providers and the public to see what MDS and GBFS versions, APIs, endpoints, and fields are required, and communicate available MDS agency information to providers. +- [Program Requirements](https://github.com/openmobilityfoundation/mobility-data-specification/issues/646) - For agencies to describe program requirements digitally to allow providers and the public to see what MDS and GBFS versions, APIs, endpoints, and fields are required, and communicate available MDS agency information to providers. - [Ability to express data sharing requirements in Policy](https://github.com/openmobilityfoundation/mobility-data-specification/issues/608) - [Method to Exclude some Provider Fields from Response](https://github.com/openmobilityfoundation/mobility-data-specification/issues/507) - [Retrieve operational zones from operators](https://github.com/openmobilityfoundation/mobility-data-specification/issues/639) From 01ae6d24b8a5e4fb2848cdce37c170e2437bba20 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 4 Oct 2021 10:05:37 -0400 Subject: [PATCH 04/81] Added Version Tracking section to Reqs --- policy/README.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/policy/README.md b/policy/README.md index 9bd34fc6..857686d9 100644 --- a/policy/README.md +++ b/policy/README.md @@ -31,6 +31,7 @@ This specification describes the digital relationship between _mobility as a ser - [Requirement](#requirement) - [Update Frequency](#requirement-update-frequency) - [Public Hosting](#public-hosting) + - [Version Tracking](#version-tracking) - [Beta Limitations](#beta-limitations) - [Format](#requirement-format) - [Metadata](#requirement-metadata) @@ -430,6 +431,12 @@ This endpoint is not authenticated (ie. public), and allows the discovery of oth 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. +#### Version Tracking + +If you are upgrading to a new MDS version, it is recommended to create a new requirements file at a new URL, since field names and available options may have changed. To make this more obvious, the MDS version number could be part of your URL, e.g. "https://mds.cityname.gov/requirements/**1.2.0**". + +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 to keep retired requirements visible. 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. From 345e805d0193e3f37920c9c431db734c27744943 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 4 Oct 2021 10:08:09 -0400 Subject: [PATCH 05/81] Fixed bold/quote formatting --- policy/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/policy/README.md b/policy/README.md index 857686d9..ec28a4eb 100644 --- a/policy/README.md +++ b/policy/README.md @@ -433,9 +433,9 @@ The OMF recommends updating the Requirements feed no more than monthly, and you #### Version Tracking -If you are upgrading to a new MDS version, it is recommended to create a new requirements file at a new URL, since field names and available options may have changed. To make this more obvious, the MDS version number could be part of your URL, e.g. "https://mds.cityname.gov/requirements/**1.2.0**". +If you are upgrading to a new MDS version, it is recommended to create a new requirements file at a new URL, since field names and available options may have changed. To make this more obvious, the MDS version number could be part of your URL, e.g. "https://mds.cityname.gov/requirements/1.2.0". -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 to keep retired requirements visible. 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**". +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 From f11c2ce6e7e21bb464edfef4b9c728cdbb31335e Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 4 Oct 2021 10:11:49 -0400 Subject: [PATCH 06/81] Added note about version tracking to metadata --- policy/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/policy/README.md b/policy/README.md index ec28a4eb..6ec2d3a5 100644 --- a/policy/README.md +++ b/policy/README.md @@ -518,8 +518,8 @@ Contains metadata applicable to the agency and at the top of its [Requirement](# | 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" | +| `file_version` | integer | Required | Version of this file. Increment 1 with each modification. See [version tracking](#version-tracking] for details. E.g. "3" | +| `last_updated` | [timestamp][ts] | Required | When this file `version` was last updated. See [version tracking](#version-tracking] for details. 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" | From e6392fd7a05e2d75b2ee350441a9a6c20405ac1c Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 4 Oct 2021 10:12:27 -0400 Subject: [PATCH 07/81] Updated link to version-tracking --- policy/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/policy/README.md b/policy/README.md index 6ec2d3a5..dd114f94 100644 --- a/policy/README.md +++ b/policy/README.md @@ -518,8 +518,8 @@ Contains metadata applicable to the agency and at the top of its [Requirement](# | 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. See [version tracking](#version-tracking] for details. E.g. "3" | -| `last_updated` | [timestamp][ts] | Required | When this file `version` was last updated. See [version tracking](#version-tracking] for details. E.g. "1611958740" | +| `file_version` | integer | Required | Version of this file. Increment 1 with each modification. See [version tracking](#version-tracking) for details. E.g. "3" | +| `last_updated` | [timestamp][ts] | Required | When this file `version` was last updated. See [version tracking](#version-tracking) for details. 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" | From 9b483936a26359a0931a4e063beebca2d4aa8ed7 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 4 Oct 2021 11:52:41 -0400 Subject: [PATCH 08/81] Updated hosting guidance links And details about agency_id --- policy/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/policy/README.md b/policy/README.md index dd114f94..3bef1ff9 100644 --- a/policy/README.md +++ b/policy/README.md @@ -425,7 +425,7 @@ See [Policy Requirements Examples](/policy/examples/requirements.md) for ideas o #### 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). +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](https://github.com/openmobilityfoundation/mobility-data-specification/wiki/Policy-Requirements-OMF-Hosting-Guidance) 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). To be compliant with MDS you must obtain an `agency_id` and list your public URL in [agencies.csv](/agencies.csv), per our [guidance document](https://github.com/openmobilityfoundation/mobility-data-specification/wiki/Adding-an-MDS-Agency-ID). #### Requirement Update Frequency @@ -521,13 +521,13 @@ Contains metadata applicable to the agency and at the top of its [Requirement](# | `file_version` | integer | Required | Version of this file. Increment 1 with each modification. See [version tracking](#version-tracking) for details. E.g. "3" | | `last_updated` | [timestamp][ts] | Required | When this file `version` was last updated. See [version tracking](#version-tracking) for details. 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_id` | UUID | Required | UUID of the agency this file applies to. Must come from [agencies.csv](/agencies.csv) file, per [guidance](https://github.com/openmobilityfoundation/mobility-data-specification/wiki/Adding-an-MDS-Agency-ID). 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" | +| `url` | URL | Required | URL of this file. Must be added to [agencies.csv](/agencies.csv), per [guidance](https://github.com/openmobilityfoundation/mobility-data-specification/wiki/Adding-an-MDS-Agency-ID). E.g. "https://mds.cityname.gov/requirements/1.2.0" | [Top][toc] From 4b8bb81f82c8e2546d0461adc34763ed42ec9f7d Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Wed, 6 Oct 2021 10:52:53 -0400 Subject: [PATCH 09/81] New Req endpoint in image --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 6ba2fa6b..5fd88a2d 100644 --- a/README.md +++ b/README.md @@ -76,7 +76,7 @@ Many parts of the MDS definitions and APIs align across each other. In these cas You can read more in our **[Understanding the different MDS APIs](https://github.com/openmobilityfoundation/governance/blob/main/technical/Understanding-MDS-APIs.md)** guide. -![MDS APIs and Endpoints](https://i.imgur.com/L5s927a.png) +![MDS APIs and Endpoints](https://i.imgur.com/bfUtCif.png) ## GBFS Requirement From 728034500a328bd4ae4723830862fac07f0e2edb Mon Sep 17 00:00:00 2001 From: Kegan Maher Date: Sun, 17 Oct 2021 11:13:33 -0700 Subject: [PATCH 10/81] pluralize policies in required properties array --- policy/policy.json | 2 +- schema/templates/policy/policy.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/policy/policy.json b/policy/policy.json index 25d9994e..37ebbf05 100644 --- a/policy/policy.json +++ b/policy/policy.json @@ -613,7 +613,7 @@ "type": "object", "description": "The data records in this payload", "required": [ - "policy" + "policies" ], "properties": { "policy": { diff --git a/schema/templates/policy/policy.json b/schema/templates/policy/policy.json index fc17f04d..320cb43f 100644 --- a/schema/templates/policy/policy.json +++ b/schema/templates/policy/policy.json @@ -336,7 +336,7 @@ "type": "object", "description": "The data records in this payload", "required": [ - "policy" + "policies" ], "properties": { "policies": { From 1ea89d9257e7f174dd353efb7b78df3c6c7f3dbb Mon Sep 17 00:00:00 2001 From: Kegan Maher Date: Sun, 17 Oct 2021 11:18:07 -0700 Subject: [PATCH 11/81] pluralize policies in property $ids --- policy/policy.json | 4 ++-- schema/templates/policy/policy.json | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/policy/policy.json b/policy/policy.json index 37ebbf05..867fb5c6 100644 --- a/policy/policy.json +++ b/policy/policy.json @@ -617,11 +617,11 @@ ], "properties": { "policy": { - "$id": "#/properties/data/properties/policy", + "$id": "#/properties/data/properties/policies", "type": "array", "title": "The policy payload", "items": { - "$id": "#/properties/data/properties/policy/items", + "$id": "#/properties/data/properties/policies/items", "$ref": "#/definitions/policy" } } diff --git a/schema/templates/policy/policy.json b/schema/templates/policy/policy.json index 320cb43f..64c01c8c 100644 --- a/schema/templates/policy/policy.json +++ b/schema/templates/policy/policy.json @@ -340,11 +340,11 @@ ], "properties": { "policies": { - "$id": "#/properties/data/properties/policy", + "$id": "#/properties/data/properties/policies", "type": "array", "title": "The policy payload", "items": { - "$id": "#/properties/data/properties/policy/items", + "$id": "#/properties/data/properties/policies/items", "$ref": "#/definitions/policy" } } From e441008090f79a6e826c4bcc8af9c827fb40a7a0 Mon Sep 17 00:00:00 2001 From: Kegan Maher Date: Sun, 17 Oct 2021 11:22:08 -0700 Subject: [PATCH 12/81] update policies array title --- policy/policy.json | 2 +- schema/templates/policy/policy.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/policy/policy.json b/policy/policy.json index 867fb5c6..4bd9b285 100644 --- a/policy/policy.json +++ b/policy/policy.json @@ -619,7 +619,7 @@ "policy": { "$id": "#/properties/data/properties/policies", "type": "array", - "title": "The policy payload", + "title": "The array of policy objects in this payload", "items": { "$id": "#/properties/data/properties/policies/items", "$ref": "#/definitions/policy" diff --git a/schema/templates/policy/policy.json b/schema/templates/policy/policy.json index 64c01c8c..408b8818 100644 --- a/schema/templates/policy/policy.json +++ b/schema/templates/policy/policy.json @@ -342,7 +342,7 @@ "policies": { "$id": "#/properties/data/properties/policies", "type": "array", - "title": "The policy payload", + "title": "The array of policy objects in this payload", "items": { "$id": "#/properties/data/properties/policies/items", "$ref": "#/definitions/policy" From dfba163b48d4d9f2a2cd6fa60562d98f717bc0a2 Mon Sep 17 00:00:00 2001 From: Kegan Maher Date: Sun, 17 Oct 2021 11:59:11 -0700 Subject: [PATCH 13/81] pluralize prop in the schema document --- policy/policy.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/policy/policy.json b/policy/policy.json index 4bd9b285..0f42f849 100644 --- a/policy/policy.json +++ b/policy/policy.json @@ -616,7 +616,7 @@ "policies" ], "properties": { - "policy": { + "policies": { "$id": "#/properties/data/properties/policies", "type": "array", "title": "The array of policy objects in this payload", From 4c66327c7ac26ec9e03d60dac06d6429edc69524 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 18 Oct 2021 11:00:56 -0400 Subject: [PATCH 14/81] Clarified /vehicles is near-realtime --- provider/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/provider/README.md b/provider/README.md index 6810319e..0e2520ff 100644 --- a/provider/README.md +++ b/provider/README.md @@ -539,7 +539,7 @@ In the case that a `stop_id` query parameter is specified, the `stops` array ret ### Vehicles -The `/vehicles` endpoint returns the current status of vehicles in an agency's [Jurisdiction](/general-information.md#definitions) and/or area of agency responsibility. All vehicles that are currently in any [`vehicle_state`](/general-information.md#vehicle-states) should be returned in this payload. Since all states are returned, care should be taken to filter out states not in the [PROW](/general-information.md#definitions) if doing vehicle counts. For the states `elsewhere` and `removed` which include vehicles not in the [PROW](/general-information.md#definitions) but provide some operational clarity for agencies, these must only persist in the feed for 90 minutes before being removed. +The `/vehicles` is a near-realtime endpoint and returns the current status of vehicles in an agency's [Jurisdiction](/general-information.md#definitions) and/or area of agency responsibility. All vehicles that are currently in any [`vehicle_state`](/general-information.md#vehicle-states) should be returned in this payload. Since all states are returned, care should be taken to filter out states not in the [PROW](/general-information.md#definitions) if doing vehicle counts. For the states `elsewhere` and `removed` which include vehicles not in the [PROW](/general-information.md#definitions) but provide some operational clarity for agencies, these must only persist in the feed for 90 minutes before being removed. Data in this endpoint should reconcile with data from the historic [`/status_changes`](/provider#status-changes) enpdoint, though `/status_changes` is the source of truth if there are discrepancies. From f6466c753aeb901224968f77bc755a37eaa0042e Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Tue, 19 Oct 2021 16:06:04 -0400 Subject: [PATCH 15/81] Minor formatting and typo --- agency/README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/agency/README.md b/agency/README.md index 4b66b82a..c2ec16d8 100644 --- a/agency/README.md +++ b/agency/README.md @@ -184,9 +184,9 @@ Body Params: | ----------- | ----------------------------- | -------- | -------------------------------------------------------------------------------- | | `vehicle_state` | Enum | Required | see [Vehicle States][vehicle-states] | | `event_types` | Enum[] | Required | see [Vehicle Events][vehicle-events] | -| `timestamp` | [timestamp][ts] | Required | Date of last event update | +| `timestamp` | [timestamp][ts] | Required | Date of last event update | | `telemetry` | [Telemetry](#telemetry-data) | Required | Single point of telemetry. | -| `event_geographies` | UUID[] | Optional | **[Beta feature](/general-information.md#beta-features):** *Yes (as of 1.1.0)*. Array of Geography UUIDs consisting of every Geography that contains the location of the event. See [Geography Driven Events][geography-driven-events]. Required if `telemetry` is not present. | +| `event_geographies` | UUID[] | Optional | **[Beta feature](/general-information.md#beta-features):** *Yes (as of 1.1.0)*. Array of Geography UUIDs consisting of every Geography that contains the location of the event. See [Geography Driven Events][geography-driven-events]. Required if `telemetry` is not present. | | `trip_id` | UUID | Optional | UUID provided by Operator to uniquely identify the trip. Required if `event_types` contains `trip_start`, `trip_end`, `trip_cancel`, `trip_enter_jurisdiction`, or `trip_leave_jurisdiction` | 201 Success Response: @@ -223,7 +223,7 @@ Body Params: | Field | Type | Field Description | | ---------- | ------------------------------ | ------------------------------------------------------------------------------------------------------- | | `success` | Integer | Number of successfully written telemetry data points. | -| `total` | Integer | Ttotal number of provided points. | +| `total` | Integer | Total number of provided points. | | `failures` | [Telemetry](#telemetry-data)[] | Array of failed telemetry for zero or more vehicles (empty if all successful). | 400 Failure Response: @@ -244,7 +244,7 @@ A standard point of vehicle telemetry. References to latitude and longitude impl | Field | Type | Required/Optional | Field Description | | -------------- | -------------- | --------------------- | ------------------------------------------------------------ | | `device_id` | UUID | Required | ID used in [Register](#vehicle---register) | -| `timestamp` | [timestamp][ts] | Required | Date/time that event occurred. Based on GPS or GNSS clock | +| `timestamp` | [timestamp][ts]| Required | Date/time that event occurred. Based on GPS or GNSS clock | | `gps` | Object | Required | Telemetry position data | | `gps.lat` | Double | Required | Latitude of the location | | `gps.lng` | Double | Required | Longitude of the location | From 4fdb6282d103c9049648ec6c52a12380facbc265 Mon Sep 17 00:00:00 2001 From: Kegan Maher Date: Sun, 17 Oct 2021 12:09:02 -0700 Subject: [PATCH 16/81] apply formatting for readability --- ...iered-parking-fees-per-hour-in-bounds.json | 42 ++++++++++++---- .../tiered-parking-fees-per-hour.json | 48 ++++++++++++++----- .../examples/tiered-parking-fees-total.json | 48 ++++++++++++++----- 3 files changed, 105 insertions(+), 33 deletions(-) diff --git a/policy/examples/tiered-parking-fees-per-hour-in-bounds.json b/policy/examples/tiered-parking-fees-per-hour-in-bounds.json index 05ed514a..81ea96ba 100644 --- a/policy/examples/tiered-parking-fees-per-hour-in-bounds.json +++ b/policy/examples/tiered-parking-fees-per-hour-in-bounds.json @@ -14,9 +14,17 @@ "rule_id": "6b6fe61b-dbe5-4367-8e35-84fb14d23c54", "rule_type": "time", "rule_units": "hours", - "geographies": ["0c77c813-bece-4e8a-84fd-f99af777d198"], - "statuses": { "available": [], "non_operational": [] }, - "vehicle_types": ["bicycle", "scooter"], + "geographies": [ + "0c77c813-bece-4e8a-84fd-f99af777d198" + ], + "statuses": { + "available": [], + "non_operational": [] + }, + "vehicle_types": [ + "bicycle", + "scooter" + ], "maximum": 1, "inclusive_maximum": false, "rate_applies_when": "in_bounds", @@ -28,9 +36,17 @@ "rule_id": "edd6a195-bb30-4eb5-a2cc-44e5a18798a2", "rule_type": "time", "rule_units": "hours", - "geographies": ["0c77c813-bece-4e8a-84fd-f99af777d198"], - "statuses": { "available": [], "non_operational": [] }, - "vehicle_types": ["bicycle", "scooter"], + "geographies": [ + "0c77c813-bece-4e8a-84fd-f99af777d198" + ], + "statuses": { + "available": [], + "non_operational": [] + }, + "vehicle_types": [ + "bicycle", + "scooter" + ], "minimum": 1, "maximum": 2, "inclusive_minimum": true, @@ -44,9 +60,17 @@ "rule_id": "9cd1768c-ab9e-484c-93f8-72a7078aa7b9", "rule_type": "time", "rule_units": "hours", - "geographies": ["0c77c813-bece-4e8a-84fd-f99af777d198"], - "statuses": { "available": [], "non_operational": [] }, - "vehicle_types": ["bicycle", "scooter"], + "geographies": [ + "0c77c813-bece-4e8a-84fd-f99af777d198" + ], + "statuses": { + "available": [], + "non_operational": [] + }, + "vehicle_types": [ + "bicycle", + "scooter" + ], "minimum": 2, "inclusive_minimum": true, "rate_applies_when": "in_bounds", diff --git a/policy/examples/tiered-parking-fees-per-hour.json b/policy/examples/tiered-parking-fees-per-hour.json index a763e652..aa973921 100644 --- a/policy/examples/tiered-parking-fees-per-hour.json +++ b/policy/examples/tiered-parking-fees-per-hour.json @@ -19,36 +19,60 @@ "rule_id": "9cd1768c-ab9e-484c-93f8-72a7078aa7b9", "rule_type": "time", "rule_units": "hours", - "geographies": ["0c77c813-bece-4e8a-84fd-f99af777d198"], - "statuses": { "available": [], "non_operational": [] }, - "vehicle_types": ["bicycle", "scooter"], + "geographies": [ + "0c77c813-bece-4e8a-84fd-f99af777d198" + ], + "statuses": { + "available": [], + "non_operational": [] + }, + "vehicle_types": [ + "bicycle", + "scooter" + ], "maximum": 2, "rate_amount": 1000, - "rate_recurrence": "each_time_unit" + "rate_recurrence": "each_time_unit" }, { "name": "1-2 Hours", "rule_id": "edd6a195-bb30-4eb5-a2cc-44e5a18798a2", "rule_type": "time", "rule_units": "hours", - "geographies": ["0c77c813-bece-4e8a-84fd-f99af777d198"], - "statuses": { "available": [], "non_operational": [] }, - "vehicle_types": ["bicycle", "scooter"], + "geographies": [ + "0c77c813-bece-4e8a-84fd-f99af777d198" + ], + "statuses": { + "available": [], + "non_operational": [] + }, + "vehicle_types": [ + "bicycle", + "scooter" + ], "maximum": 1, "rate_amount": 400, - "rate_recurrence": "each_time_unit" + "rate_recurrence": "each_time_unit" }, { "name": "0-1 Hour", "rule_id": "6b6fe61b-dbe5-4367-8e35-84fb14d23c54", "rule_type": "time", "rule_units": "hours", - "geographies": ["0c77c813-bece-4e8a-84fd-f99af777d198"], - "statuses": { "available": [], "non_operational": [] }, - "vehicle_types": ["bicycle", "scooter"], + "geographies": [ + "0c77c813-bece-4e8a-84fd-f99af777d198" + ], + "statuses": { + "available": [], + "non_operational": [] + }, + "vehicle_types": [ + "bicycle", + "scooter" + ], "maximum": 0, "rate_amount": 200, - "rate_recurrence": "each_time_unit" + "rate_recurrence": "each_time_unit" } ] } diff --git a/policy/examples/tiered-parking-fees-total.json b/policy/examples/tiered-parking-fees-total.json index d0bef60f..dac70774 100644 --- a/policy/examples/tiered-parking-fees-total.json +++ b/policy/examples/tiered-parking-fees-total.json @@ -19,36 +19,60 @@ "rule_id": "9cd1768c-ab9e-484c-93f8-72a7078aa7b9", "rule_type": "time", "rule_units": "hours", - "geographies": ["0c77c813-bece-4e8a-84fd-f99af777d198"], - "statuses": { "available": [], "non_operational": [] }, - "vehicle_types": ["bicycle", "scooter"], + "geographies": [ + "0c77c813-bece-4e8a-84fd-f99af777d198" + ], + "statuses": { + "available": [], + "non_operational": [] + }, + "vehicle_types": [ + "bicycle", + "scooter" + ], "maximum": 2, "rate_amount": 1000, - "rate_recurrence": "once_on_unmatch" + "rate_recurrence": "once_on_unmatch" }, { "name": "1-2 Hours", "rule_id": "edd6a195-bb30-4eb5-a2cc-44e5a18798a2", "rule_type": "time", "rule_units": "hours", - "geographies": ["0c77c813-bece-4e8a-84fd-f99af777d198"], - "statuses": { "available": [], "non_operational": [] }, - "vehicle_types": ["bicycle", "scooter"], + "geographies": [ + "0c77c813-bece-4e8a-84fd-f99af777d198" + ], + "statuses": { + "available": [], + "non_operational": [] + }, + "vehicle_types": [ + "bicycle", + "scooter" + ], "maximum": 1, "rate_amount": 400, - "rate_recurrence": "once_on_unmatch" + "rate_recurrence": "once_on_unmatch" }, { "name": "0-1 Hour", "rule_id": "6b6fe61b-dbe5-4367-8e35-84fb14d23c54", "rule_type": "time", "rule_units": "hours", - "geographies": ["0c77c813-bece-4e8a-84fd-f99af777d198"], - "statuses": { "available": [], "non_operational": [] }, - "vehicle_types": ["bicycle", "scooter"], + "geographies": [ + "0c77c813-bece-4e8a-84fd-f99af777d198" + ], + "statuses": { + "available": [], + "non_operational": [] + }, + "vehicle_types": [ + "bicycle", + "scooter" + ], "maximum": 0, "rate_amount": 200, - "rate_recurrence": "once_on_unmatch" + "rate_recurrence": "once_on_unmatch" } ] } From 074eebc553fac8cb774b5e2caed9587af409fbb0 Mon Sep 17 00:00:00 2001 From: Kegan Maher Date: Sun, 17 Oct 2021 12:11:48 -0700 Subject: [PATCH 17/81] wrap example policy in full payload body --- ...iered-parking-fees-per-hour-in-bounds.json | 166 +++++++++--------- 1 file changed, 87 insertions(+), 79 deletions(-) diff --git a/policy/examples/tiered-parking-fees-per-hour-in-bounds.json b/policy/examples/tiered-parking-fees-per-hour-in-bounds.json index 81ea96ba..3a2489c8 100644 --- a/policy/examples/tiered-parking-fees-per-hour-in-bounds.json +++ b/policy/examples/tiered-parking-fees-per-hour-in-bounds.json @@ -1,81 +1,89 @@ { - "name": "Tiered Dwell Time Example", - "description": "First hour $2, second hour $4, every hour onwards $10", - "policy_id": "2800cd0a-7827-4110-9713-b9e5bf29e9a1", - "start_date": 1558389669540, - "publish_date": 1558389669540, - "end_date": null, - "prev_policies": null, - "provider_ids": [], - "currency": "USD", - "rules": [ - { - "name": "0-1 Hour", - "rule_id": "6b6fe61b-dbe5-4367-8e35-84fb14d23c54", - "rule_type": "time", - "rule_units": "hours", - "geographies": [ - "0c77c813-bece-4e8a-84fd-f99af777d198" - ], - "statuses": { - "available": [], - "non_operational": [] - }, - "vehicle_types": [ - "bicycle", - "scooter" - ], - "maximum": 1, - "inclusive_maximum": false, - "rate_applies_when": "in_bounds", - "rate_amount": 200, - "rate_recurrence": "each_time_unit" - }, - { - "name": "1-2 Hours", - "rule_id": "edd6a195-bb30-4eb5-a2cc-44e5a18798a2", - "rule_type": "time", - "rule_units": "hours", - "geographies": [ - "0c77c813-bece-4e8a-84fd-f99af777d198" - ], - "statuses": { - "available": [], - "non_operational": [] - }, - "vehicle_types": [ - "bicycle", - "scooter" - ], - "minimum": 1, - "maximum": 2, - "inclusive_minimum": true, - "inclusive_maximum": false, - "rate_applies_when": "in_bounds", - "rate_amount": 400, - "rate_recurrence": "each_time_unit" - }, - { - "name": "> 2 hours", - "rule_id": "9cd1768c-ab9e-484c-93f8-72a7078aa7b9", - "rule_type": "time", - "rule_units": "hours", - "geographies": [ - "0c77c813-bece-4e8a-84fd-f99af777d198" - ], - "statuses": { - "available": [], - "non_operational": [] - }, - "vehicle_types": [ - "bicycle", - "scooter" - ], - "minimum": 2, - "inclusive_minimum": true, - "rate_applies_when": "in_bounds", - "rate_amount": 1000, - "rate_recurrence": "each_time_unit" - } - ] + "updated": 0, + "version": "1.2.0", + "data": { + "policies": [ + { + "name": "Tiered Dwell Time Example", + "description": "First hour $2, second hour $4, every hour onwards $10", + "policy_id": "2800cd0a-7827-4110-9713-b9e5bf29e9a1", + "start_date": 1558389669540, + "publish_date": 1558389669540, + "end_date": null, + "prev_policies": null, + "provider_ids": [], + "currency": "USD", + "rules": [ + { + "name": "0-1 Hour", + "rule_id": "6b6fe61b-dbe5-4367-8e35-84fb14d23c54", + "rule_type": "time", + "rule_units": "hours", + "geographies": [ + "0c77c813-bece-4e8a-84fd-f99af777d198" + ], + "statuses": { + "available": [], + "non_operational": [] + }, + "vehicle_types": [ + "bicycle", + "scooter" + ], + "maximum": 1, + "inclusive_maximum": false, + "rate_applies_when": "in_bounds", + "rate_amount": 200, + "rate_recurrence": "each_time_unit" + }, + { + "name": "1-2 Hours", + "rule_id": "edd6a195-bb30-4eb5-a2cc-44e5a18798a2", + "rule_type": "time", + "rule_units": "hours", + "geographies": [ + "0c77c813-bece-4e8a-84fd-f99af777d198" + ], + "statuses": { + "available": [], + "non_operational": [] + }, + "vehicle_types": [ + "bicycle", + "scooter" + ], + "minimum": 1, + "maximum": 2, + "inclusive_minimum": true, + "inclusive_maximum": false, + "rate_applies_when": "in_bounds", + "rate_amount": 400, + "rate_recurrence": "each_time_unit" + }, + { + "name": "> 2 hours", + "rule_id": "9cd1768c-ab9e-484c-93f8-72a7078aa7b9", + "rule_type": "time", + "rule_units": "hours", + "geographies": [ + "0c77c813-bece-4e8a-84fd-f99af777d198" + ], + "statuses": { + "available": [], + "non_operational": [] + }, + "vehicle_types": [ + "bicycle", + "scooter" + ], + "minimum": 2, + "inclusive_minimum": true, + "rate_applies_when": "in_bounds", + "rate_amount": 1000, + "rate_recurrence": "each_time_unit" + } + ] + } + ] + } } From 7263398417e45acaa9d6191fc0270ab84b4adf23 Mon Sep 17 00:00:00 2001 From: Kegan Maher Date: Tue, 19 Oct 2021 19:30:48 -0700 Subject: [PATCH 18/81] regenerate agency schemas with cargo_bicycle --- agency/get_stops.json | 5 +++++ agency/get_vehicle.json | 1 + agency/post_stops.json | 5 +++++ agency/post_vehicle.json | 1 + agency/put_stops.json | 5 +++++ 5 files changed, 17 insertions(+) diff --git a/agency/get_stops.json b/agency/get_stops.json index 120904ec..c88cec97 100644 --- a/agency/get_stops.json +++ b/agency/get_stops.json @@ -186,6 +186,11 @@ "type": "integer", "minimum": 0 }, + "cargo_bicycle": { + "$id": "#/definitions/vehicle_type_counts/properties/cargo_bicycle", + "type": "integer", + "minimum": 0 + }, "car": { "$id": "#/definitions/vehicle_type_counts/properties/car", "type": "integer", diff --git a/agency/get_vehicle.json b/agency/get_vehicle.json index 2358166b..bd27ab48 100644 --- a/agency/get_vehicle.json +++ b/agency/get_vehicle.json @@ -38,6 +38,7 @@ "description": "The type of vehicle", "enum": [ "bicycle", + "cargo_bicycle", "car", "scooter", "moped", diff --git a/agency/post_stops.json b/agency/post_stops.json index 8cc77041..861db0b1 100644 --- a/agency/post_stops.json +++ b/agency/post_stops.json @@ -186,6 +186,11 @@ "type": "integer", "minimum": 0 }, + "cargo_bicycle": { + "$id": "#/definitions/vehicle_type_counts/properties/cargo_bicycle", + "type": "integer", + "minimum": 0 + }, "car": { "$id": "#/definitions/vehicle_type_counts/properties/car", "type": "integer", diff --git a/agency/post_vehicle.json b/agency/post_vehicle.json index 2d1ec9e3..21d14ec2 100644 --- a/agency/post_vehicle.json +++ b/agency/post_vehicle.json @@ -31,6 +31,7 @@ "description": "The type of vehicle", "enum": [ "bicycle", + "cargo_bicycle", "car", "scooter", "moped", diff --git a/agency/put_stops.json b/agency/put_stops.json index 8e6f7639..5f510cdb 100644 --- a/agency/put_stops.json +++ b/agency/put_stops.json @@ -47,6 +47,11 @@ "type": "integer", "minimum": 0 }, + "cargo_bicycle": { + "$id": "#/definitions/vehicle_type_counts/properties/cargo_bicycle", + "type": "integer", + "minimum": 0 + }, "car": { "$id": "#/definitions/vehicle_type_counts/properties/car", "type": "integer", From 080ea53dcfc392696ecada7b7f47807229e623d9 Mon Sep 17 00:00:00 2001 From: Kegan Maher Date: Tue, 19 Oct 2021 19:45:29 -0700 Subject: [PATCH 19/81] regenerate policy schema with cargo_bicycle --- policy/policy.json | 1 + 1 file changed, 1 insertion(+) diff --git a/policy/policy.json b/policy/policy.json index 25d9994e..df519813 100644 --- a/policy/policy.json +++ b/policy/policy.json @@ -480,6 +480,7 @@ "description": "The type of vehicle", "enum": [ "bicycle", + "cargo_bicycle", "car", "scooter", "moped", From b83ddb934ad11a394baae8eb3ee0b61ba6132c45 Mon Sep 17 00:00:00 2001 From: Kegan Maher Date: Tue, 19 Oct 2021 19:47:58 -0700 Subject: [PATCH 20/81] regenerate provider schemas with cargo_bicycle --- provider/events.json | 1 + provider/status_changes.json | 1 + provider/stops.json | 5 +++++ provider/trips.json | 1 + provider/vehicles.json | 1 + 5 files changed, 9 insertions(+) diff --git a/provider/events.json b/provider/events.json index 2312ba0b..b657ec6e 100644 --- a/provider/events.json +++ b/provider/events.json @@ -151,6 +151,7 @@ "description": "The type of vehicle", "enum": [ "bicycle", + "cargo_bicycle", "car", "scooter", "moped", diff --git a/provider/status_changes.json b/provider/status_changes.json index 558ea56d..eb2bbd12 100644 --- a/provider/status_changes.json +++ b/provider/status_changes.json @@ -151,6 +151,7 @@ "description": "The type of vehicle", "enum": [ "bicycle", + "cargo_bicycle", "car", "scooter", "moped", diff --git a/provider/stops.json b/provider/stops.json index 6ec41313..6d0dc1a3 100644 --- a/provider/stops.json +++ b/provider/stops.json @@ -285,6 +285,11 @@ "type": "integer", "minimum": 0 }, + "cargo_bicycle": { + "$id": "#/definitions/vehicle_type_counts/properties/cargo_bicycle", + "type": "integer", + "minimum": 0 + }, "car": { "$id": "#/definitions/vehicle_type_counts/properties/car", "type": "integer", diff --git a/provider/trips.json b/provider/trips.json index 6107ac4e..d453aa88 100644 --- a/provider/trips.json +++ b/provider/trips.json @@ -197,6 +197,7 @@ "description": "The type of vehicle", "enum": [ "bicycle", + "cargo_bicycle", "car", "scooter", "moped", diff --git a/provider/vehicles.json b/provider/vehicles.json index 92d36da1..d71b99fe 100644 --- a/provider/vehicles.json +++ b/provider/vehicles.json @@ -274,6 +274,7 @@ "description": "The type of vehicle", "enum": [ "bicycle", + "cargo_bicycle", "car", "scooter", "moped", From b6caa1f82918f269758b2f911e3f7a98e985d96f Mon Sep 17 00:00:00 2001 From: Kegan Maher Date: Tue, 19 Oct 2021 20:12:23 -0700 Subject: [PATCH 21/81] update geojson feature in agency schemas the upstream schema definition was updated to allow number or string for the id property --- agency/get_stops.json | 10 ++++++++++ agency/post_stops.json | 10 ++++++++++ 2 files changed, 20 insertions(+) diff --git a/agency/get_stops.json b/agency/get_stops.json index 120904ec..ceff2721 100644 --- a/agency/get_stops.json +++ b/agency/get_stops.json @@ -225,6 +225,16 @@ "Feature" ] }, + "id": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ] + }, "properties": { "type": "object", "required": [ diff --git a/agency/post_stops.json b/agency/post_stops.json index 8cc77041..1d0c1d1d 100644 --- a/agency/post_stops.json +++ b/agency/post_stops.json @@ -225,6 +225,16 @@ "Feature" ] }, + "id": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ] + }, "properties": { "type": "object", "required": [ From 8c4b417d6b4b09756b92f4da66601c6167de25b4 Mon Sep 17 00:00:00 2001 From: Kegan Maher Date: Tue, 19 Oct 2021 20:13:10 -0700 Subject: [PATCH 22/81] update geojson feature in provider schemas the upstream schema definition was updated to allow number or string for the id property --- provider/events.json | 10 ++++++++++ provider/status_changes.json | 10 ++++++++++ provider/stops.json | 10 ++++++++++ provider/trips.json | 10 ++++++++++ provider/vehicles.json | 10 ++++++++++ 5 files changed, 50 insertions(+) diff --git a/provider/events.json b/provider/events.json index 2312ba0b..6936f39d 100644 --- a/provider/events.json +++ b/provider/events.json @@ -98,6 +98,16 @@ "Feature" ] }, + "id": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ] + }, "properties": { "type": "object", "required": [ diff --git a/provider/status_changes.json b/provider/status_changes.json index 558ea56d..1248ae6b 100644 --- a/provider/status_changes.json +++ b/provider/status_changes.json @@ -98,6 +98,16 @@ "Feature" ] }, + "id": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ] + }, "properties": { "type": "object", "required": [ diff --git a/provider/stops.json b/provider/stops.json index 6ec41313..c4c56794 100644 --- a/provider/stops.json +++ b/provider/stops.json @@ -98,6 +98,16 @@ "Feature" ] }, + "id": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ] + }, "properties": { "type": "object", "required": [ diff --git a/provider/trips.json b/provider/trips.json index 6107ac4e..a4a865cd 100644 --- a/provider/trips.json +++ b/provider/trips.json @@ -98,6 +98,16 @@ "Feature" ] }, + "id": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ] + }, "properties": { "type": "object", "required": [ diff --git a/provider/vehicles.json b/provider/vehicles.json index 92d36da1..ef7c4ec4 100644 --- a/provider/vehicles.json +++ b/provider/vehicles.json @@ -98,6 +98,16 @@ "Feature" ] }, + "id": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + } + ] + }, "properties": { "type": "object", "required": [ From fd321ab5878b91f4ee53229143a8e527806b8248 Mon Sep 17 00:00:00 2001 From: Kegan Maher Date: Mon, 25 Oct 2021 14:58:25 -0700 Subject: [PATCH 23/81] refactor telemetry props from vehicle props these can be re-used in the new Feature geometry --- schema/agency.py | 14 +- .../templates/agency/post_vehicle_event.json | 2 +- .../agency/post_vehicle_telemetry.json | 2 +- schema/templates/common.json | 126 ++++++++++-------- 4 files changed, 81 insertions(+), 63 deletions(-) diff --git a/schema/agency.py b/schema/agency.py index bbd34968..9c7e41c0 100644 --- a/schema/agency.py +++ b/schema/agency.py @@ -7,6 +7,16 @@ import common +def vehicle_telemetry(): + telemetry = common.load_definitions("telemetry") + vehicle_telemetry = common.load_definitions("vehicle_telemetry") + + # merge the standard telemetry props into vehicle_telemetry.gps + vehicle_telemetry["properties"]["gps"]["properties"].update(telemetry["properties"]) + + return vehicle_telemetry + + def get_stops_schema(): """ Create the schema for the Agency GET /stops endpoint. @@ -113,10 +123,10 @@ def post_vehicle_event_schema(): # load schema template and insert definitions schema = common.load_json("./templates/agency/post_vehicle_event.json") definitions = common.load_definitions( - "telemetry", "timestamp", "uuid" ) + definitions["vehicle_telemetry"] = vehicle_telemetry() schema["definitions"].update(definitions) # merge the state machine definitions and transition combinations rule @@ -139,10 +149,10 @@ def post_vehicle_telemetry_schema(): # load schema template and insert definitions schema = common.load_json("./templates/agency/post_vehicle_telemetry.json") definitions = common.load_definitions( - "telemetry", "timestamp", "uuid" ) + definitions["vehicle_telemetry"] = vehicle_telemetry() schema["definitions"].update(definitions) # verify and return diff --git a/schema/templates/agency/post_vehicle_event.json b/schema/templates/agency/post_vehicle_event.json index c2880b9c..d7b4dfdc 100644 --- a/schema/templates/agency/post_vehicle_event.json +++ b/schema/templates/agency/post_vehicle_event.json @@ -21,7 +21,7 @@ "$ref": "#/definitions/timestamp" }, "telemetry": { - "$ref": "#/definitions/telemetry" + "$ref": "#/definitions/vehicle_telemetry" }, "trip_id": { "$ref": "#/definitions/uuid" diff --git a/schema/templates/agency/post_vehicle_telemetry.json b/schema/templates/agency/post_vehicle_telemetry.json index 39e93dbf..f7ad99f9 100644 --- a/schema/templates/agency/post_vehicle_telemetry.json +++ b/schema/templates/agency/post_vehicle_telemetry.json @@ -11,7 +11,7 @@ "data": { "type": "array", "items": { - "$ref": "#/definitions/telemetry" + "$ref": "#/definitions/vehicle_telemetry" } } }, diff --git a/schema/templates/common.json b/schema/templates/common.json index 141c077f..03778bbf 100644 --- a/schema/templates/common.json +++ b/schema/templates/common.json @@ -307,71 +307,32 @@ "telemetry": { "$id": "#/definitions/telemetry", "type": "object", - "description": "A vehicle telemetry datum", - "required": [ - "device_id", - "timestamp", - "gps" - ], + "description": "A telemetry datum", "additionalProperties": false, "properties": { - "device_id": { - "$ref": "#/definitions/uuid" + "altitude": { + "type": "number", + "description": "Altitude above mean sea level in meters" }, - "timestamp": { - "$ref": "#/definitions/timestamp" + "heading": { + "type": "number", + "description": "Degrees - clockwise starting at 0 degrees at true North" }, - "gps": { - "type": "object", - "required": [ - "lat", - "lng" - ], - "additionalProperties": false, - "properties": { - "lat": { - "type": "number", - "description": "Latitude of the location", - "minimum": -90, - "maximum": 90 - }, - "lng": { - "type": "number", - "description": "Longitude of the location", - "minimum": -180, - "maximum": 180 - }, - "altitude": { - "type": "number", - "description": "Altitude above mean sea level in meters" - }, - "heading": { - "type": "number", - "description": "Degrees clockwise from true north" - }, - "speed": { - "type": "number", - "description": "Speed in meters/sec" - }, - "accuracy": { - "type": "number", - "description": "Accuracy in meters" - }, - "hdop": { - "type": "number", - "description": "Horizontal GPS or GNSS accuracy value" - }, - "satellites": { - "type": "integer", - "description": "Number of GPS or GNSS satellites" - } - } + "speed": { + "type": "number", + "description": "Estimated speed in meters / sec as reported by the GPS chipset" }, - "charge": { + "accuracy": { "type": "number", - "description": "Fraction of charge of the vehicle (required if applicable", - "minimum": 0, - "maximum": 1 + "description": "Horizontal accuracy, in meters" + }, + "hdop": { + "type": "number", + "description": "Horizontal GPS or GNSS accuracy value" + }, + "satellites": { + "type": "integer", + "description": "Number of GPS or GNSS satellites" } } }, @@ -677,6 +638,53 @@ } ] }, + "vehicle_telemetry": { + "$id": "#/definitions/vehicle_telemetry", + "type": "object", + "description": "A telemetry datum for a specific vehicle at a specific time", + "required": [ + "device_id", + "timestamp", + "gps" + ], + "additionalProperties": false, + "properties": { + "device_id": { + "$ref": "#/definitions/uuid" + }, + "timestamp": { + "$ref": "#/definitions/timestamp" + }, + "gps": { + "type": "object", + "required": [ + "lat", + "lng" + ], + "additionalProperties": false, + "properties": { + "lat": { + "type": "number", + "description": "Latitude of the location", + "minimum": -90, + "maximum": 90 + }, + "lng": { + "type": "number", + "description": "Longitude of the location", + "minimum": -180, + "maximum": 180 + } + } + }, + "charge": { + "type": "number", + "description": "Fraction of charge of the vehicle (required if applicable)", + "minimum": 0, + "maximum": 1 + } + } + }, "vehicle_type": { "$id": "#/definitions/vehicle_type", "type": "string", From 64bae6fb4a96eb1b9a2868ced868e92c98b5565b Mon Sep 17 00:00:00 2001 From: Kegan Maher Date: Mon, 25 Oct 2021 15:59:04 -0700 Subject: [PATCH 24/81] refactor feature point creation the feature_schema function was only used by the mds_feature_point_definition function, so combine the two and work on the GeoJSON feature directly --- schema/common.py | 71 ++++++++++++++++-------------------------------- 1 file changed, 24 insertions(+), 47 deletions(-) diff --git a/schema/common.py b/schema/common.py index 837fd964..cc9c35ac 100644 --- a/schema/common.py +++ b/schema/common.py @@ -128,66 +128,43 @@ def point_definition(): } -def feature_schema(id=None, title=None, geometry=None, properties=None, required=None): +def mds_feature_point_definition(): """ - Get the canonical schema for a GeoJSON Feature, - and make any given modifications. - - :id: overrides the `$id` metadata - :title: overrides the `title` metadata - :geometry: overrides the allowed `geometry` for the Feature - :properties: overrides the `properties` definitions for this Feature - :required: is a list of required :properties: + Create a customized definition of the GeoJSON Feature schema for MDS Points. """ + name = "MDS_Feature_Point" + # Get the canonical Feature schema feature = requests.get("http://geojson.org/schema/Feature.json").json() - # Modify some metadata + # Modify metadata feature.pop("$schema") - if id is not None: - feature["$id"] = id - if title is not None: - feature["title"] = title + feature["$id"] = definition_id(name) + feature["title"] = "MDS GeoJSON Feature Point" - if geometry is not None: - feature["properties"]["geometry"] = geometry + # Only allow GeoJSON Point feature geometry + feature["properties"]["geometry"] = { "$ref": definition_id("Point") } + # Modfy properties definition/requirements f_properties = feature["properties"]["properties"] - if required is not None: - del f_properties["oneOf"] - f_properties["type"] = "object" - f_properties["required"] = required - if properties is not None: - f_properties["properties"] = properties - - return feature + del f_properties["oneOf"] + f_properties["type"] = "object" + # Point features must include the timestamp + f_properties["required"] = ["timestamp"] -def mds_feature_point_definition(): - """ - Create a customized definition of the GeoJSON Feature schema for MDS Points. - """ - name = "MDS_Feature_Point" - return { - name: feature_schema( - id = definition_id(name), - title = "MDS GeoJSON Feature Point", - # Only allow GeoJSON Point feature geometry - geometry = { "$ref": definition_id("Point") }, - properties = { - "timestamp": { - "$ref": definition_id("timestamp") - }, - # Locations corresponding to Stops must include a `stop_id` reference - "stop_id": { - "$ref": definition_id("uuid") - } - }, - # Point features *must* include the `timestamp` - required = ["timestamp"] - ) + f_properties["properties"] = { + "timestamp": { + "$ref": definition_id("timestamp") + }, + # Locations corresponding to Stops must include a stop_id reference + "stop_id": { + "$ref": definition_id("uuid") + } } + return {name: feature} + def stop_definitions(): """ From 3ee2e3d768bc0f68e39fb1266151492979f3a9ec Mon Sep 17 00:00:00 2001 From: Kegan Maher Date: Mon, 25 Oct 2021 16:27:37 -0700 Subject: [PATCH 25/81] refactor definition name to module-level variable transition consumers to load the definition by name instead of making another function call to mds_feature_point_definition --- schema/common.py | 13 +++++++------ schema/provider.py | 4 ++-- 2 files changed, 9 insertions(+), 8 deletions(-) diff --git a/schema/common.py b/schema/common.py index cc9c35ac..813d03af 100644 --- a/schema/common.py +++ b/schema/common.py @@ -11,6 +11,9 @@ COMMON_DEFINITIONS = {} +MDS_FEATURE_POINT = "MDS_Feature_Point" + + def load_json(path): """ Load a JSON file from disk. @@ -132,14 +135,12 @@ def mds_feature_point_definition(): """ Create a customized definition of the GeoJSON Feature schema for MDS Points. """ - name = "MDS_Feature_Point" - # Get the canonical Feature schema feature = requests.get("http://geojson.org/schema/Feature.json").json() # Modify metadata feature.pop("$schema") - feature["$id"] = definition_id(name) + feature["$id"] = definition_id(MDS_FEATURE_POINT) feature["title"] = "MDS GeoJSON Feature Point" # Only allow GeoJSON Point feature geometry @@ -163,7 +164,7 @@ def mds_feature_point_definition(): } } - return {name: feature} + return {MDS_FEATURE_POINT: feature} def stop_definitions(): @@ -177,9 +178,9 @@ def stop_definitions(): "timestamp", "uuid", "uuid_array", - "vehicle_type_counts" + "vehicle_type_counts", + MDS_FEATURE_POINT ) - definitions.update(mds_feature_point_definition()) return definitions diff --git a/schema/provider.py b/schema/provider.py index b682ee04..cb8efad9 100644 --- a/schema/provider.py +++ b/schema/provider.py @@ -48,10 +48,10 @@ def endpoint_schema(endpoint, extra_definitions={}): "string", "timestamp", "uuid", - "version" + "version", + common.MDS_FEATURE_POINT ) definitions.update(common.point_definition()) - definitions.update(common.mds_feature_point_definition()) definitions.update(extra_definitions) endpoint_schema = common.load_json(f"./templates/provider/{endpoint}.json") From cf9493d18aadd2cd82a785b424ce51cfe233ff18 Mon Sep 17 00:00:00 2001 From: Kegan Maher Date: Mon, 25 Oct 2021 16:30:49 -0700 Subject: [PATCH 26/81] merge telemetry props into Feature props pass common definitions to reuse telemetry props, make argument required for these initialization functions --- schema/common.py | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/schema/common.py b/schema/common.py index 813d03af..cd0184fc 100644 --- a/schema/common.py +++ b/schema/common.py @@ -74,14 +74,14 @@ def vehicle_state_machine(vehicle_state=None, vehicle_events=None): return (state_machine_defs, transitions) -def vehicle_type_counts_definition(definitions=None): +def vehicle_type_counts_definition(definitions): """ Generate a definition for a dict of vehicle_type: int. """ vehicle_type_counts = {} def_name = "vehicle_type_counts" def_id = definition_id(def_name) - vehicle_types = definitions["vehicle_type"] if definitions else load_definitions("vehicle_type") + vehicle_types = definitions["vehicle_type"] for vehicle_type in vehicle_types["enum"]: vehicle_type_counts[vehicle_type] = { @@ -131,7 +131,7 @@ def point_definition(): } -def mds_feature_point_definition(): +def mds_feature_point_definition(definitions): """ Create a customized definition of the GeoJSON Feature schema for MDS Points. """ @@ -164,6 +164,10 @@ def mds_feature_point_definition(): } } + # merge telemetry props + telemetry = definitions["telemetry"] + f_properties["properties"].update(telemetry["properties"]) + return {MDS_FEATURE_POINT: feature} @@ -216,7 +220,7 @@ def load_definitions(*args, allow_null=False): common_definitions = common["definitions"] # MDS specific geography definition - mds_feature = mds_feature_point_definition() + mds_feature = mds_feature_point_definition(common_definitions) common_definitions.update(mds_feature) # vehicle_type -> count definition From 6d53528325854030bf592d9d1a63998c75ab4b95 Mon Sep 17 00:00:00 2001 From: Kegan Maher Date: Tue, 26 Oct 2021 08:39:44 -0700 Subject: [PATCH 27/81] update agency schemas with new telemetry defs --- agency/get_stops.json | 24 ++++++++++++++ agency/post_stops.json | 24 ++++++++++++++ agency/post_vehicle_event.json | 50 +++++++++++++++--------------- agency/post_vehicle_telemetry.json | 50 +++++++++++++++--------------- 4 files changed, 98 insertions(+), 50 deletions(-) diff --git a/agency/get_stops.json b/agency/get_stops.json index ceff2721..f32974d1 100644 --- a/agency/get_stops.json +++ b/agency/get_stops.json @@ -246,6 +246,30 @@ }, "stop_id": { "$ref": "#/definitions/uuid" + }, + "altitude": { + "type": "number", + "description": "Altitude above mean sea level in meters" + }, + "heading": { + "type": "number", + "description": "Degrees - clockwise starting at 0 degrees at true North" + }, + "speed": { + "type": "number", + "description": "Estimated speed in meters / sec as reported by the GPS chipset" + }, + "accuracy": { + "type": "number", + "description": "Horizontal accuracy, in meters" + }, + "hdop": { + "type": "number", + "description": "Horizontal GPS or GNSS accuracy value" + }, + "satellites": { + "type": "integer", + "description": "Number of GPS or GNSS satellites" } } }, diff --git a/agency/post_stops.json b/agency/post_stops.json index 1d0c1d1d..158642ac 100644 --- a/agency/post_stops.json +++ b/agency/post_stops.json @@ -246,6 +246,30 @@ }, "stop_id": { "$ref": "#/definitions/uuid" + }, + "altitude": { + "type": "number", + "description": "Altitude above mean sea level in meters" + }, + "heading": { + "type": "number", + "description": "Degrees - clockwise starting at 0 degrees at true North" + }, + "speed": { + "type": "number", + "description": "Estimated speed in meters / sec as reported by the GPS chipset" + }, + "accuracy": { + "type": "number", + "description": "Horizontal accuracy, in meters" + }, + "hdop": { + "type": "number", + "description": "Horizontal GPS or GNSS accuracy value" + }, + "satellites": { + "type": "integer", + "description": "Number of GPS or GNSS satellites" } } }, diff --git a/agency/post_vehicle_event.json b/agency/post_vehicle_event.json index 49d5eff9..57bf7b99 100644 --- a/agency/post_vehicle_event.json +++ b/agency/post_vehicle_event.json @@ -4,10 +4,27 @@ "title": "The MDS Agency Schema, POST vehicle status body", "type": "object", "definitions": { - "telemetry": { - "$id": "#/definitions/telemetry", + "timestamp": { + "$id": "#/definitions/timestamp", + "type": "number", + "description": "Integer milliseconds since Unix epoch", + "multipleOf": 1.0, + "minimum": 1514764800000 + }, + "uuid": { + "$id": "#/definitions/uuid", + "type": "string", + "description": "A UUID used to uniquely identifty an object", + "default": "", + "examples": [ + "3c9604d6-b5ee-11e8-96f8-529269fb1459" + ], + "pattern": "^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$" + }, + "vehicle_telemetry": { + "$id": "#/definitions/vehicle_telemetry", "type": "object", - "description": "A vehicle telemetry datum", + "description": "A telemetry datum for a specific vehicle at a specific time", "required": [ "device_id", "timestamp", @@ -47,15 +64,15 @@ }, "heading": { "type": "number", - "description": "Degrees clockwise from true north" + "description": "Degrees - clockwise starting at 0 degrees at true North" }, "speed": { "type": "number", - "description": "Speed in meters/sec" + "description": "Estimated speed in meters / sec as reported by the GPS chipset" }, "accuracy": { "type": "number", - "description": "Accuracy in meters" + "description": "Horizontal accuracy, in meters" }, "hdop": { "type": "number", @@ -69,29 +86,12 @@ }, "charge": { "type": "number", - "description": "Fraction of charge of the vehicle (required if applicable", + "description": "Fraction of charge of the vehicle (required if applicable)", "minimum": 0, "maximum": 1 } } }, - "timestamp": { - "$id": "#/definitions/timestamp", - "type": "number", - "description": "Integer milliseconds since Unix epoch", - "multipleOf": 1.0, - "minimum": 1514764800000 - }, - "uuid": { - "$id": "#/definitions/uuid", - "type": "string", - "description": "A UUID used to uniquely identifty an object", - "default": "", - "examples": [ - "3c9604d6-b5ee-11e8-96f8-529269fb1459" - ], - "pattern": "^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$" - }, "vehicle_state": { "$id": "#/definitions/vehicle_state", "type": "string", @@ -167,7 +167,7 @@ "$ref": "#/definitions/timestamp" }, "telemetry": { - "$ref": "#/definitions/telemetry" + "$ref": "#/definitions/vehicle_telemetry" }, "trip_id": { "$ref": "#/definitions/uuid" diff --git a/agency/post_vehicle_telemetry.json b/agency/post_vehicle_telemetry.json index 8c2d3821..021c9d8e 100644 --- a/agency/post_vehicle_telemetry.json +++ b/agency/post_vehicle_telemetry.json @@ -4,10 +4,27 @@ "title": "The MDS Agency Schema, POST vehicle telemetry body", "type": "object", "definitions": { - "telemetry": { - "$id": "#/definitions/telemetry", + "timestamp": { + "$id": "#/definitions/timestamp", + "type": "number", + "description": "Integer milliseconds since Unix epoch", + "multipleOf": 1.0, + "minimum": 1514764800000 + }, + "uuid": { + "$id": "#/definitions/uuid", + "type": "string", + "description": "A UUID used to uniquely identifty an object", + "default": "", + "examples": [ + "3c9604d6-b5ee-11e8-96f8-529269fb1459" + ], + "pattern": "^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$" + }, + "vehicle_telemetry": { + "$id": "#/definitions/vehicle_telemetry", "type": "object", - "description": "A vehicle telemetry datum", + "description": "A telemetry datum for a specific vehicle at a specific time", "required": [ "device_id", "timestamp", @@ -47,15 +64,15 @@ }, "heading": { "type": "number", - "description": "Degrees clockwise from true north" + "description": "Degrees - clockwise starting at 0 degrees at true North" }, "speed": { "type": "number", - "description": "Speed in meters/sec" + "description": "Estimated speed in meters / sec as reported by the GPS chipset" }, "accuracy": { "type": "number", - "description": "Accuracy in meters" + "description": "Horizontal accuracy, in meters" }, "hdop": { "type": "number", @@ -69,28 +86,11 @@ }, "charge": { "type": "number", - "description": "Fraction of charge of the vehicle (required if applicable", + "description": "Fraction of charge of the vehicle (required if applicable)", "minimum": 0, "maximum": 1 } } - }, - "timestamp": { - "$id": "#/definitions/timestamp", - "type": "number", - "description": "Integer milliseconds since Unix epoch", - "multipleOf": 1.0, - "minimum": 1514764800000 - }, - "uuid": { - "$id": "#/definitions/uuid", - "type": "string", - "description": "A UUID used to uniquely identifty an object", - "default": "", - "examples": [ - "3c9604d6-b5ee-11e8-96f8-529269fb1459" - ], - "pattern": "^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$" } }, "required": [ @@ -100,7 +100,7 @@ "data": { "type": "array", "items": { - "$ref": "#/definitions/telemetry" + "$ref": "#/definitions/vehicle_telemetry" } } }, From 215d3adc68c4cd3ccdb1afe4386941bf4ccb6d96 Mon Sep 17 00:00:00 2001 From: Kegan Maher Date: Tue, 26 Oct 2021 08:44:29 -0700 Subject: [PATCH 28/81] update provider schemas with new telemetry defs --- provider/events.json | 106 +++++++++++++++++++++-------------- provider/status_changes.json | 106 +++++++++++++++++++++-------------- provider/stops.json | 106 +++++++++++++++++++++-------------- provider/trips.json | 106 +++++++++++++++++++++-------------- provider/vehicles.json | 106 +++++++++++++++++++++-------------- 5 files changed, 325 insertions(+), 205 deletions(-) diff --git a/provider/events.json b/provider/events.json index 6936f39d..150c16ed 100644 --- a/provider/events.json +++ b/provider/events.json @@ -41,47 +41,6 @@ ], "pattern": "^1\\.2\\.[0-9]+$" }, - "Point": { - "$id": "#/definitions/Point", - "title": "GeoJSON Point", - "type": "object", - "required": [ - "type", - "coordinates" - ], - "properties": { - "type": { - "type": "string", - "enum": [ - "Point" - ] - }, - "coordinates": { - "type": "array", - "minItems": 2, - "items": [ - { - "type": "number", - "minimum": -180.0, - "maximum": 180.0 - }, - { - "type": "number", - "minimum": -90.0, - "maximum": 90.0 - } - ], - "maxItems": 2 - }, - "bbox": { - "type": "array", - "minItems": 4, - "items": { - "type": "number" - } - } - } - }, "MDS_Feature_Point": { "$id": "#/definitions/MDS_Feature_Point", "title": "MDS GeoJSON Feature Point", @@ -119,6 +78,30 @@ }, "stop_id": { "$ref": "#/definitions/uuid" + }, + "altitude": { + "type": "number", + "description": "Altitude above mean sea level in meters" + }, + "heading": { + "type": "number", + "description": "Degrees - clockwise starting at 0 degrees at true North" + }, + "speed": { + "type": "number", + "description": "Estimated speed in meters / sec as reported by the GPS chipset" + }, + "accuracy": { + "type": "number", + "description": "Horizontal accuracy, in meters" + }, + "hdop": { + "type": "number", + "description": "Horizontal GPS or GNSS accuracy value" + }, + "satellites": { + "type": "integer", + "description": "Number of GPS or GNSS satellites" } } }, @@ -134,6 +117,47 @@ } } }, + "Point": { + "$id": "#/definitions/Point", + "title": "GeoJSON Point", + "type": "object", + "required": [ + "type", + "coordinates" + ], + "properties": { + "type": { + "type": "string", + "enum": [ + "Point" + ] + }, + "coordinates": { + "type": "array", + "minItems": 2, + "items": [ + { + "type": "number", + "minimum": -180.0, + "maximum": 180.0 + }, + { + "type": "number", + "minimum": -90.0, + "maximum": 90.0 + } + ], + "maxItems": 2 + }, + "bbox": { + "type": "array", + "minItems": 4, + "items": { + "type": "number" + } + } + } + }, "propulsion_type": { "$id": "#/definitions/propulsion_type", "type": "string", diff --git a/provider/status_changes.json b/provider/status_changes.json index 1248ae6b..c7ca6825 100644 --- a/provider/status_changes.json +++ b/provider/status_changes.json @@ -41,47 +41,6 @@ ], "pattern": "^1\\.2\\.[0-9]+$" }, - "Point": { - "$id": "#/definitions/Point", - "title": "GeoJSON Point", - "type": "object", - "required": [ - "type", - "coordinates" - ], - "properties": { - "type": { - "type": "string", - "enum": [ - "Point" - ] - }, - "coordinates": { - "type": "array", - "minItems": 2, - "items": [ - { - "type": "number", - "minimum": -180.0, - "maximum": 180.0 - }, - { - "type": "number", - "minimum": -90.0, - "maximum": 90.0 - } - ], - "maxItems": 2 - }, - "bbox": { - "type": "array", - "minItems": 4, - "items": { - "type": "number" - } - } - } - }, "MDS_Feature_Point": { "$id": "#/definitions/MDS_Feature_Point", "title": "MDS GeoJSON Feature Point", @@ -119,6 +78,30 @@ }, "stop_id": { "$ref": "#/definitions/uuid" + }, + "altitude": { + "type": "number", + "description": "Altitude above mean sea level in meters" + }, + "heading": { + "type": "number", + "description": "Degrees - clockwise starting at 0 degrees at true North" + }, + "speed": { + "type": "number", + "description": "Estimated speed in meters / sec as reported by the GPS chipset" + }, + "accuracy": { + "type": "number", + "description": "Horizontal accuracy, in meters" + }, + "hdop": { + "type": "number", + "description": "Horizontal GPS or GNSS accuracy value" + }, + "satellites": { + "type": "integer", + "description": "Number of GPS or GNSS satellites" } } }, @@ -134,6 +117,47 @@ } } }, + "Point": { + "$id": "#/definitions/Point", + "title": "GeoJSON Point", + "type": "object", + "required": [ + "type", + "coordinates" + ], + "properties": { + "type": { + "type": "string", + "enum": [ + "Point" + ] + }, + "coordinates": { + "type": "array", + "minItems": 2, + "items": [ + { + "type": "number", + "minimum": -180.0, + "maximum": 180.0 + }, + { + "type": "number", + "minimum": -90.0, + "maximum": 90.0 + } + ], + "maxItems": 2 + }, + "bbox": { + "type": "array", + "minItems": 4, + "items": { + "type": "number" + } + } + } + }, "propulsion_type": { "$id": "#/definitions/propulsion_type", "type": "string", diff --git a/provider/stops.json b/provider/stops.json index c4c56794..b0dbfbda 100644 --- a/provider/stops.json +++ b/provider/stops.json @@ -41,47 +41,6 @@ ], "pattern": "^1\\.2\\.[0-9]+$" }, - "Point": { - "$id": "#/definitions/Point", - "title": "GeoJSON Point", - "type": "object", - "required": [ - "type", - "coordinates" - ], - "properties": { - "type": { - "type": "string", - "enum": [ - "Point" - ] - }, - "coordinates": { - "type": "array", - "minItems": 2, - "items": [ - { - "type": "number", - "minimum": -180.0, - "maximum": 180.0 - }, - { - "type": "number", - "minimum": -90.0, - "maximum": 90.0 - } - ], - "maxItems": 2 - }, - "bbox": { - "type": "array", - "minItems": 4, - "items": { - "type": "number" - } - } - } - }, "MDS_Feature_Point": { "$id": "#/definitions/MDS_Feature_Point", "title": "MDS GeoJSON Feature Point", @@ -119,6 +78,30 @@ }, "stop_id": { "$ref": "#/definitions/uuid" + }, + "altitude": { + "type": "number", + "description": "Altitude above mean sea level in meters" + }, + "heading": { + "type": "number", + "description": "Degrees - clockwise starting at 0 degrees at true North" + }, + "speed": { + "type": "number", + "description": "Estimated speed in meters / sec as reported by the GPS chipset" + }, + "accuracy": { + "type": "number", + "description": "Horizontal accuracy, in meters" + }, + "hdop": { + "type": "number", + "description": "Horizontal GPS or GNSS accuracy value" + }, + "satellites": { + "type": "integer", + "description": "Number of GPS or GNSS satellites" } } }, @@ -134,6 +117,47 @@ } } }, + "Point": { + "$id": "#/definitions/Point", + "title": "GeoJSON Point", + "type": "object", + "required": [ + "type", + "coordinates" + ], + "properties": { + "type": { + "type": "string", + "enum": [ + "Point" + ] + }, + "coordinates": { + "type": "array", + "minItems": 2, + "items": [ + { + "type": "number", + "minimum": -180.0, + "maximum": 180.0 + }, + { + "type": "number", + "minimum": -90.0, + "maximum": 90.0 + } + ], + "maxItems": 2 + }, + "bbox": { + "type": "array", + "minItems": 4, + "items": { + "type": "number" + } + } + } + }, "ttl": { "$id": "#/definitions/ttl", "type": "integer", diff --git a/provider/trips.json b/provider/trips.json index a4a865cd..80768ad6 100644 --- a/provider/trips.json +++ b/provider/trips.json @@ -41,47 +41,6 @@ ], "pattern": "^1\\.2\\.[0-9]+$" }, - "Point": { - "$id": "#/definitions/Point", - "title": "GeoJSON Point", - "type": "object", - "required": [ - "type", - "coordinates" - ], - "properties": { - "type": { - "type": "string", - "enum": [ - "Point" - ] - }, - "coordinates": { - "type": "array", - "minItems": 2, - "items": [ - { - "type": "number", - "minimum": -180.0, - "maximum": 180.0 - }, - { - "type": "number", - "minimum": -90.0, - "maximum": 90.0 - } - ], - "maxItems": 2 - }, - "bbox": { - "type": "array", - "minItems": 4, - "items": { - "type": "number" - } - } - } - }, "MDS_Feature_Point": { "$id": "#/definitions/MDS_Feature_Point", "title": "MDS GeoJSON Feature Point", @@ -119,6 +78,30 @@ }, "stop_id": { "$ref": "#/definitions/uuid" + }, + "altitude": { + "type": "number", + "description": "Altitude above mean sea level in meters" + }, + "heading": { + "type": "number", + "description": "Degrees - clockwise starting at 0 degrees at true North" + }, + "speed": { + "type": "number", + "description": "Estimated speed in meters / sec as reported by the GPS chipset" + }, + "accuracy": { + "type": "number", + "description": "Horizontal accuracy, in meters" + }, + "hdop": { + "type": "number", + "description": "Horizontal GPS or GNSS accuracy value" + }, + "satellites": { + "type": "integer", + "description": "Number of GPS or GNSS satellites" } } }, @@ -134,6 +117,47 @@ } } }, + "Point": { + "$id": "#/definitions/Point", + "title": "GeoJSON Point", + "type": "object", + "required": [ + "type", + "coordinates" + ], + "properties": { + "type": { + "type": "string", + "enum": [ + "Point" + ] + }, + "coordinates": { + "type": "array", + "minItems": 2, + "items": [ + { + "type": "number", + "minimum": -180.0, + "maximum": 180.0 + }, + { + "type": "number", + "minimum": -90.0, + "maximum": 90.0 + } + ], + "maxItems": 2 + }, + "bbox": { + "type": "array", + "minItems": 4, + "items": { + "type": "number" + } + } + } + }, "currency": { "$id": "#/definitions/currency", "type": [ diff --git a/provider/vehicles.json b/provider/vehicles.json index ef7c4ec4..cd0208b7 100644 --- a/provider/vehicles.json +++ b/provider/vehicles.json @@ -41,47 +41,6 @@ ], "pattern": "^1\\.2\\.[0-9]+$" }, - "Point": { - "$id": "#/definitions/Point", - "title": "GeoJSON Point", - "type": "object", - "required": [ - "type", - "coordinates" - ], - "properties": { - "type": { - "type": "string", - "enum": [ - "Point" - ] - }, - "coordinates": { - "type": "array", - "minItems": 2, - "items": [ - { - "type": "number", - "minimum": -180.0, - "maximum": 180.0 - }, - { - "type": "number", - "minimum": -90.0, - "maximum": 90.0 - } - ], - "maxItems": 2 - }, - "bbox": { - "type": "array", - "minItems": 4, - "items": { - "type": "number" - } - } - } - }, "MDS_Feature_Point": { "$id": "#/definitions/MDS_Feature_Point", "title": "MDS GeoJSON Feature Point", @@ -119,6 +78,30 @@ }, "stop_id": { "$ref": "#/definitions/uuid" + }, + "altitude": { + "type": "number", + "description": "Altitude above mean sea level in meters" + }, + "heading": { + "type": "number", + "description": "Degrees - clockwise starting at 0 degrees at true North" + }, + "speed": { + "type": "number", + "description": "Estimated speed in meters / sec as reported by the GPS chipset" + }, + "accuracy": { + "type": "number", + "description": "Horizontal accuracy, in meters" + }, + "hdop": { + "type": "number", + "description": "Horizontal GPS or GNSS accuracy value" + }, + "satellites": { + "type": "integer", + "description": "Number of GPS or GNSS satellites" } } }, @@ -134,6 +117,47 @@ } } }, + "Point": { + "$id": "#/definitions/Point", + "title": "GeoJSON Point", + "type": "object", + "required": [ + "type", + "coordinates" + ], + "properties": { + "type": { + "type": "string", + "enum": [ + "Point" + ] + }, + "coordinates": { + "type": "array", + "minItems": 2, + "items": [ + { + "type": "number", + "minimum": -180.0, + "maximum": 180.0 + }, + { + "type": "number", + "minimum": -90.0, + "maximum": 90.0 + } + ], + "maxItems": 2 + }, + "bbox": { + "type": "array", + "minItems": 4, + "items": { + "type": "number" + } + } + } + }, "links": { "$id": "#/definitions/links", "type": "object", From 664d9c46fc8aa8fde349b1570afcf9755306b0bc Mon Sep 17 00:00:00 2001 From: Kegan Maher Date: Tue, 26 Oct 2021 10:27:16 -0700 Subject: [PATCH 29/81] add comms_restored event for the removed state --- schema/templates/common.json | 1 + 1 file changed, 1 insertion(+) diff --git a/schema/templates/common.json b/schema/templates/common.json index 141c077f..05c43d46 100644 --- a/schema/templates/common.json +++ b/schema/templates/common.json @@ -631,6 +631,7 @@ "contains": { "enum": [ "agency_pick_up", + "comms_restored", "compliance_pick_up", "decommissioned", "located", From 48d329e8f9ec81043aa46873a195b2ec994ecfa3 Mon Sep 17 00:00:00 2001 From: Kegan Maher Date: Tue, 26 Oct 2021 10:29:45 -0700 Subject: [PATCH 30/81] update agency schemas with removed:comms_restored --- agency/get_vehicle.json | 1 + agency/post_vehicle_event.json | 1 + 2 files changed, 2 insertions(+) diff --git a/agency/get_vehicle.json b/agency/get_vehicle.json index 2358166b..6bb2edfa 100644 --- a/agency/get_vehicle.json +++ b/agency/get_vehicle.json @@ -280,6 +280,7 @@ "contains": { "enum": [ "agency_pick_up", + "comms_restored", "compliance_pick_up", "decommissioned", "located", diff --git a/agency/post_vehicle_event.json b/agency/post_vehicle_event.json index 49d5eff9..d1ce7ff1 100644 --- a/agency/post_vehicle_event.json +++ b/agency/post_vehicle_event.json @@ -267,6 +267,7 @@ "contains": { "enum": [ "agency_pick_up", + "comms_restored", "compliance_pick_up", "decommissioned", "located", From 6f327e298669686d3168279df1249148994ea19e Mon Sep 17 00:00:00 2001 From: Kegan Maher Date: Tue, 26 Oct 2021 10:31:07 -0700 Subject: [PATCH 31/81] update provider schemas with removed:comms_restored --- provider/events.json | 1 + provider/vehicles.json | 1 + 2 files changed, 2 insertions(+) diff --git a/provider/events.json b/provider/events.json index 2312ba0b..c6fd5374 100644 --- a/provider/events.json +++ b/provider/events.json @@ -482,6 +482,7 @@ "contains": { "enum": [ "agency_pick_up", + "comms_restored", "compliance_pick_up", "decommissioned", "located", diff --git a/provider/vehicles.json b/provider/vehicles.json index 92d36da1..0fc327bb 100644 --- a/provider/vehicles.json +++ b/provider/vehicles.json @@ -496,6 +496,7 @@ "contains": { "enum": [ "agency_pick_up", + "comms_restored", "compliance_pick_up", "decommissioned", "located", From d2d7514d7fbab8083dfac67d05eb0b1ab8461c63 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Wed, 27 Oct 2021 11:13:10 -0400 Subject: [PATCH 32/81] Updated working group info --- README.md | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/README.md b/README.md index 5fd88a2d..62d2b576 100644 --- a/README.md +++ b/README.md @@ -92,12 +92,7 @@ The Mobility Data Specification is an open source project with all development t You can learn more about the polices, methodologies, and tools in the MDS ecosystem in the [Mobility Data Management State of Practice](https://github.com/openmobilityfoundation/privacy-committee/blob/main/products/state-of-the-practice.md) wiki. To help cities put the right privacy policies in place, the OMF [Privacy, Security, and Transparency Committee](https://github.com/openmobilityfoundation/privacy-committee) has created a comprehensive best-practices document called the [MDS Privacy Guide for Cities](https://github.com/openmobilityfoundation/governance/raw/main/documents/OMF-MDS-Privacy-Guide-for-Cities.pdf). -You can also get involved in development by joining an [OMF working group](https://github.com/openmobilityfoundation/mobility-data-specification/wiki#omf-meetings). The working groups maintain the OMF GitHub repositories and work through issues and pull requests. Each working group has its own mailing list for non-technical discussion and planning: - -Working Group | Mailing List | Description ---- | --- | --- -Provider Services | [mds-provider-services](https://groups.google.com/a/groups.openmobilityfoundation.org/forum/#!forum/mds-provider-services) | Manages the [`provider`][provider] API within MDS. -City Services | [mds-city-services](https://groups.google.com/a/groups.openmobilityfoundation.org/forum/#!forum/mds-city-services) | Manages the [`agency`][agency], [`policy`][policy], [`geography`][geography], [`jurisdiction`][jurisdiction], and [`metrics`](metrics) APIs within MDS, as well as the [`mds-core`](https://github.com/openmobilityfoundation/mds-core) and [`mds-compliance-mobile`](https://github.com/openmobilityfoundation/mds-compliance-mobile) reference implementations. +You can also get involved in development by joining the [MDS Working Group](https://github.com/openmobilityfoundation/mobility-data-specification/wiki/MDS-Working-Group). The working group maintains the OMF GitHub repositories and works through issues and pull requests. To receive relevant emails and calendar invites for meetings, please sign up for the [MDS Mailing List](https://groups.google.com/a/openmobilityfoundation.org/g/wg-mds). You can view info about current and past releases, the public OMF calendar, and review planning calls in the [wiki](https://github.com/openmobilityfoundation/mobility-data-specification/wiki). From afc1d7093ce0d594a3b01a0c695754d27cd23bbc Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Wed, 27 Oct 2021 11:30:50 -0400 Subject: [PATCH 33/81] Link to help on provider/agency IDs --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 62d2b576..15ad98b8 100644 --- a/README.md +++ b/README.md @@ -133,7 +133,7 @@ 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). +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). Find out how in our [Adding an Agency ID](https://github.com/openmobilityfoundation/mobility-data-specification/wiki/Adding-an-MDS-Agency-ID) help document. [Top][toc] @@ -143,7 +143,7 @@ Over two dozen mobility service providers (MSPs) around the world use MDS, allow - See our **[list of providers using MDS](https://www.openmobilityfoundation.org/mds-users/#mobility-providers-using-mds)**. For a table list with unique IDs, see the MDS [provider list](/providers.csv). -To add yourself to the provider list, 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). +To add yourself to the provider list, 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). Find out how in our [Adding an Provider ID](https://github.com/openmobilityfoundation/mobility-data-specification/wiki/Adding-an-MDS-Provider-ID) help document. [Top][toc] From 8b7154dc2d609ded37d5b127b5b1c7c789de2203 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Wed, 27 Oct 2021 21:52:02 -0400 Subject: [PATCH 34/81] Revised Membership section --- README.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 15ad98b8..3a80b9b6 100644 --- a/README.md +++ b/README.md @@ -100,7 +100,16 @@ For questions about MDS please contact by email at [info@openmobilityfoundation. ## Membership -OMF Members (public agencies and commercial companies) have additional participation opportunities with leadership roles on our [Board of Directors](https://www.openmobilityfoundation.org/about/), [Privacy, Security, and Transparency Committee](https://github.com/openmobilityfoundation/privacy-committee), [Technology Council](https://github.com/openmobilityfoundation/governance/wiki/Technology-Council), and [Strategy Committee](https://github.com/openmobilityfoundation/governance/wiki/Strategy-Committee), as well as the steering committees of all [Working Groups](https://github.com/openmobilityfoundation/mobility-data-specification/wiki#omf-meetings). +OMF Members (public agencies and commercial companies) have additional participation opportunities with leadership roles on our: + +- [Board of Directors](https://www.openmobilityfoundation.org/about/) +- [Privacy, Security, and Transparency Committee](https://github.com/openmobilityfoundation/privacy-committee) +- [Technology Council](https://github.com/openmobilityfoundation/governance/wiki/Technology-Council) +- [Strategy Committee](https://github.com/openmobilityfoundation/governance/wiki/Strategy-Committee) +- [Advisory Committee](https://github.com/openmobilityfoundation/governance/wiki/Advisory-Committee) +- Steering committees of all [Working Groups](https://github.com/openmobilityfoundation/mobility-data-specification/wiki#omf-meetings), currently: + - [MDS Working Group](https://github.com/openmobilityfoundation/mobility-data-specification/wiki/MDS-Working-Group) + - [Curb Working Group](https://github.com/openmobilityfoundation/curb-data-specification/wiki) Read about [how to become an OMF member](https://www.openmobilityfoundation.org/how-to-become-a-member/) and [contact us](https://mailchi.mp/openmobilityfoundation/membership) for more details. From 8d9babdc511432a3719055a503a4309564fd9ca0 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 28 Oct 2021 10:22:50 -0400 Subject: [PATCH 35/81] Added governance links --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 3a80b9b6..8f661892 100644 --- a/README.md +++ b/README.md @@ -100,7 +100,7 @@ For questions about MDS please contact by email at [info@openmobilityfoundation. ## Membership -OMF Members (public agencies and commercial companies) have additional participation opportunities with leadership roles on our: +OMF Members (public agencies and commercial companies) have additional participation opportunities with leadership roles within our OMF [governance](https://github.com/openmobilityfoundation/governance#omf-scope-of-work): - [Board of Directors](https://www.openmobilityfoundation.org/about/) - [Privacy, Security, and Transparency Committee](https://github.com/openmobilityfoundation/privacy-committee) @@ -111,7 +111,7 @@ OMF Members (public agencies and commercial companies) have additional participa - [MDS Working Group](https://github.com/openmobilityfoundation/mobility-data-specification/wiki/MDS-Working-Group) - [Curb Working Group](https://github.com/openmobilityfoundation/curb-data-specification/wiki) -Read about [how to become an OMF member](https://www.openmobilityfoundation.org/how-to-become-a-member/) and [contact us](https://mailchi.mp/openmobilityfoundation/membership) for more details. +Read about [how to become an OMF member](https://www.openmobilityfoundation.org/how-to-become-a-member/), [how to get involved and our governance model](https://www.openmobilityfoundation.org/how-to-get-involved-in-the-open-mobility-foundation/), and [contact us](https://mailchi.mp/openmobilityfoundation/membership) for more details. [Top][toc] From 8431486b0ecb1a9dcb67955dbe5a1831bec150ca Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 28 Oct 2021 11:02:13 -0400 Subject: [PATCH 36/81] Formatting on Policy endpoints --- policy/README.md | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/policy/README.md b/policy/README.md index 3bef1ff9..eb928f6e 100644 --- a/policy/README.md +++ b/policy/README.md @@ -118,9 +118,10 @@ Authorization is not required. An agency may decide to make this endpoint unauth ### Policies -Endpoint: `/policies/{id}` -Method: `GET` -`data` Payload: `{ "policies": [] }`, an array of objects with the structure [outlined below](#policy). +**Endpoint**: `/policies/{id}` +**Method**: `GET` +**Schema:** [`policy` schema](#policy) +**`data` Payload**: `{ "policies": [] }`, an array of objects with the structure [outlined below](#policy). #### Query Parameters @@ -140,9 +141,10 @@ Policies will be returned in order of effective date (see schema below), with pa **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). +**Endpoint**: `/geographies/{id}` +**Method**: `GET` +**Schema:** [`geography` schema](#geography) +**`data` Payload**: `{ geographies: [] }`, an array of GeoJSON `Feature` objects that follow the schema [outlined here](#geography) or in [Geography](/geography#general-information). #### Query Parameters @@ -154,10 +156,11 @@ Method: `GET` ### Requirements -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) +**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:** [`requirement` schema](#requirement) +**`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. From e3b5b41b9fac6a52bb1774384087e231138b6053 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 28 Oct 2021 11:03:53 -0400 Subject: [PATCH 37/81] Added beta feedback to Rates --- policy/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/policy/README.md b/policy/README.md index eb928f6e..b0c70f91 100644 --- a/policy/README.md +++ b/policy/README.md @@ -342,6 +342,8 @@ An individual `Rule` object is defined by the following fields: ### Rates Rate-related properties can currently be specified on `rate` and `time` Rules. Note: A future MDS version will likely support rates for `count` and `speed` rules, but their behavior is currently undefined. +**[Beta feature](/general-information.md#beta-features)**: *Yes (as of 1.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). From d278eac66dc94ce1ed0e63275d3fdcf52fcdb785 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 28 Oct 2021 11:13:03 -0400 Subject: [PATCH 38/81] Stops: beta feedback and schema link --- provider/README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/provider/README.md b/provider/README.md index 0e2520ff..f854b65e 100644 --- a/provider/README.md +++ b/provider/README.md @@ -345,7 +345,7 @@ The authenticated reports are monthly, historic flat files that may be pre-gener **Endpoint:** `/reports` **Method:** `GET` -**[Beta feature][beta]:** Yes (as of 1.1.0) +**[Beta feature][beta]:** Yes (as of 1.1.0). [Leave feedback](https://github.com/openmobilityfoundation/mobility-data-specification/issues/672) **Schema:** TBD when out of beta **`data` Filename:** monthly file named by year and month, e.g. `/reports/YYYY-MM.csv` **`data` Payload:** monthly CSV files with the following structure: @@ -530,7 +530,8 @@ In addition to the standard [Provider payload wrapper](#response-format), respon **Endpoint:** `/stops/:stop_id` **Method:** `GET` -**[Beta feature][beta]:** Yes (as of 1.0.0) +**[Beta feature][beta]:** Yes (as of 1.0.0). [Leave feedback](https://github.com/openmobilityfoundation/mobility-data-specification/issues/638) +**Schema:** [`stops` schema][stops-schema] **`data` Payload:** `{ "stops": [] }`, an array of [Stops][stops] In the case that a `stop_id` query parameter is specified, the `stops` array returned will only have one entry. In the case that no `stop_id` query parameter is specified, all stops will be returned. From 5fedd720a3db8355cd1227c1cd732f40b3fbb1eb Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 28 Oct 2021 11:16:24 -0400 Subject: [PATCH 39/81] Links to general policy schema --- policy/README.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/policy/README.md b/policy/README.md index b0c70f91..f227446a 100644 --- a/policy/README.md +++ b/policy/README.md @@ -120,7 +120,7 @@ Authorization is not required. An agency may decide to make this endpoint unauth **Endpoint**: `/policies/{id}` **Method**: `GET` -**Schema:** [`policy` schema](#policy) +**Schema:** [`policy` schema][json-schema] **`data` Payload**: `{ "policies": [] }`, an array of objects with the structure [outlined below](#policy). #### Query Parameters @@ -143,7 +143,7 @@ Policies will be returned in order of effective date (see schema below), with pa **Endpoint**: `/geographies/{id}` **Method**: `GET` -**Schema:** [`geography` schema](#geography) +**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 @@ -159,7 +159,7 @@ 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:** [`requirement` schema](#requirement) +**Schema:** TBD when out of beta **`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. @@ -704,6 +704,7 @@ You may also show which APIs, endpoints, and fields your agency is serving to pr [beta]: /general-information.md#beta [error-messages]: /general-information.md#error-messages [iana]: https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml +[json-schema]: #json-schema [muni-boundary]: ../provider/README.md#municipality-boundary [propulsion-types]: /general-information.md#propulsion-types [responses]: /general-information.md#responses From ad39b98e9b051aa456d097bf18cc68e4e92c237f Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 28 Oct 2021 11:18:13 -0400 Subject: [PATCH 40/81] Added beta feedback for Agency stops --- agency/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/agency/README.md b/agency/README.md index c2ec16d8..4f22cc93 100644 --- a/agency/README.md +++ b/agency/README.md @@ -265,7 +265,7 @@ The `/stops` endpoint allows an agency to register city-managed Stops, or a prov **Endpoint:** `/stops` **Method:** `POST` -**[Beta feature][beta]:** Yes (as of 1.0.0) +**[Beta feature][beta]:** Yes (as of 1.0.0). [Leave feedback](https://github.com/openmobilityfoundation/mobility-data-specification/issues/638) **Request Body**: An array of [Stops][stops] 201 Success Response: @@ -287,7 +287,7 @@ _No content returned on success._ **Endpoint:** `/stops` **Method:** `PUT` -**[Beta feature][beta]:** Yes (as of 1.0.0) +**[Beta feature][beta]:** Yes (as of 1.0.0). [Leave feedback](https://github.com/openmobilityfoundation/mobility-data-specification/issues/638) **Request Body**: An array of subsets of [Stop][stops] information, where the permitted subset fields are defined as: | Field | Required/Optional | Description | @@ -313,7 +313,7 @@ _No content returned if no vehicle matching `stop_id` is found._ **Endpoint:** `/stops/:stop_id` **Method:** `GET` -**[Beta feature][beta]:** Yes (as of 1.0.0) +**[Beta feature][beta]:** Yes (as of 1.0.0). [Leave feedback](https://github.com/openmobilityfoundation/mobility-data-specification/issues/638) **Payload:** `{ "stops": [] }`, an array of [Stops][stops] Path Params: From 6c55755dbc6a89569288a09fa40490a919531521 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 28 Oct 2021 11:19:38 -0400 Subject: [PATCH 41/81] Feedback link for GDEs --- general-information.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/general-information.md b/general-information.md index 65554531..275073b0 100644 --- a/general-information.md +++ b/general-information.md @@ -145,7 +145,7 @@ For the purposes of this specification, the intersection of two geographic datat ## Geography-Driven Events -**[Beta feature](/general-information.md#beta-features):** *Yes (as of 1.1.0)* +**[Beta feature](/general-information.md#beta-features):** *Yes (as of 1.1.0)*. [Leave feedback](https://github.com/openmobilityfoundation/mobility-data-specification/issues/670) 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. From e7ad29025f1c29651da692b4ba0bb8119a436cc0 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 28 Oct 2021 11:22:49 -0400 Subject: [PATCH 42/81] Added links to beta feedback --- general-information.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/general-information.md b/general-information.md index 275073b0..2be07aa2 100644 --- a/general-information.md +++ b/general-information.md @@ -35,11 +35,11 @@ This document contains specifications that are shared between the various MDS AP 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. -Despite this, MDS users are highly encouraged to use beta features. New features can only become proven and trusted through implementation, use, and the learning that comes with it. Users should be thoughtful about the role of beta features in their operations. Users of beta features are strongly encouraged to share their experiences, learnings, and challenges with the broader MDS community via GitHub issues or pull requests. This will inform the refinements that transform beta features into fully proven, stable parts of the specification. +Despite this, MDS users are highly encouraged to use beta features. New features can only become proven and trusted through implementation, use, and the learning that comes with it. Users should be thoughtful about the role of beta features in their operations. Users of beta features are strongly encouraged to share their experiences, learnings, and challenges with the broader MDS community via GitHub issues or pull requests. This will inform the refinements that transform beta features into fully proven, stable parts of the specification. You may leave feedback on the appropriate open [feedback issue](https://github.com/openmobilityfoundation/mobility-data-specification/issues?q=is%3Aissue+is%3Aopen+label%3Abeta) tagged with the `beta` label. Beta features may be suitable for enabling some new tools and analysis, but may not be appropriate for mission-critical applications or regulatory decisions where certainty and reliability are essential. In subsequent releases existing beta features may include breaking changes, even in a minor release. Note that [schemas](/schema) may not be defined for some beta features until they are promoted out of beta. -Working Groups and their Steering Committees are expected to review beta designated features with each release cycle and determine whether the feature has reached the level of stability and maturity needed to remove the beta designation. In a case where a beta feature fails to reach substantial adoption after an extended time, Working Group Steering Committees should discuss whether or not the feature should remain in the specification. +Working Groups and their Steering Committees are expected to review beta designated features and [feedback](https://github.com/openmobilityfoundation/mobility-data-specification/issues?q=is%3Aissue+is%3Aopen+label%3Abeta) with each release cycle and determine whether the feature has reached the level of stability and maturity needed to remove the beta designation. In a case where a beta feature fails to reach substantial adoption after an extended time, Working Group Steering Committees should discuss whether or not the feature should remain in the specification. [Top][toc] From af8107477a08bb2b332b9eaae5e9340fe035f07f Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 28 Oct 2021 11:24:20 -0400 Subject: [PATCH 43/81] Metrics beta feedback link --- metrics/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/metrics/README.md b/metrics/README.md index 9a4762b8..22e5d0cf 100644 --- a/metrics/README.md +++ b/metrics/README.md @@ -68,7 +68,7 @@ Metrics may be a supplement for other more granular MDS data, and may be used to ## Beta Feature -[Beta feature](https://github.com/openmobilityfoundation/mobility-data-specification/blob/feature-metrics/general-information.md#beta-features): Yes (as of 1.0.0) +**[Beta feature](https://github.com/openmobilityfoundation/mobility-data-specification/blob/feature-metrics/general-information.md#beta-features)**: _Yes (as of 1.0.0)_. [Leave feedback](https://github.com/openmobilityfoundation/mobility-data-specification/issues/671) The Metrics API and all of its endpoints are marked as a [beta feature](https://github.com/openmobilityfoundation/mobility-data-specification/blob/feature-metrics/general-information.md#beta-features). It has not been tested in real world scenarios, and may be adjusted in future releases. From fa29a0201166cb678ae3be67d6b4bee7a13eb690 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 28 Oct 2021 11:25:04 -0400 Subject: [PATCH 44/81] Jurisdiction beta feedback link --- jurisdiction/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/jurisdiction/README.md b/jurisdiction/README.md index 911c3f2f..5af04111 100644 --- a/jurisdiction/README.md +++ b/jurisdiction/README.md @@ -39,6 +39,8 @@ A jurisdiction is: The Jurisdictions API and all of its endpoints are marked as a [beta feature](https://github.com/openmobilityfoundation/mobility-data-specification/blob/feature-metrics/general-information.md#beta-features) starting in the 1.1.0 release. It has not been tested in real world scenarios, and may be adjusted in future releases. +**[Beta feature](https://github.com/openmobilityfoundation/mobility-data-specification/blob/feature-metrics/general-information.md#beta-features)**: _Yes (as of 1.1.0)_. [Leave feedback](https://github.com/openmobilityfoundation/mobility-data-specification/issues/673) + ## Use Cases ### 1. Defining boundaries and what the vehicle state `elsewhere` means From e0f0ca2cbe09a886862d57e7eb5c3d18377bbb72 Mon Sep 17 00:00:00 2001 From: Kegan Maher Date: Thu, 28 Oct 2021 13:03:40 -0700 Subject: [PATCH 45/81] single geography template and generator inline the reference to https://geojson.org/schema/FeatureCollection.json in the template since we use it directly --- schema/geography.py | 32 +++++++++ schema/templates/geography/geography.json | 86 +++++++++++++++++++++++ 2 files changed, 118 insertions(+) create mode 100644 schema/geography.py create mode 100644 schema/templates/geography/geography.json diff --git a/schema/geography.py b/schema/geography.py new file mode 100644 index 00000000..f796864b --- /dev/null +++ b/schema/geography.py @@ -0,0 +1,32 @@ +""" +Schema generators for Geography endpoints. +""" + +import json + +import common + + +def geography_schema(): + """ + Create the schema for the Geography endpoint. + """ + # load schema template and insert definitions + schema = common.load_json("./templates/geography/geography.json") + definitions = common.load_definitions( + "string", + "timestamp", + "uuid", + "version" + ) + definitions.update(common.load_definitions( + "timestamp", + "uuid_array", + allow_null=True + )) + schema["definitions"].update(definitions) + + # verify and return + return common.check_schema(schema) + + diff --git a/schema/templates/geography/geography.json b/schema/templates/geography/geography.json new file mode 100644 index 00000000..e5987bcc --- /dev/null +++ b/schema/templates/geography/geography.json @@ -0,0 +1,86 @@ +{ + "$id": "https://raw.githubusercontent.com/openmobilityfoundation/mobility-data-specification/main/geography/geography.json", + "$schema": "http://json-schema.org/draft-06/schema#", + "title": "The MDS Geography Schema", + "type": "object", + "definitions": { + "geography": { + "$id": "#/definitions/geography", + "type": "object", + "title": "The geography object schema", + "additionalProperties": false, + "required": [ + "name", + "geography_id", + "geography_json", + "published_date" + ], + "properties": { + "name": { + "$id": "#/definitions/geography/properties/name", + "$ref": "#/definitions/string", + "description": "Name of geography" + }, + "description": { + "$id": "#/definitions/geography/properties/description", + "$ref": "#/definitions/string", + "description": "Description of geography" + }, + "geography_type": { + "$id": "#/definitions/geography/properties/geography_type", + "type": "string", + "description": "The type of geography" + }, + "geography_id": { + "$id": "#/definitions/geography/properties/geography_id", + "$ref": "#/definitions/uuid", + "description": "Unique ID of geography" + }, + "geography_json": { + "$id": "#/definitions/geography/properties/geography_json", + "$ref": "https://geojson.org/schema/FeatureCollection.json", + "description": "The GeoJSON FeatureCollection that defines the geographical coordinates" + }, + "effective_date":{ + "$id": "#/definitions/geography/properties/effective_date", + "$ref": "#/definitions/null_timestamp", + "description": "The date at which a Geography is considered 'live'. Must be at or after published_date." + }, + "published_date": { + "$id": "#/definitions/geography/properties/published_date", + "$ref": "#/definitions/timestamp", + "description": "Timestamp at which the geography was published i.e. made immutable" + }, + "retire_date": { + "$id": "#/definitions/geography/properties/end_date", + "$ref": "#/definitions/null_timestamp", + "description": "Time that the geography is slated to retire. Once the retire date is passed, new policies can no longer reference it and old policies referencing it should be updated. Retired geographies should continue to be returned in the geographies list. Must be after effective_date." + }, + "prev_geographies": { + "$id": "#/definitions/geography/properties/prev_geographies", + "$ref": "#/definitions/null_uuid_array", + "description": "Unique IDs of prior geographies replaced by this one", + "uniqueItems": true + } + } + } + }, + "required": [ + "geography", + "version" + ], + "properties": { + "geography": { + "$id": "#/properties/geography", + "$ref": "#/definitions/geography", + "description": "The geography in this payload", + "additionalProperties": false + }, + "version": { + "$id": "#/properties/version", + "$ref": "#/definitions/version", + "description": "The version of MDS that the geography represents" + } + }, + "additionalProperties": false +} From 9a6eeecf79fdb9d3c55b520050f473cffe8bc8d8 Mon Sep 17 00:00:00 2001 From: Kegan Maher Date: Thu, 28 Oct 2021 13:10:20 -0700 Subject: [PATCH 46/81] geographies array template and generator reuses the single geography schema/definition --- schema/geography.py | 11 +++++++ schema/templates/geography/geographies.json | 35 +++++++++++++++++++++ 2 files changed, 46 insertions(+) create mode 100644 schema/templates/geography/geographies.json diff --git a/schema/geography.py b/schema/geography.py index f796864b..771e6ebe 100644 --- a/schema/geography.py +++ b/schema/geography.py @@ -30,3 +30,14 @@ def geography_schema(): return common.check_schema(schema) +def geographies_schema(): + """ + Create the schema for the Geographies endpoint. + """ + # load schema template and insert definitions from geography + geography = geography_schema() + schema = common.load_json("./templates/geography/geographies.json") + schema["definitions"].update(geography["definitions"]) + + return common.check_schema(schema) + diff --git a/schema/templates/geography/geographies.json b/schema/templates/geography/geographies.json new file mode 100644 index 00000000..13380181 --- /dev/null +++ b/schema/templates/geography/geographies.json @@ -0,0 +1,35 @@ +{ + "$id": "https://raw.githubusercontent.com/openmobilityfoundation/mobility-data-specification/main/geography/geographies.json", + "$schema": "http://json-schema.org/draft-06/schema#", + "title": "The MDS Geographies Schema", + "type": "object", + "definitions": { + }, + "required": [ + "geographies", + "updated", + "version" + ], + "properties": { + "geographies": { + "$id": "#/properties/geographies", + "type": "array", + "title": "The array of policy objects in this payload", + "items": { + "$id": "#/properties/geographies/items", + "$ref": "#/definitions/geography" + } + }, + "updated": { + "$id": "#/properties/updated", + "$ref": "#/definitions/timestamp", + "description": "The timestamp when geographies was last updated" + }, + "version": { + "$id": "#/properties/version", + "$ref": "#/definitions/version", + "description": "The version of MDS that the geographies represents" + } + }, + "additionalProperties": false +} From 1e75794432fccd283100c5c50fb6e4b02f86de17 Mon Sep 17 00:00:00 2001 From: Kegan Maher Date: Thu, 28 Oct 2021 13:12:35 -0700 Subject: [PATCH 47/81] generator dict and wrapper function following the same layout as other spec generators --- schema/geography.py | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/schema/geography.py b/schema/geography.py index 771e6ebe..125402fd 100644 --- a/schema/geography.py +++ b/schema/geography.py @@ -41,3 +41,31 @@ def geographies_schema(): return common.check_schema(schema) + +def schema_generators(): + """ + The dict of schema generators for Geography. + + The key is the name of the schema file/template file. + The value is the generator function, taking a dict of common definitions as an argument. + The generator function should return the complete, validated schema document as a dict. + """ + return { + "geography": geography_schema, + "geographies": geographies_schema + } + + +def write_schema_files(): + """ + Create each of the Geography endpoint schema files in the appropriate directory. + """ + print("\nStarting to generate Geography JSON Schemas...\n") + + for name, generator in schema_generators().items(): + schema = generator() + with open(f"../geography/{name}.json", "w") as schemafile: + schemafile.write(json.dumps(schema, indent=2)) + print(f"Wrote {name}.json") + + print("\nFinished generating Geography JSON Schemas") From a8ac00491e90ea7312dd8ff147218de4e2e829df Mon Sep 17 00:00:00 2001 From: Kegan Maher Date: Thu, 28 Oct 2021 13:13:48 -0700 Subject: [PATCH 48/81] expose geography in generate_schemas.py entrypoint --- schema/README.md | 4 ++-- schema/generate_schemas.py | 7 ++++++- 2 files changed, 8 insertions(+), 3 deletions(-) diff --git a/schema/README.md b/schema/README.md index ccb9b892..04200056 100644 --- a/schema/README.md +++ b/schema/README.md @@ -7,10 +7,10 @@ This directory contains the templates and code that _generate_ the official JSON At a command prompt within this `schema` directory run: ```bash -python generate_schemas.py [--agency] [--policy] [--provider] +python generate_schemas.py [--agency] [--geography] [--policy] [--provider] ``` -The optional flags `--agency`, `--policy`, and `--provider` can be used to specify which +The optional flags `--agency`, `--geography`, `--policy`, and `--provider` can be used to specify which set of schemas to generate. The default is to generate all schemas. ## Updating Schemas diff --git a/schema/generate_schemas.py b/schema/generate_schemas.py index cfe14285..01454588 100644 --- a/schema/generate_schemas.py +++ b/schema/generate_schemas.py @@ -2,12 +2,13 @@ Generate the JSON Schema documents for MDS endpoints. USAGE: - python generate_schemas.py [--agency] [--policy] [--provider] + python generate_schemas.py [--agency] [--geography] [--policy] [--provider] """ import sys import agency +import geography import policy import provider @@ -15,12 +16,16 @@ if __name__ == "__main__": if len(sys.argv) == 1: agency.write_schema_files() + geography.write_schema_files() policy.write_schema_files() provider.write_schema_files() else: if "--agency" in sys.argv: agency.write_schema_files() sys.argv.remove("--agency") + if "--geography" in sys.argv: + geography.write_schema_files() + sys.argv.remove("--geography") if "--policy" in sys.argv: policy.write_schema_files() sys.argv.remove("--policy") From aed2e578094c633613dda95de331b4ff7a0f033f Mon Sep 17 00:00:00 2001 From: Kegan Maher Date: Thu, 28 Oct 2021 13:17:25 -0700 Subject: [PATCH 49/81] generate the single geography schema document --- geography/geography.json | 154 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 154 insertions(+) create mode 100644 geography/geography.json diff --git a/geography/geography.json b/geography/geography.json new file mode 100644 index 00000000..661263f8 --- /dev/null +++ b/geography/geography.json @@ -0,0 +1,154 @@ +{ + "$id": "https://raw.githubusercontent.com/openmobilityfoundation/mobility-data-specification/main/geography/geography.json", + "$schema": "http://json-schema.org/draft-06/schema#", + "title": "The MDS Geography Schema", + "type": "object", + "definitions": { + "geography": { + "$id": "#/definitions/geography", + "type": "object", + "title": "The geography object schema", + "additionalProperties": false, + "required": [ + "name", + "geography_id", + "geography_json", + "published_date" + ], + "properties": { + "name": { + "$id": "#/definitions/geography/properties/name", + "$ref": "#/definitions/string", + "description": "Name of geography" + }, + "description": { + "$id": "#/definitions/geography/properties/description", + "$ref": "#/definitions/string", + "description": "Description of geography" + }, + "geography_type": { + "$id": "#/definitions/geography/properties/geography_type", + "type": "string", + "description": "The type of geography" + }, + "geography_id": { + "$id": "#/definitions/geography/properties/geography_id", + "$ref": "#/definitions/uuid", + "description": "Unique ID of geography" + }, + "geography_json": { + "$id": "#/definitions/geography/properties/geography_json", + "$ref": "https://geojson.org/schema/FeatureCollection.json", + "description": "The GeoJSON FeatureCollection that defines the geographical coordinates" + }, + "effective_date": { + "$id": "#/definitions/geography/properties/effective_date", + "$ref": "#/definitions/null_timestamp", + "description": "The date at which a Geography is considered 'live'. Must be at or after published_date." + }, + "published_date": { + "$id": "#/definitions/geography/properties/published_date", + "$ref": "#/definitions/timestamp", + "description": "Timestamp at which the geography was published i.e. made immutable" + }, + "retire_date": { + "$id": "#/definitions/geography/properties/end_date", + "$ref": "#/definitions/null_timestamp", + "description": "Time that the geography is slated to retire. Once the retire date is passed, new policies can no longer reference it and old policies referencing it should be updated. Retired geographies should continue to be returned in the geographies list. Must be after effective_date." + }, + "prev_geographies": { + "$id": "#/definitions/geography/properties/prev_geographies", + "$ref": "#/definitions/null_uuid_array", + "description": "Unique IDs of prior geographies replaced by this one", + "uniqueItems": true + } + } + }, + "string": { + "$id": "#/definitions/string", + "type": "string", + "description": "A length-limited string type", + "maxLength": 255, + "default": "", + "examples": [ + "ABC123" + ], + "pattern": "^(.*)$" + }, + "timestamp": { + "$id": "#/definitions/timestamp", + "type": "number", + "description": "Integer milliseconds since Unix epoch", + "multipleOf": 1.0, + "minimum": 1514764800000 + }, + "uuid": { + "$id": "#/definitions/uuid", + "type": "string", + "description": "A UUID used to uniquely identifty an object", + "default": "", + "examples": [ + "3c9604d6-b5ee-11e8-96f8-529269fb1459" + ], + "pattern": "^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$" + }, + "version": { + "$id": "#/definitions/version", + "type": "string", + "description": "The version of MDS this data represents", + "examples": [ + "1.2.0" + ], + "pattern": "^1\\.2\\.[0-9]+$" + }, + "uuid_array": { + "$id": "#/definitions/uuid_array", + "type": "array", + "description": "Array of UUID", + "items": { + "$id": "#/definitions/uuid_array/items", + "$ref": "#/definitions/uuid" + } + }, + "null_timestamp": { + "$id": "#/definitions/null_timestamp", + "type": [ + "number", + "null" + ], + "description": "Integer milliseconds since Unix epoch", + "multipleOf": 1.0, + "minimum": 1514764800000 + }, + "null_uuid_array": { + "$id": "#/definitions/null_uuid_array", + "type": [ + "array", + "null" + ], + "description": "Array of UUID", + "items": { + "$id": "#/definitions/uuid_array/items", + "$ref": "#/definitions/uuid" + } + } + }, + "required": [ + "geography", + "version" + ], + "properties": { + "geography": { + "$id": "#/properties/geography", + "$ref": "#/definitions/geography", + "description": "The geography in this payload", + "additionalProperties": false + }, + "version": { + "$id": "#/properties/version", + "$ref": "#/definitions/version", + "description": "The version of MDS that the geography represents" + } + }, + "additionalProperties": false +} \ No newline at end of file From 0fe9bd59728cd44ada6f1795c80a457f9fa915ea Mon Sep 17 00:00:00 2001 From: Kegan Maher Date: Thu, 28 Oct 2021 13:18:09 -0700 Subject: [PATCH 50/81] generate the geographies array schema document --- geography/geographies.json | 163 +++++++++++++++++++++++++++++++++++++ 1 file changed, 163 insertions(+) create mode 100644 geography/geographies.json diff --git a/geography/geographies.json b/geography/geographies.json new file mode 100644 index 00000000..d1ebbc76 --- /dev/null +++ b/geography/geographies.json @@ -0,0 +1,163 @@ +{ + "$id": "https://raw.githubusercontent.com/openmobilityfoundation/mobility-data-specification/main/geography/geographies.json", + "$schema": "http://json-schema.org/draft-06/schema#", + "title": "The MDS Geographies Schema", + "type": "object", + "definitions": { + "geography": { + "$id": "#/definitions/geography", + "type": "object", + "title": "The geography object schema", + "additionalProperties": false, + "required": [ + "name", + "geography_id", + "geography_json", + "published_date" + ], + "properties": { + "name": { + "$id": "#/definitions/geography/properties/name", + "$ref": "#/definitions/string", + "description": "Name of geography" + }, + "description": { + "$id": "#/definitions/geography/properties/description", + "$ref": "#/definitions/string", + "description": "Description of geography" + }, + "geography_type": { + "$id": "#/definitions/geography/properties/geography_type", + "type": "string", + "description": "The type of geography" + }, + "geography_id": { + "$id": "#/definitions/geography/properties/geography_id", + "$ref": "#/definitions/uuid", + "description": "Unique ID of geography" + }, + "geography_json": { + "$id": "#/definitions/geography/properties/geography_json", + "$ref": "https://geojson.org/schema/FeatureCollection.json", + "description": "The GeoJSON FeatureCollection that defines the geographical coordinates" + }, + "effective_date": { + "$id": "#/definitions/geography/properties/effective_date", + "$ref": "#/definitions/null_timestamp", + "description": "The date at which a Geography is considered 'live'. Must be at or after published_date." + }, + "published_date": { + "$id": "#/definitions/geography/properties/published_date", + "$ref": "#/definitions/timestamp", + "description": "Timestamp at which the geography was published i.e. made immutable" + }, + "retire_date": { + "$id": "#/definitions/geography/properties/end_date", + "$ref": "#/definitions/null_timestamp", + "description": "Time that the geography is slated to retire. Once the retire date is passed, new policies can no longer reference it and old policies referencing it should be updated. Retired geographies should continue to be returned in the geographies list. Must be after effective_date." + }, + "prev_geographies": { + "$id": "#/definitions/geography/properties/prev_geographies", + "$ref": "#/definitions/null_uuid_array", + "description": "Unique IDs of prior geographies replaced by this one", + "uniqueItems": true + } + } + }, + "string": { + "$id": "#/definitions/string", + "type": "string", + "description": "A length-limited string type", + "maxLength": 255, + "default": "", + "examples": [ + "ABC123" + ], + "pattern": "^(.*)$" + }, + "timestamp": { + "$id": "#/definitions/timestamp", + "type": "number", + "description": "Integer milliseconds since Unix epoch", + "multipleOf": 1.0, + "minimum": 1514764800000 + }, + "uuid": { + "$id": "#/definitions/uuid", + "type": "string", + "description": "A UUID used to uniquely identifty an object", + "default": "", + "examples": [ + "3c9604d6-b5ee-11e8-96f8-529269fb1459" + ], + "pattern": "^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$" + }, + "version": { + "$id": "#/definitions/version", + "type": "string", + "description": "The version of MDS this data represents", + "examples": [ + "1.2.0" + ], + "pattern": "^1\\.2\\.[0-9]+$" + }, + "uuid_array": { + "$id": "#/definitions/uuid_array", + "type": "array", + "description": "Array of UUID", + "items": { + "$id": "#/definitions/uuid_array/items", + "$ref": "#/definitions/uuid" + } + }, + "null_timestamp": { + "$id": "#/definitions/null_timestamp", + "type": [ + "number", + "null" + ], + "description": "Integer milliseconds since Unix epoch", + "multipleOf": 1.0, + "minimum": 1514764800000 + }, + "null_uuid_array": { + "$id": "#/definitions/null_uuid_array", + "type": [ + "array", + "null" + ], + "description": "Array of UUID", + "items": { + "$id": "#/definitions/uuid_array/items", + "$ref": "#/definitions/uuid" + } + } + }, + "required": [ + "geographies", + "updated", + "version" + ], + "properties": { + "geographies": { + "$id": "#/properties/geographies", + "type": "array", + "title": "The array of policy objects in this payload", + "items": { + "$id": "#/properties/geographies/items", + "$ref": "#/definitions/geography" + } + }, + "updated": { + "$id": "#/properties/updated", + "$ref": "#/definitions/timestamp", + "description": "The timestamp when geographies was last updated" + }, + "version": { + "$id": "#/properties/version", + "$ref": "#/definitions/version", + "description": "The version of MDS that the geographies represents" + } + }, + "additionalProperties": false +} \ No newline at end of file From b4e8b40ff70321c67905dd59da3f44f7477a269c Mon Sep 17 00:00:00 2001 From: Kegan Maher Date: Thu, 28 Oct 2021 13:32:45 -0700 Subject: [PATCH 51/81] add links to new schema documents --- geography/README.md | 20 +++++++------------- 1 file changed, 7 insertions(+), 13 deletions(-) diff --git a/geography/README.md b/geography/README.md index a3b14f12..eecdb0cb 100644 --- a/geography/README.md +++ b/geography/README.md @@ -89,7 +89,7 @@ Authorization is not required. An agency may decide to make this endpoint unauth ## Schema -Link to schema will be defined and added in a future release. +See the [Endpoints](#endpoints) below for links to their specific JSON Schema documents. [Top][toc] @@ -173,9 +173,9 @@ The Geography Author API consists of the following endpoints: ### Geography -**Endpoint**: `/geographies/{geography_id}` - -**Method**: `GET` +**Endpoint**: `/geographies/{geography_id}` +**Method**: `GET` +**Schema:** [`geography` schema](./geography.json) Path Params: @@ -213,15 +213,9 @@ Response codes: ### Geographies -**Endpoint**: `/geographies` - -**Method**: `GET` - -Path Params: - -| Name | Type | Required/Optional | Description | -| ------------ | --------- | --- | ---------------------------------------------- | -| `summary` | string | Optional | Return geographies, including the GeoJSON in each geography object | +**Endpoint**: `/geographies` +**Method**: `GET` +**Schema:** [`geographies` schema](./geographies.json) Returns: All geography objects From 107e349359e43fd9ac19fb54aab66f74c5667636 Mon Sep 17 00:00:00 2001 From: Kegan Maher Date: Thu, 28 Oct 2021 13:33:21 -0700 Subject: [PATCH 52/81] remove old schema document this seemed to be an example/sketch, and wasn't linked to from anywhere else --- geography/get_geography.json | 1038 ---------------------------------- 1 file changed, 1038 deletions(-) delete mode 100644 geography/get_geography.json diff --git a/geography/get_geography.json b/geography/get_geography.json deleted file mode 100644 index 83a5e2f6..00000000 --- a/geography/get_geography.json +++ /dev/null @@ -1,1038 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "title": "The MDS Geography Author Schema, GET /geographies/{id} payload", - "definitions": { - "GeoJSON.Feature": { - "description": "A feature object which contains a geometry and associated properties.\nhttps://tools.ietf.org/html/rfc7946#section-3.2", - "properties": { - "bbox": { - "anyOf": [ - { - "additionalItems": { - "anyOf": [ - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - } - ] - }, - "items": [ - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - } - ], - "minItems": 4, - "type": "array" - }, - { - "additionalItems": { - "anyOf": [ - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - } - ] - }, - "items": [ - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - } - ], - "minItems": 6, - "type": "array" - } - ], - "description": "Bounding box of the coordinate range of the object's Geometries, Features, or Feature Collections.\nThe value of the bbox member is an array of length 2*n where n is the number of dimensions\nrepresented in the contained geometries, with all axes of the most southwesterly point\nfollowed by all axes of the more northeasterly point.\nThe axes order of a bbox follows the axes order of geometries.\nhttps://tools.ietf.org/html/rfc7946#section-5" - }, - "geometry": { - "anyOf": [ - { - "$ref": "#/definitions/GeoJSON.Point" - }, - { - "$ref": "#/definitions/GeoJSON.MultiPoint" - }, - { - "$ref": "#/definitions/GeoJSON.LineString" - }, - { - "$ref": "#/definitions/GeoJSON.MultiLineString" - }, - { - "$ref": "#/definitions/GeoJSON.Polygon" - }, - { - "$ref": "#/definitions/GeoJSON.MultiPolygon" - }, - { - "$ref": "#/definitions/GeoJSON.GeometryCollection" - } - ], - "description": "The feature's geometry" - }, - "id": { - "description": "A value that uniquely identifies this feature in a\nhttps://tools.ietf.org/html/rfc7946#section-3.2.", - "type": [ - "string", - "number" - ] - }, - "properties": { - "additionalProperties": {}, - "description": "Properties associated with this feature.", - "type": "object" - }, - "type": { - "description": "Specifies the type of GeoJSON object.", - "enum": [ - "Feature" - ], - "type": "string" - } - }, - "type": "object" - }, - "GeoJSON.FeatureCollection": { - "description": "A collection of feature objects.\n https://tools.ietf.org/html/rfc7946#section-3.3", - "properties": { - "bbox": { - "anyOf": [ - { - "additionalItems": { - "anyOf": [ - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - } - ] - }, - "items": [ - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - } - ], - "minItems": 4, - "type": "array" - }, - { - "additionalItems": { - "anyOf": [ - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - } - ] - }, - "items": [ - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - } - ], - "minItems": 6, - "type": "array" - } - ], - "description": "Bounding box of the coordinate range of the object's Geometries, Features, or Feature Collections.\nThe value of the bbox member is an array of length 2*n where n is the number of dimensions\nrepresented in the contained geometries, with all axes of the most southwesterly point\nfollowed by all axes of the more northeasterly point.\nThe axes order of a bbox follows the axes order of geometries.\nhttps://tools.ietf.org/html/rfc7946#section-5" - }, - "features": { - "items": { - "$ref": "#/definitions/GeoJSON.Feature" - }, - "type": "array" - }, - "type": { - "description": "Specifies the type of GeoJSON object.", - "enum": [ - "FeatureCollection" - ], - "type": "string" - } - }, - "type": "object" - }, - "GeoJSON.GeometryCollection": { - "description": "Geometry Collection\nhttps://tools.ietf.org/html/rfc7946#section-3.1.8", - "properties": { - "bbox": { - "anyOf": [ - { - "additionalItems": { - "anyOf": [ - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - } - ] - }, - "items": [ - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - } - ], - "minItems": 4, - "type": "array" - }, - { - "additionalItems": { - "anyOf": [ - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - } - ] - }, - "items": [ - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - } - ], - "minItems": 6, - "type": "array" - } - ], - "description": "Bounding box of the coordinate range of the object's Geometries, Features, or Feature Collections.\nThe value of the bbox member is an array of length 2*n where n is the number of dimensions\nrepresented in the contained geometries, with all axes of the most southwesterly point\nfollowed by all axes of the more northeasterly point.\nThe axes order of a bbox follows the axes order of geometries.\nhttps://tools.ietf.org/html/rfc7946#section-5" - }, - "geometries": { - "items": { - "anyOf": [ - { - "$ref": "#/definitions/GeoJSON.Point" - }, - { - "$ref": "#/definitions/GeoJSON.MultiPoint" - }, - { - "$ref": "#/definitions/GeoJSON.LineString" - }, - { - "$ref": "#/definitions/GeoJSON.MultiLineString" - }, - { - "$ref": "#/definitions/GeoJSON.Polygon" - }, - { - "$ref": "#/definitions/GeoJSON.MultiPolygon" - }, - { - "$ref": "#/definitions/GeoJSON.GeometryCollection" - } - ] - }, - "type": "array" - }, - "type": { - "description": "Specifies the type of GeoJSON object.", - "enum": [ - "GeometryCollection" - ], - "type": "string" - } - }, - "type": "object" - }, - "GeoJSON.LineString": { - "description": "LineString geometry object.\nhttps://tools.ietf.org/html/rfc7946#section-3.1.4", - "properties": { - "bbox": { - "anyOf": [ - { - "additionalItems": { - "anyOf": [ - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - } - ] - }, - "items": [ - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - } - ], - "minItems": 4, - "type": "array" - }, - { - "additionalItems": { - "anyOf": [ - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - } - ] - }, - "items": [ - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - } - ], - "minItems": 6, - "type": "array" - } - ], - "description": "Bounding box of the coordinate range of the object's Geometries, Features, or Feature Collections.\nThe value of the bbox member is an array of length 2*n where n is the number of dimensions\nrepresented in the contained geometries, with all axes of the most southwesterly point\nfollowed by all axes of the more northeasterly point.\nThe axes order of a bbox follows the axes order of geometries.\nhttps://tools.ietf.org/html/rfc7946#section-5" - }, - "coordinates": { - "items": { - "items": { - "type": "number" - }, - "type": "array" - }, - "type": "array" - }, - "type": { - "description": "Specifies the type of GeoJSON object.", - "enum": [ - "LineString" - ], - "type": "string" - } - }, - "type": "object" - }, - "GeoJSON.MultiLineString": { - "description": "MultiLineString geometry object.\nhttps://tools.ietf.org/html/rfc7946#section-3.1.5", - "properties": { - "bbox": { - "anyOf": [ - { - "additionalItems": { - "anyOf": [ - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - } - ] - }, - "items": [ - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - } - ], - "minItems": 4, - "type": "array" - }, - { - "additionalItems": { - "anyOf": [ - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - } - ] - }, - "items": [ - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - } - ], - "minItems": 6, - "type": "array" - } - ], - "description": "Bounding box of the coordinate range of the object's Geometries, Features, or Feature Collections.\nThe value of the bbox member is an array of length 2*n where n is the number of dimensions\nrepresented in the contained geometries, with all axes of the most southwesterly point\nfollowed by all axes of the more northeasterly point.\nThe axes order of a bbox follows the axes order of geometries.\nhttps://tools.ietf.org/html/rfc7946#section-5" - }, - "coordinates": { - "items": { - "items": { - "items": { - "type": "number" - }, - "type": "array" - }, - "type": "array" - }, - "type": "array" - }, - "type": { - "description": "Specifies the type of GeoJSON object.", - "enum": [ - "MultiLineString" - ], - "type": "string" - } - }, - "type": "object" - }, - "GeoJSON.MultiPoint": { - "description": "MultiPoint geometry object.\n https://tools.ietf.org/html/rfc7946#section-3.1.3", - "properties": { - "bbox": { - "anyOf": [ - { - "additionalItems": { - "anyOf": [ - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - } - ] - }, - "items": [ - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - } - ], - "minItems": 4, - "type": "array" - }, - { - "additionalItems": { - "anyOf": [ - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - } - ] - }, - "items": [ - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - } - ], - "minItems": 6, - "type": "array" - } - ], - "description": "Bounding box of the coordinate range of the object's Geometries, Features, or Feature Collections.\nThe value of the bbox member is an array of length 2*n where n is the number of dimensions\nrepresented in the contained geometries, with all axes of the most southwesterly point\nfollowed by all axes of the more northeasterly point.\nThe axes order of a bbox follows the axes order of geometries.\nhttps://tools.ietf.org/html/rfc7946#section-5" - }, - "coordinates": { - "items": { - "items": { - "type": "number" - }, - "type": "array" - }, - "type": "array" - }, - "type": { - "description": "Specifies the type of GeoJSON object.", - "enum": [ - "MultiPoint" - ], - "type": "string" - } - }, - "type": "object" - }, - "GeoJSON.MultiPolygon": { - "description": "MultiPolygon geometry object.\nhttps://tools.ietf.org/html/rfc7946#section-3.1.7", - "properties": { - "bbox": { - "anyOf": [ - { - "additionalItems": { - "anyOf": [ - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - } - ] - }, - "items": [ - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - } - ], - "minItems": 4, - "type": "array" - }, - { - "additionalItems": { - "anyOf": [ - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - } - ] - }, - "items": [ - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - } - ], - "minItems": 6, - "type": "array" - } - ], - "description": "Bounding box of the coordinate range of the object's Geometries, Features, or Feature Collections.\nThe value of the bbox member is an array of length 2*n where n is the number of dimensions\nrepresented in the contained geometries, with all axes of the most southwesterly point\nfollowed by all axes of the more northeasterly point.\nThe axes order of a bbox follows the axes order of geometries.\nhttps://tools.ietf.org/html/rfc7946#section-5" - }, - "coordinates": { - "items": { - "items": { - "items": { - "items": { - "type": "number" - }, - "type": "array" - }, - "type": "array" - }, - "type": "array" - }, - "type": "array" - }, - "type": { - "description": "Specifies the type of GeoJSON object.", - "enum": [ - "MultiPolygon" - ], - "type": "string" - } - }, - "type": "object" - }, - "GeoJSON.Point": { - "description": "Point geometry object.\nhttps://tools.ietf.org/html/rfc7946#section-3.1.2", - "properties": { - "bbox": { - "anyOf": [ - { - "additionalItems": { - "anyOf": [ - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - } - ] - }, - "items": [ - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - } - ], - "minItems": 4, - "type": "array" - }, - { - "additionalItems": { - "anyOf": [ - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - } - ] - }, - "items": [ - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - } - ], - "minItems": 6, - "type": "array" - } - ], - "description": "Bounding box of the coordinate range of the object's Geometries, Features, or Feature Collections.\nThe value of the bbox member is an array of length 2*n where n is the number of dimensions\nrepresented in the contained geometries, with all axes of the most southwesterly point\nfollowed by all axes of the more northeasterly point.\nThe axes order of a bbox follows the axes order of geometries.\nhttps://tools.ietf.org/html/rfc7946#section-5" - }, - "coordinates": { - "description": "A Position is an array of coordinates.\nhttps://tools.ietf.org/html/rfc7946#section-3.1.1\nArray should contain between two and three elements.\nThe previous GeoJSON specification allowed more elements (e.g., which could be used to represent M values),\nbut the current specification only allows X, Y, and (optionally) Z to be defined.", - "items": { - "type": "number" - }, - "type": "array" - }, - "type": { - "description": "Specifies the type of GeoJSON object.", - "enum": [ - "Point" - ], - "type": "string" - } - }, - "type": "object" - }, - "GeoJSON.Polygon": { - "description": "Polygon geometry object.\nhttps://tools.ietf.org/html/rfc7946#section-3.1.6", - "properties": { - "bbox": { - "anyOf": [ - { - "additionalItems": { - "anyOf": [ - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - } - ] - }, - "items": [ - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - } - ], - "minItems": 4, - "type": "array" - }, - { - "additionalItems": { - "anyOf": [ - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - } - ] - }, - "items": [ - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - }, - { - "type": "number" - } - ], - "minItems": 6, - "type": "array" - } - ], - "description": "Bounding box of the coordinate range of the object's Geometries, Features, or Feature Collections.\nThe value of the bbox member is an array of length 2*n where n is the number of dimensions\nrepresented in the contained geometries, with all axes of the most southwesterly point\nfollowed by all axes of the more northeasterly point.\nThe axes order of a bbox follows the axes order of geometries.\nhttps://tools.ietf.org/html/rfc7946#section-5" - }, - "coordinates": { - "items": { - "items": { - "items": { - "type": "number" - }, - "type": "array" - }, - "type": "array" - }, - "type": "array" - }, - "type": { - "description": "Specifies the type of GeoJSON object.", - "enum": [ - "Polygon" - ], - "type": "string" - } - }, - "type": "object" - } - }, - "properties": { - "geography_id": { - "examples": [ - "3c9604d6-b5ee-11e8-96f8-529269fb1459" - ], - "format": "uuid", - "pattern": "^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$", - "type": "string" - }, - "geography_json": { - "$ref": "#/definitions/GeoJSON.FeatureCollection" - } - }, - "type": "object" -} From 82180e9137493282641cbb4b74fd8d1b019f38a7 Mon Sep 17 00:00:00 2001 From: Kegan Maher Date: Thu, 28 Oct 2021 13:34:14 -0700 Subject: [PATCH 53/81] formatting/markdown cleanup --- geography/README.md | 52 +++++++++++++++++++++++++-------------------- 1 file changed, 29 insertions(+), 23 deletions(-) diff --git a/geography/README.md b/geography/README.md index eecdb0cb..1b57176d 100644 --- a/geography/README.md +++ b/geography/README.md @@ -11,12 +11,12 @@ Geographical data will be stored as GeoJSON and read from either `geographies.js ## Table of Contents * [General Information](#general-information) - * [Versioning](#versioning) - * [Transition from Policy](#transition-from-policy) + * [Versioning](#versioning) + * [Transition from Policy](#transition-from-policy) * [Distribution](#distribution) - * [Flat Files](#flat-files) - * [Response Format](#response-format) - * [Authorization](#authorization) + * [Flat Files](#flat-files) + * [Response Format](#response-format) + * [Authorization](#authorization) * [Schema](#schema) * [Geography Fields](#geography-fields) * [Previous Geographies](#previous-geographies) @@ -45,7 +45,7 @@ Versioning must be implemented as specified in the [Versioning section][versioni 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. +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] @@ -65,7 +65,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` The files shall be structured like the output of the [REST endpoints](#rest-endpoints) above. @@ -115,6 +115,8 @@ Obsoleting or otherwise changing a geography is accomplished by publishing a new This field is optional can be omitted by the publishing Agency. +[Top][toc] + ### Geography Type Type of geography. These specific types are recommendations based on ones commonly defined by agencies. Others may be created by the Agency as needed, or the optional `geography_type` field may be omitted. @@ -148,16 +150,17 @@ Type of geography. These specific types are recommendations based on ones common Note: to use flat files rather than REST endpoints, Geography objects should be stored in `geographies.json`. The `geographies.json` file will look like the output of `GET /geographies`. Example `geographies.json` -```json + +```jsonc { - "version": "1.1.0", + "version": "1.2.0", "updated": "1570035222868", "geographies": [ { - // GeoJSON 1 + // Geography 1 }, { - // GeoJSON 2 + // Geography 2 } ] } @@ -177,22 +180,22 @@ The Geography Author API consists of the following endpoints: **Method**: `GET` **Schema:** [`geography` schema](./geography.json) -Path Params: +#### Query Parameters | Name | Type | Required/Optional | Description | | ------------- | ---- | --- | --------------------------------------------------- | -| geography_id | UUID | Required | Unique identifier for a single specific Geography | +| `geography_id` | UUID | Required | Unique identifier for a single specific Geography | -Returns: Details of a single Geography based on a UUID. +Returns: Details of a single Geography based on a UUID. Response body: ```js { - "version": '1.1.0', + "version": '1.2.0', "geography": { "geography_id": UUID, - "geography_type": Enum, + "geography_type": string, "name": string, "description": string, "published_date": timestamp, @@ -204,10 +207,11 @@ Response body: ``` Response codes: -- 200 - success -- 401 - unauthorized -- 404 - no geography found -- 403 - user is attempting to read an unpublished geography, but only has the `geographies:read:published` scope. + +* 200 - success +* 401 - unauthorized +* 404 - no geography found +* 403 - user is attempting to read an unpublished geography, but only has the `geographies:read:published` scope. [Top][toc] @@ -220,7 +224,8 @@ Response codes: Returns: All geography objects Response body: -```js + +```jsonc { "version": "1.1.0", "updated": "1570035222868", @@ -236,8 +241,9 @@ Response body: ``` Response codes: -- 200 - success -- 401 - unauthorized + +* 200 - success +* 401 - unauthorized [Top][toc] From 8f65f3e917a12440b6a06191ffcf5d1756a8ae58 Mon Sep 17 00:00:00 2001 From: Kegan Maher Date: Thu, 28 Oct 2021 13:37:43 -0700 Subject: [PATCH 54/81] update version in examples --- geography/README.md | 2 +- geography/examples/README.md | 12 ++++++------ geography/examples/distribution-zone-8.json | 2 +- geography/examples/geographies.json | 16 ++++++++-------- geography/examples/municipal-boundary.json | 4 ++-- geography/examples/no-ride-zone.json | 4 ++-- geography/examples/operating-area.json | 2 +- geography/examples/slow-ride-zone.json | 4 ++-- geography/examples/stop.json | 4 ++-- 9 files changed, 25 insertions(+), 25 deletions(-) diff --git a/geography/README.md b/geography/README.md index 1b57176d..2699de0d 100644 --- a/geography/README.md +++ b/geography/README.md @@ -227,7 +227,7 @@ Response body: ```jsonc { - "version": "1.1.0", + "version": "1.2.0", "updated": "1570035222868", "geographies": [ { diff --git a/geography/examples/README.md b/geography/examples/README.md index 5b9c2036..dee77f62 100644 --- a/geography/examples/README.md +++ b/geography/examples/README.md @@ -32,7 +32,7 @@ Shows the muncipal boundaries of a regulating entity, which may be larger than t ```json { - "version": "1.0.0", + "version": "1.2.0", "geography": { "geography_id": "e00535dd-d8ff-4b1b-920d-34e7404d0208", "geography_type": "municipal_boundary", @@ -60,7 +60,7 @@ Boundaries of a city's permitted operating area for provider vehicles. ```json { - "version": "1.0.0", + "version": "1.2.0", "geography": { "geography_id": "8ad39dc3-005b-4348-9d61-c830c54c161b", "geography_type": "operating_area", @@ -89,7 +89,7 @@ Boundaries of one of 9 areas in a city where vehicles can be distibuted and rebl ```json { - "version": "1.0.0", + "version": "1.2.0", "geography": { "geography_id": "70a91abc-0d9f-43a9-8e6a-763142dc6c94", "geography_type": "distribution_zone", @@ -119,7 +119,7 @@ Boundaries of areas in a city where vehicles are not allowed be ridden by riders ```json { - "version": "1.0.0", + "version": "1.2.0", "geography": { "geography_id": "fc277865-79d3-4f0e-8459-53e9a647db99", "geography_type": "slow_ride_zone", @@ -144,7 +144,7 @@ Boundaries of areas in a city where vehicles are to be ridden at a slower top sp ```json { - "version": "1.0.0", + "version": "1.2.0", "geography": { "geography_id": "8ad39dc3-005b-4348-9d61-c830c54c161b", "geography_type": "operating_area", @@ -174,7 +174,7 @@ Designated stoping areas for vehicles. In this example the recommended parking l ```json { - "version": "1.0.0", + "version": "1.2.0", "geography": { "geography_id": "d1328cdb-92fe-4267-85e0-a9fe5653268e", "geography_type": "stop", diff --git a/geography/examples/distribution-zone-8.json b/geography/examples/distribution-zone-8.json index 3da278a4..8d4203a3 100644 --- a/geography/examples/distribution-zone-8.json +++ b/geography/examples/distribution-zone-8.json @@ -1,5 +1,5 @@ { - "version": "1.0.0", + "version": "1.2.0", "geography": { "geography_id": "70a91abc-0d9f-43a9-8e6a-763142dc6c94", "geography_type": "distribution_zone", diff --git a/geography/examples/geographies.json b/geography/examples/geographies.json index 854d2484..67a1020d 100644 --- a/geography/examples/geographies.json +++ b/geography/examples/geographies.json @@ -1,9 +1,9 @@ { - "version": "1.1.0", + "version": "1.2.0", "updated": "1570035222868", "geographies": [ { - "version": "1.0.0", + "version": "1.2.0", "geography": { "geography_id": "e00535dd-d8ff-4b1b-920d-34e7404d0208", "geography_type": "municipal_boundary", @@ -208,7 +208,7 @@ } }, { - "version": "1.0.0", + "version": "1.2.0", "geography": { "geography_id": "8ad39dc3-005b-4348-9d61-c830c54c161b", "geography_type": "operating_area", @@ -15450,7 +15450,7 @@ } }, { - "version": "1.0.0", + "version": "1.2.0", "geography": { "geography_id": "70a91abc-0d9f-43a9-8e6a-763142dc6c94", "geography_type": "distribution_zone", @@ -17290,7 +17290,7 @@ } }, { - "version": "1.0.0", + "version": "1.2.0", "geography": { "geography_id": "e00535dd-d8ff-4b1b-920d-34e7404d0208", "geography_type": "no_ride_zone", @@ -17844,7 +17844,7 @@ } }, { - "version": "1.0.0", + "version": "1.2.0", "geography": { "geography_id": "fc277865-79d3-4f0e-8459-53e9a647db99", "geography_type": "slow_ride_zone", @@ -19855,7 +19855,7 @@ } }, { - "version": "1.0.0", + "version": "1.2.0", "geography": { "geography_id": "d1328cdb-92fe-4267-85e0-a9fe5653268e", "geography_type": "stop", @@ -20001,4 +20001,4 @@ } } ] -} \ No newline at end of file +} diff --git a/geography/examples/municipal-boundary.json b/geography/examples/municipal-boundary.json index 29240ada..bc45f7f3 100644 --- a/geography/examples/municipal-boundary.json +++ b/geography/examples/municipal-boundary.json @@ -1,5 +1,5 @@ { - "version": "1.0.0", + "version": "1.2.0", "geography": { "geography_id": "e00535dd-d8ff-4b1b-920d-34e7404d0208", "geography_type": "municipal_boundary", @@ -202,4 +202,4 @@ ] } } -} \ No newline at end of file +} diff --git a/geography/examples/no-ride-zone.json b/geography/examples/no-ride-zone.json index d1821d90..601bfc7c 100644 --- a/geography/examples/no-ride-zone.json +++ b/geography/examples/no-ride-zone.json @@ -1,5 +1,5 @@ { - "version": "1.0.0", + "version": "1.2.0", "geography": { "geography_id": "e00535dd-d8ff-4b1b-920d-34e7404d0208", "geography_type": "no_ride_zone", @@ -551,4 +551,4 @@ ] } } -} \ No newline at end of file +} diff --git a/geography/examples/operating-area.json b/geography/examples/operating-area.json index 4de24220..5493c179 100644 --- a/geography/examples/operating-area.json +++ b/geography/examples/operating-area.json @@ -1,5 +1,5 @@ { - "version": "1.0.0", + "version": "1.2.0", "geography": { "geography_id": "8ad39dc3-005b-4348-9d61-c830c54c161b", "geography_type": "operating_area", diff --git a/geography/examples/slow-ride-zone.json b/geography/examples/slow-ride-zone.json index 278a13e4..f665d2e2 100644 --- a/geography/examples/slow-ride-zone.json +++ b/geography/examples/slow-ride-zone.json @@ -1,5 +1,5 @@ { - "version": "1.0.0", + "version": "1.2.0", "geography": { "geography_id": "fc277865-79d3-4f0e-8459-53e9a647db99", "geography_type": "slow_ride_zone", @@ -2008,4 +2008,4 @@ ] } } -} \ No newline at end of file +} diff --git a/geography/examples/stop.json b/geography/examples/stop.json index bea9c9f3..fc0b1464 100644 --- a/geography/examples/stop.json +++ b/geography/examples/stop.json @@ -1,5 +1,5 @@ { - "version": "1.0.0", + "version": "1.2.0", "geography": { "geography_id": "d1328cdb-92fe-4267-85e0-a9fe5653268e", "geography_type": "stop", @@ -143,4 +143,4 @@ ] } } -} \ No newline at end of file +} From 42a6e3543058a5a971191c25d32e34663cc28755 Mon Sep 17 00:00:00 2001 From: Kegan Maher Date: Thu, 28 Oct 2021 13:39:20 -0700 Subject: [PATCH 55/81] update version in jurisdiction examples --- jurisdiction/examples/README.md | 2 +- jurisdiction/examples/jurisdictions.json | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/jurisdiction/examples/README.md b/jurisdiction/examples/README.md index cbb8e976..947545d2 100644 --- a/jurisdiction/examples/README.md +++ b/jurisdiction/examples/README.md @@ -6,7 +6,7 @@ This file presents an example of how to format a flat file, should an agency pre ```js { - "version": "1.1.0", + "version": "1.2.0", "updated": "1570035222868", "end_date": "1570035222868", "jurisdictions": diff --git a/jurisdiction/examples/jurisdictions.json b/jurisdiction/examples/jurisdictions.json index 5f4e9d52..9e54b15d 100644 --- a/jurisdiction/examples/jurisdictions.json +++ b/jurisdiction/examples/jurisdictions.json @@ -1,9 +1,9 @@ { - "version": "1.1.0", + "version": "1.2.0", "updated": "1570035222868", "end_date": "1570035222868", - "jurisdictions": + "jurisdictions": [ { "jurisdiction_id": "240edf69-9f2b-457c-accf-e8156e78811f", From 1fed1aae15c3c46915c1d193b55989c0e96608ab Mon Sep 17 00:00:00 2001 From: Kegan Maher Date: Thu, 28 Oct 2021 13:42:14 -0700 Subject: [PATCH 56/81] update version in policy examples --- policy/examples/idle-time.json | 2 +- policy/examples/metered-parking-fees.json | 2 +- policy/examples/per-trip-fees.json | 2 +- policy/examples/prohibited-zone.json | 2 +- policy/examples/provider-cap.json | 2 +- policy/examples/required-parking.json | 2 +- policy/examples/requirements.md | 14 +++++++------- policy/examples/speed-limits.json | 2 +- policy/examples/vehicle-row-fees.json | 2 +- 9 files changed, 15 insertions(+), 15 deletions(-) diff --git a/policy/examples/idle-time.json b/policy/examples/idle-time.json index 8b8badf2..bbaf0b74 100644 --- a/policy/examples/idle-time.json +++ b/policy/examples/idle-time.json @@ -1,6 +1,6 @@ { "updated": 0, - "version": "1.0.0", + "version": "1.2.0", "data": { "policies": [ { diff --git a/policy/examples/metered-parking-fees.json b/policy/examples/metered-parking-fees.json index c1d83daa..a12a07a0 100644 --- a/policy/examples/metered-parking-fees.json +++ b/policy/examples/metered-parking-fees.json @@ -1,6 +1,6 @@ { "updated": 0, - "version": "1.0.0", + "version": "1.2.0", "data": { "policies": [ { diff --git a/policy/examples/per-trip-fees.json b/policy/examples/per-trip-fees.json index 4e435329..d48de4cc 100644 --- a/policy/examples/per-trip-fees.json +++ b/policy/examples/per-trip-fees.json @@ -1,6 +1,6 @@ { "updated": 0, - "version": "1.0.0", + "version": "1.2.0", "data": { "policies": [ { diff --git a/policy/examples/prohibited-zone.json b/policy/examples/prohibited-zone.json index 7bdc628d..27dc080c 100644 --- a/policy/examples/prohibited-zone.json +++ b/policy/examples/prohibited-zone.json @@ -1,6 +1,6 @@ { "updated": 0, - "version": "1.0.0", + "version": "1.2.0", "data": { "policies": [ { diff --git a/policy/examples/provider-cap.json b/policy/examples/provider-cap.json index bc6b1546..d1006049 100644 --- a/policy/examples/provider-cap.json +++ b/policy/examples/provider-cap.json @@ -1,6 +1,6 @@ { "updated": 0, - "version": "1.0.0", + "version": "1.2.0", "data": { "policies": [ { diff --git a/policy/examples/required-parking.json b/policy/examples/required-parking.json index 62dc766b..76f13468 100644 --- a/policy/examples/required-parking.json +++ b/policy/examples/required-parking.json @@ -1,6 +1,6 @@ { "updated": 0, - "version": "1.0.0", + "version": "1.2.0", "data": { "policies": [ { diff --git a/policy/examples/requirements.md b/policy/examples/requirements.md index 41b17cd3..4df23334 100644 --- a/policy/examples/requirements.md +++ b/policy/examples/requirements.md @@ -134,7 +134,7 @@ Version 1.1.0 for one provider with scooters, and 1.0.0 for another provider for "required_data_specs": [ { "data_spec_name": "MDS", - "version": "1.1.0", + "version": "1.2.0", "required_apis": [ { "api_name": "provider", @@ -167,7 +167,7 @@ Version 1.1.0 for one provider with scooters, and 1.0.0 for another provider for "required_data_specs": [ { "data_spec_name": "MDS", - "version": "1.0.0", + "version": "1.2.0", "required_apis": [ { "api_name": "provider", @@ -224,7 +224,7 @@ Version 1.1.0 for 2 providers requiring only historic Provider `/trips` with the "required_data_specs": [ { "data_spec_name": "MDS", - "version": "1.1.0", + "version": "1.2.0", "required_apis": [ { "api_name": "provider", @@ -284,7 +284,7 @@ Version 1.1.0 for 2 providers asking for only historic [Provider `/trips`](/prov "required_data_specs": [ { "data_spec_name": "MDS", - "version": "1.1.0", + "version": "1.2.0", "required_apis": [ { "api_name": "provider", @@ -352,7 +352,7 @@ Note: by specifying geography, policy, and jurisdiction here with a URL, the age "required_data_specs": [ { "data_spec_name": "MDS", - "version": "1.1.0", + "version": "1.2.0", "required_apis": [ { "api_name": "provider", @@ -535,7 +535,7 @@ Version 1.1.0 for 3 providers and serving Agency only linking to a defined MDS P "required_data_specs": [ { "data_spec_name": "MDS", - "version": "1.1.0", + "version": "1.2.0", "required_apis": [ { "api_name": "agency", @@ -620,7 +620,7 @@ Version 1.1.0 for 2 providers requiring Provider `/status_changes` with the mini "required_data_specs": [ { "data_spec_name": "MDS", - "version": "1.1.0", + "version": "1.2.0", "required_apis": [ { "api_name": "provider", diff --git a/policy/examples/speed-limits.json b/policy/examples/speed-limits.json index 8687a646..d14dd2ef 100644 --- a/policy/examples/speed-limits.json +++ b/policy/examples/speed-limits.json @@ -1,6 +1,6 @@ { "updated": 0, - "version": "1.0.0", + "version": "1.2.0", "data": { "policies": [ { diff --git a/policy/examples/vehicle-row-fees.json b/policy/examples/vehicle-row-fees.json index 39bd9592..ec6ea351 100644 --- a/policy/examples/vehicle-row-fees.json +++ b/policy/examples/vehicle-row-fees.json @@ -1,6 +1,6 @@ { "updated": 0, - "version": "1.0.0", + "version": "1.2.0", "data": { "policies": [ { From 1ac56955b4385a4e21ef91e8047af885375c487b Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 29 Oct 2021 11:10:01 -0400 Subject: [PATCH 57/81] Update issue templates for provider/agency IDs --- .github/ISSUE_TEMPLATE/add-agency-id.md | 33 +++++++++++++++++++++++ .github/ISSUE_TEMPLATE/add-provider-id.md | 29 ++++++++++++++++++++ 2 files changed, 62 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/add-agency-id.md create mode 100644 .github/ISSUE_TEMPLATE/add-provider-id.md diff --git a/.github/ISSUE_TEMPLATE/add-agency-id.md b/.github/ISSUE_TEMPLATE/add-agency-id.md new file mode 100644 index 00000000..172a6df9 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/add-agency-id.md @@ -0,0 +1,33 @@ +--- +name: Add Agency ID +about: Create Agency ID for use in MDS +title: '' +labels: '' +assignees: '' + +--- + +**Note:** See the [Adding an MDS Agency ID](https://github.com/openmobilityfoundation/mobility-data-specification/wiki/Adding-an-MDS-Agency-ID) page for more help. + +Opening this issue will allow you as a city or governmental agency get an official agency ID for use across MDS globally, and include in your Requirements URL. + +## Fields needed from you for the [agencies.csv file](https://github.com/openmobilityfoundation/mobility-data-specification/blob/main/agencies.csv). + +_All fields are required._ + +1. agency_country_iso_code - Two letter ISO country code where your agency is located. + - ... +1. agency_state - Geographic abbreviation or name of the state where your agency is located. + - ... +1. agency_city - Geographic name of the city where your agency is located. + - ... +1. agency_name - Full name of your governmental city/agency. + - ... +1. agency_id - A random UUID version 4. There are lots of way to generate a unique UUID, like using this website. + - ... +1. department_url - URL to the home page of your agency's department. + - ... +1. requirement_url - Full https:// URL where your current Policy Requirements endpoint is located. + - ... + +Additionally, please provide your name and role within your agency to help with verification. diff --git a/.github/ISSUE_TEMPLATE/add-provider-id.md b/.github/ISSUE_TEMPLATE/add-provider-id.md new file mode 100644 index 00000000..192defd1 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/add-provider-id.md @@ -0,0 +1,29 @@ +--- +name: Add Provider ID +about: Create Provider ID for use in MDS +title: 'Add Provider ID: [Provider Name]' +labels: admin +assignees: schnuerle + +--- + +**Note:** See the [Adding an MDS Provider ID](https://github.com/openmobilityfoundation/mobility-data-specification/wiki/Adding-an-MDS-Provider-ID) page for more help. + +Opening this issue will allow you as a mobility service provider get an official provider ID for use across MDS globally. + +## Fields needed from you for the [providers.csv file](https://github.com/openmobilityfoundation/mobility-data-specification/blob/main/providers.csv). + +_All fields are required._ + +1. provider_name - Short name of your company. + - ... +1. provider_id - A random UUID version 4. There are lots of way to generate a unique UUID, like using this [website](https://www.uuidgenerator.net/version4). + - ... +1. url - URL to the home page of your company. + - ... +1. mds_api_url - Full https:// URL where your root MDS feeds are located. + - ... +1. gbfs_api_url - Full https:// URL where your public GBFS feeds are located. + - ... + +Additionally, please provide your name and role within your agency to help with verification. From efbbaf575bbf10c15555e4860b6623da22f119c3 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 29 Oct 2021 11:11:14 -0400 Subject: [PATCH 58/81] Update add-agency-id.md --- .github/ISSUE_TEMPLATE/add-agency-id.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/add-agency-id.md b/.github/ISSUE_TEMPLATE/add-agency-id.md index 172a6df9..800418b9 100644 --- a/.github/ISSUE_TEMPLATE/add-agency-id.md +++ b/.github/ISSUE_TEMPLATE/add-agency-id.md @@ -1,8 +1,8 @@ --- name: Add Agency ID about: Create Agency ID for use in MDS -title: '' -labels: '' +title: 'Add Agency ID: [Agency Name]' +labels: 'admin' assignees: '' --- From 7c96d94db728bf09dca40178191a3b65c0a08b6f Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 29 Oct 2021 11:11:34 -0400 Subject: [PATCH 59/81] Update add-provider-id.md --- .github/ISSUE_TEMPLATE/add-provider-id.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/ISSUE_TEMPLATE/add-provider-id.md b/.github/ISSUE_TEMPLATE/add-provider-id.md index 192defd1..ae097a1c 100644 --- a/.github/ISSUE_TEMPLATE/add-provider-id.md +++ b/.github/ISSUE_TEMPLATE/add-provider-id.md @@ -3,7 +3,7 @@ name: Add Provider ID about: Create Provider ID for use in MDS title: 'Add Provider ID: [Provider Name]' labels: admin -assignees: schnuerle +assignees: '' --- From 633a784cb155feb66a2e19059ae6adb376ef6da0 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 29 Oct 2021 11:11:53 -0400 Subject: [PATCH 60/81] Update add-agency-id.md --- .github/ISSUE_TEMPLATE/add-agency-id.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/ISSUE_TEMPLATE/add-agency-id.md b/.github/ISSUE_TEMPLATE/add-agency-id.md index 800418b9..a07b7bae 100644 --- a/.github/ISSUE_TEMPLATE/add-agency-id.md +++ b/.github/ISSUE_TEMPLATE/add-agency-id.md @@ -2,7 +2,7 @@ name: Add Agency ID about: Create Agency ID for use in MDS title: 'Add Agency ID: [Agency Name]' -labels: 'admin' +labels: admin assignees: '' --- From f1ceea8eb027e845a95ca8cd9b8be90145e13363 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 29 Oct 2021 12:17:12 -0400 Subject: [PATCH 61/81] Added Ryde Technology provider From #684 --- providers.csv | 1 + 1 file changed, 1 insertion(+) diff --git a/providers.csv b/providers.csv index dad60d11..842f306d 100644 --- a/providers.csv +++ b/providers.csv @@ -31,3 +31,4 @@ Pony,f190d330-b49e-4590-871b-0bcbec565a8c,https://getapony.com/,https://mds.geta SHARE-NOW,d8f880d6-96d8-4cdc-8069-32a683b2bce6,https://www.share-now.com,https://external.share-now.com/api/rental/mds/,https://external.share-now.com/api/rental/mds/gbfs/ Boaz Bikes,7c96bc58-fb63-433a-b77f-84ccb1c9d737,https://www.boazbikes.com/,https://mds.movatic.co/,https://gbsf.movatic.co/en/1.1/576347857979998215 VeoRide INC.,6e39f9db-751b-5cea-ae7e-486f579a56bc,https://www.veoride.com/,https://cluster-prod.veoride.com/api/shares/mds,https://cluster-prod.veoride.com/api/shares/gbfs +RydeTechnology,bcd3af0f-d606-443c-b862-ed47f236fdc8,https://www.ryde-technology.com,, From 8b4f0fc6e8a8d96be584d197294a39fc6c6f77d8 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 29 Oct 2021 12:19:50 -0400 Subject: [PATCH 62/81] Removed Ryde since no MDS or GBFS URLs --- providers.csv | 1 - 1 file changed, 1 deletion(-) diff --git a/providers.csv b/providers.csv index 842f306d..dad60d11 100644 --- a/providers.csv +++ b/providers.csv @@ -31,4 +31,3 @@ Pony,f190d330-b49e-4590-871b-0bcbec565a8c,https://getapony.com/,https://mds.geta SHARE-NOW,d8f880d6-96d8-4cdc-8069-32a683b2bce6,https://www.share-now.com,https://external.share-now.com/api/rental/mds/,https://external.share-now.com/api/rental/mds/gbfs/ Boaz Bikes,7c96bc58-fb63-433a-b77f-84ccb1c9d737,https://www.boazbikes.com/,https://mds.movatic.co/,https://gbsf.movatic.co/en/1.1/576347857979998215 VeoRide INC.,6e39f9db-751b-5cea-ae7e-486f579a56bc,https://www.veoride.com/,https://cluster-prod.veoride.com/api/shares/mds,https://cluster-prod.veoride.com/api/shares/gbfs -RydeTechnology,bcd3af0f-d606-443c-b862-ed47f236fdc8,https://www.ryde-technology.com,, From 3882e93e8c8d888db161f9f96771ce11e4cd949c Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 29 Oct 2021 17:19:18 -0400 Subject: [PATCH 63/81] Formatting on agency issue --- .github/ISSUE_TEMPLATE/add-agency-id.md | 28 ++++++++++++------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/add-agency-id.md b/.github/ISSUE_TEMPLATE/add-agency-id.md index a07b7bae..7f550bb0 100644 --- a/.github/ISSUE_TEMPLATE/add-agency-id.md +++ b/.github/ISSUE_TEMPLATE/add-agency-id.md @@ -15,19 +15,19 @@ Opening this issue will allow you as a city or governmental agency get an offici _All fields are required._ -1. agency_country_iso_code - Two letter ISO country code where your agency is located. - - ... -1. agency_state - Geographic abbreviation or name of the state where your agency is located. - - ... -1. agency_city - Geographic name of the city where your agency is located. - - ... -1. agency_name - Full name of your governmental city/agency. - - ... -1. agency_id - A random UUID version 4. There are lots of way to generate a unique UUID, like using this website. - - ... -1. department_url - URL to the home page of your agency's department. - - ... -1. requirement_url - Full https:// URL where your current Policy Requirements endpoint is located. - - ... +1. **agency_country_iso_code** - Two letter ISO country code where your agency is located. + - ... +1. **agency_state** - Geographic abbreviation or name of the state where your agency is located. + - ... +1. **agency_city** - Geographic name of the city where your agency is located. + - ... +1. **agency_name** - Full name of your governmental city/agency. + - ... +1. **agency_id** - A random UUID version 4. There are lots of way to generate a unique UUID, like using this website. + - ... +1. **department_url** - URL to the home page of your agency's department. + - ... +1. **requirement_url** - Full https:// URL where your current Policy Requirements endpoint is located. + - ... Additionally, please provide your name and role within your agency to help with verification. From 7dae60d2baa9b122168659c144a0e0888a0d7b98 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 29 Oct 2021 17:19:51 -0400 Subject: [PATCH 64/81] Formatting on Provider issue --- .github/ISSUE_TEMPLATE/add-provider-id.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/add-provider-id.md b/.github/ISSUE_TEMPLATE/add-provider-id.md index ae097a1c..8d9a595c 100644 --- a/.github/ISSUE_TEMPLATE/add-provider-id.md +++ b/.github/ISSUE_TEMPLATE/add-provider-id.md @@ -15,15 +15,15 @@ Opening this issue will allow you as a mobility service provider get an official _All fields are required._ -1. provider_name - Short name of your company. - - ... -1. provider_id - A random UUID version 4. There are lots of way to generate a unique UUID, like using this [website](https://www.uuidgenerator.net/version4). - - ... -1. url - URL to the home page of your company. - - ... -1. mds_api_url - Full https:// URL where your root MDS feeds are located. - - ... -1. gbfs_api_url - Full https:// URL where your public GBFS feeds are located. - - ... +1. **provider_name** - Short name of your company. + - ... +1. **provider_id** - A random UUID version 4. There are lots of way to generate a unique UUID, like using this [website](https://www.uuidgenerator.net/version4). + - ... +1. **url** - URL to the home page of your company. + - ... +1. **mds_api_url** - Full https:// URL where your root MDS feeds are located. + - ... +1. **gbfs_api_url** - Full https:// URL where your public GBFS feeds are located. + - ... Additionally, please provide your name and role within your agency to help with verification. From 13729e55f1c717a5b9584f29c55ea882e208d094 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 29 Oct 2021 17:20:46 -0400 Subject: [PATCH 65/81] Header on Agency issue --- .github/ISSUE_TEMPLATE/add-agency-id.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/ISSUE_TEMPLATE/add-agency-id.md b/.github/ISSUE_TEMPLATE/add-agency-id.md index 7f550bb0..210c2a84 100644 --- a/.github/ISSUE_TEMPLATE/add-agency-id.md +++ b/.github/ISSUE_TEMPLATE/add-agency-id.md @@ -11,7 +11,7 @@ assignees: '' Opening this issue will allow you as a city or governmental agency get an official agency ID for use across MDS globally, and include in your Requirements URL. -## Fields needed from you for the [agencies.csv file](https://github.com/openmobilityfoundation/mobility-data-specification/blob/main/agencies.csv). +**Fields needed from you for the [agencies.csv file](https://github.com/openmobilityfoundation/mobility-data-specification/blob/main/agencies.csv).** _All fields are required._ From bf1d150333d2291ff2b6ee394dd0c77e4212c4ef Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 29 Oct 2021 17:21:08 -0400 Subject: [PATCH 66/81] Header on provider issue --- .github/ISSUE_TEMPLATE/add-provider-id.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/ISSUE_TEMPLATE/add-provider-id.md b/.github/ISSUE_TEMPLATE/add-provider-id.md index 8d9a595c..9b5ad30f 100644 --- a/.github/ISSUE_TEMPLATE/add-provider-id.md +++ b/.github/ISSUE_TEMPLATE/add-provider-id.md @@ -11,7 +11,7 @@ assignees: '' Opening this issue will allow you as a mobility service provider get an official provider ID for use across MDS globally. -## Fields needed from you for the [providers.csv file](https://github.com/openmobilityfoundation/mobility-data-specification/blob/main/providers.csv). +**Fields needed from you for the [providers.csv file](https://github.com/openmobilityfoundation/mobility-data-specification/blob/main/providers.csv).** _All fields are required._ From 8a31bda5853ffa78822e546fe5a9ee0cfbc50081 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 29 Oct 2021 17:22:11 -0400 Subject: [PATCH 67/81] Update cities using MDS --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 8f661892..207946ae 100644 --- a/README.md +++ b/README.md @@ -137,7 +137,7 @@ The MDS specification is versioned using Git tags and [semantic versioning](http # Cities Using MDS -More than 115 cities and public agencies around the world use MDS, and it has been implemented by most major [mobility service providers](#providers-using-mds). +More than 140 cities and public agencies across 6 continents around the world use MDS, and it has been implemented by most major [mobility service providers](#providers-using-mds). - See our **[list of cities using MDS](https://www.openmobilityfoundation.org/mds-users/#cities-using-mds)** with links to public mobility websites and policy/permit documents. 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. From 89dee0846c9c6d66b65671cf241d5de5e033d833 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Fri, 29 Oct 2021 17:24:31 -0400 Subject: [PATCH 68/81] Update version number on home --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 207946ae..50dc58bf 100644 --- a/README.md +++ b/README.md @@ -117,7 +117,7 @@ Read about [how to become an OMF member](https://www.openmobilityfoundation.org/ # Versions -MDS has a **current release** (version 1.1.0), **previous releases** (both recommended and longer recommended for use), and **upcoming releases** in development. For a full list of releases, their status, recommended versions, and timelines, see the [Official MDS Releases](https://github.com/openmobilityfoundation/governance/wiki/Releases) page. +MDS has a **current release** (version 1.2.0), **previous releases** (both recommended and longer recommended for use), and **upcoming releases** in development. For a full list of releases, their status, recommended versions, and timelines, see the [Official MDS Releases](https://github.com/openmobilityfoundation/governance/wiki/Releases) page. The OMF provides guidance on upgrading for cities, providers, and software companies, and sample permit language for cities. See our [MDS Version Guidance](https://github.com/openmobilityfoundation/governance/blob/main/technical/OMF-MDS-Version-Guidance.md) for best practices on how and when to upgrade MDS as new versions become available. Our complimentary [MDS Policy Language Guidance](https://github.com/openmobilityfoundation/governance/blob/main/technical/OMF-MDS-Policy-Language-Guidance.md) document is for cities writing MDS into their operating policy and includes sample policy language. @@ -137,7 +137,7 @@ The MDS specification is versioned using Git tags and [semantic versioning](http # Cities Using MDS -More than 140 cities and public agencies across 6 continents around the world use MDS, and it has been implemented by most major [mobility service providers](#providers-using-mds). +More than 150 cities and public agencies across 6 continents around the world use MDS, and it has been implemented by most major [mobility service providers](#providers-using-mds). - See our **[list of cities using MDS](https://www.openmobilityfoundation.org/mds-users/#cities-using-mds)** with links to public mobility websites and policy/permit documents. 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. From 3cadaefb3f508f9690d54727d229e25304f8e7d4 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 1 Nov 2021 09:34:07 -0400 Subject: [PATCH 69/81] Minor updates for Requirements --- policy/README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/policy/README.md b/policy/README.md index f227446a..65476f09 100644 --- a/policy/README.md +++ b/policy/README.md @@ -61,7 +61,7 @@ Versioning must be implemented as specified in the [Versioning section][versioni ## Background -The goal of this specification is to enable Agencies to create, revise, and publish machine-readable policies, as sets of rules for individual and collective device behavior exhibited by both _mobility as a service_ Providers and riders / users. [Examples](./examples/README.md) of policies include: +The goal of the Policy API specification is to enable agencies to create, revise, and publish machine-readable policies, as sets of rules for individual and collective device behavior exhibited by both _mobility as a service_ providers and riders / users. [Examples](./examples/README.md) of policies include: - City-wide and localized caps (e.g. "Minimum 500 and maximum 3000 scooters within city boundaries") - Exclusion zones (e.g. "No scooters are permitted in this district on weekends") @@ -70,7 +70,7 @@ The goal of this specification is to enable Agencies to create, revise, and publ - Idle-time and disabled-time limitations (e.g. "5 days idle while rentable, 12 hours idle while unrentable, per device") - Trip fees and subsidies (e.g. "A 25 cent fee applied when a trip ends downtown") -The machine-readable format allows Providers to obtain policies and compute compliance where it can be determined entirely by data obtained internally. +The machine-readable format allows Providers to obtain policies and compute compliance where it can be determined entirely by data obtained internally, and know what data is required from them and provided to them. **See the [Policy Examples](./examples/README.md) for ways these can be implemented.** @@ -114,7 +114,7 @@ See the [Responses section][responses] for information on valid MDS response cod ### 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. +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. ### Policies @@ -139,7 +139,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 a MDS 1.x.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 MDS 1.x.0 releases. **Endpoint**: `/geographies/{id}` **Method**: `GET` From e07d7c3ed029be2707021d34bb2ced6920c2f638 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 1 Nov 2021 13:27:20 -0400 Subject: [PATCH 70/81] Clarified optionally authenticated in Jursidictions --- jurisdiction/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/jurisdiction/README.md b/jurisdiction/README.md index 5af04111..ea9ab373 100644 --- a/jurisdiction/README.md +++ b/jurisdiction/README.md @@ -2,9 +2,7 @@ MDS Jurisdiction Icon -This specification details the purpose, use cases, and schema for Jurisdictions, a beta feature. Jurisdictions are an optional service that, if implemented, must be authenticated, and served by a coordinated group of agencies. - -The Jursidiction API is to be served by agencies, and it can optionally be made public. 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 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. ## Table of Contents @@ -164,6 +162,8 @@ The publishing Agency should establish and communicate to interested parties how 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. +[Top](#table-of-contents) + ## Examples See the [Jurisdiction Examples](examples/README.md) for a sample `jurisdictions.json` file. From cd64ca612c2b37b57d87667d459350f8dd195859 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 1 Nov 2021 13:29:29 -0400 Subject: [PATCH 71/81] Added Jurisdictions to list of optionally auth APIs --- general-information.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/general-information.md b/general-information.md index 2be07aa2..0170d1c0 100644 --- a/general-information.md +++ b/general-information.md @@ -173,7 +173,7 @@ During the Beta period for this feature, location and telemetry data remain requ ## Optional Authentication -Authorization of the Policy and Geography APIs is no longer required and will be deprecated in next major release with these endpoints becoming optionally private instead of optionally public. An agency may optionally decide to make both the Policy and Geography endpoints 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. +Authorization of the Policy and Geography APIs is no longer required and will be deprecated in next major release with these endpoints becoming 'optionally private' instead of 'optionally public'. An agency may optionally decide to make the Policy and Geography endpoints, as well as Jursidictions, 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. From d69fc306f72d47f463eea3e6dd90a74762116b79 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 1 Nov 2021 13:54:27 -0400 Subject: [PATCH 72/81] Some Gen Info formatting cleanup --- general-information.md | 110 ++++++++++++++++++++--------------------- 1 file changed, 54 insertions(+), 56 deletions(-) diff --git a/general-information.md b/general-information.md index 0170d1c0..8de6fa03 100644 --- a/general-information.md +++ b/general-information.md @@ -58,7 +58,7 @@ Defining terminology and abbreviations used throughout MDS. * **API** - Application Programming Interface - A function or set of functions that allow one software application to access or communicate with features of a different software application or service. * **API Endpoint** - A point at which an API connects with a software application or service. * **DOT** - Department of Transportation, usually a city-run agency. -* **Jurisdiction** - An agency’s area of legal authority to manage and regulate a mobility program in the real world. Note there is also an MDS API called [Jurisdiction](/jurisdiction/, which is a way to digitally represent this. +* **Jurisdiction** - An agency’s area of legal authority to manage and regulate a mobility program in the real world. Note there is also an MDS API called [Jurisdiction](/jurisdiction), which is a way to digitally represent this. * **PROW** - Public Right of Way - the physical infrastructure reserved for transportation purposes, examples include sidewalks, curbs, bike lanes, transit lanes and stations, traffic lanes and signals, and public parking. [Top][toc] @@ -77,20 +77,18 @@ References to geographic datatypes (Point, MultiPolygon, etc.) imply coordinates ### Geographic Telemetry Data -Whenever a vehicle location coordinate measurement is presented, it must be -represented as a GeoJSON [`Feature`][geojson-feature] object with a corresponding -`properties` object with the following properties: +Whenever a vehicle location coordinate measurement is presented, it must be represented as a GeoJSON [`Feature`][geojson-feature] object with a corresponding `properties` object with the following properties: -| Field | Type | Required/Optional | Field Description | -| -------------- | -------------- | --------------------- | ------------------------------------------------------------ | -| `timestamp` | [timestamp][ts] | Required | Date/time that event occurred. Based on GPS or GNSS clock | -| `altitude` | Double | Required if Available | Altitude above mean sea level in meters | -| `heading` | Double | Required if Available | Degrees - clockwise starting at 0 degrees at true North | -| `speed` | Float | Required if Available | Estimated speed in meters / sec as reported by the GPS chipset | -| `accuracy` | Float | Required if Available | Horizontal accuracy, in meters | -| `hdop` | Float | Required if Available | Horizontal GPS or GNSS accuracy value (see [hdop][hdop]) | -| `satellites` | Integer | Required if Available | Number of GPS or GNSS satellites +| Field | Type | Required/Optional | Field Description | +| -------------- | --------------- | --------------------- | ------------------------------------------------------------ | +| `timestamp` | [timestamp][ts] | Required | Date/time that event occurred. Based on GPS or GNSS clock | +| `altitude` | Double | Required if Available | Altitude above mean sea level in meters | +| `heading` | Double | Required if Available | Degrees - clockwise starting at 0 degrees at true North | +| `speed` | Float | Required if Available | Estimated speed in meters / sec as reported by the GPS chipset | +| `accuracy` | Float | Required if Available | Horizontal accuracy, in meters | +| `hdop` | Float | Required if Available | Horizontal GPS or GNSS accuracy value (see [hdop][hdop]) | +| `satellites` | Integer | Required if Available | Number of GPS or GNSS satellites | Example of a vehicle location GeoJSON [`Feature`][geojson-feature] object: @@ -173,7 +171,7 @@ During the Beta period for this feature, location and telemetry data remain requ ## Optional Authentication -Authorization of the Policy and Geography APIs is no longer required and will be deprecated in next major release with these endpoints becoming 'optionally private' instead of 'optionally public'. An agency may optionally decide to make the Policy and Geography endpoints, as well as Jursidictions, 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. +Authorization of the Policy and Geography APIs is no longer required and will be deprecated in next major release with these endpoints (plus Jursidictions) becoming 'optionally private' instead of 'optionally public'. An agency may optionally decide to make the Policy and Geography endpoints, as well as Jursidictions, 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. @@ -230,29 +228,29 @@ All String fields, such as `vehicle_id`, are limited to a maximum of 255 charact Stops describe vehicle trip start and end locations in a pre-designated physical place. They can vary from docking stations with or without charging, corrals with lock-to railings, or suggested parking areas marked with spray paint. Stops are used in both [Provider](/provider#stops) (including routes and event locations) and [Agency](/agency#stops) (including telemetry data). -| Field | Type | Required/Optional | Description | -|------------------------|-------------------------------------------------------------|-------------------|----------------------------------------------------------------------------------------------| -| stop_id | UUID | Required | Unique ID for stop | -| name | String | Required | Name of stop | -| last_reported | Timestamp | Required | Date/Time that the stop was last updated | -| location | GeoJSON [Point Feature](#stop-based-geographic-data) | Required | Simple centerpoint location of the Stop. The use of the optional `geography_id` is recommended to provide more detail. | -| status | [Stop Status](#stop-status) | Required | Object representing the status of the Stop. See [Stop Status](#stop-status). | -| capacity | {vehicle_type: number} | Required | Number of total places per vehicle_type | -| num_vehicles_available | {vehicle_type: number} | Required | How many vehicles are available per vehicle_type at this stop? | -| num_vehicles_disabled | {vehicle_type: number} | Required | How many vehicles are unavailable/reserved per vehicle_type at this stop? | -| provider_id | UUID | Optional | UUID for the Provider managing this stop. Null/undefined if managed by an Agency. See MDS [provider list](/providers.csv). | -| geography_id | UUID | Optional | Pointer to the [Geography](/geography) that represents the Stop geospatially via Polygon or MultiPolygon. | -| region_id | string | Optional | ID of the region where station is located, see [GBFS Station Information][gbfs-station-info] | -| short_name | String | Optional | Abbreviated stop name | -| address | String | Optional | Postal address (useful for directions) | -| post_code | String | Optional | Postal code (e.g. `10036`) | -| rental_methods | [Enum[]][gbfs-station-info] | Optional | List of payment methods accepted at stop, see [GBFS Rental Methods][gbfs-station-info] | -| cross_street | String | Optional | Cross street of where the station is located. | -| num_places_available | {vehicle_type: number} | Optional | How many places are free to be populated with vehicles at this stop? | -| num_places_disabled | {vehicle_type: number} | Optional | How many places are disabled and unable to accept vehicles at this stop? | -| parent_stop | UUID | Optional | Describe a basic hierarchy of stops (e.g.a stop inside of a greater stop) | -| devices | UUID[] | Optional | List of device_ids for vehicles which are currently at this stop | -| image_url | URL | Optional | Link to an image, photo, or diagram of the stop. Could be used by providers to help riders find or use the stop. | +| Field | Type | Required/Optional | Description | +|------------------------|-------------------------------------------------------|-------------------|-------------| +| stop_id | UUID | Required | Unique ID for stop | +| name | String | Required | Name of stop | +| last_reported | Timestamp | Required | Date/Time that the stop was last updated | +| location | GeoJSON [Point Feature](#stop-based-geographic-data) | Required | Simple centerpoint location of the Stop. The use of the optional `geography_id` is recommended to provide more detail. | +| status | [Stop Status](#stop-status) | Required | Object representing the status of the Stop. See [Stop Status](#stop-status). | +| capacity | {vehicle_type: number} | Required | Number of total places per vehicle_type | +| num_vehicles_available | {vehicle_type: number} | Required | How many vehicles are available per vehicle_type at this stop? | +| num_vehicles_disabled | {vehicle_type: number} | Required | How many vehicles are unavailable/reserved per vehicle_type at this stop? | +| provider_id | UUID | Optional | UUID for the Provider managing this stop. Null/undefined if managed by an Agency. See MDS [provider list](/providers.csv). | +| geography_id | UUID | Optional | Pointer to the [Geography](/geography) that represents the Stop geospatially via Polygon or MultiPolygon. | +| region_id | string | Optional | ID of the region where station is located, see [GBFS Station Information][gbfs-station-info] | +| short_name | String | Optional | Abbreviated stop name | +| address | String | Optional | Postal address (useful for directions) | +| post_code | String | Optional | Postal code (e.g. `10036`) | +| rental_methods | [Enum[]][gbfs-station-info] | Optional | List of payment methods accepted at stop, see [GBFS Rental Methods][gbfs-station-info] | +| cross_street | String | Optional | Cross street of where the station is located. | +| num_places_available | {vehicle_type: number} | Optional | How many places are free to be populated with vehicles at this stop? | +| num_places_disabled | {vehicle_type: number} | Optional | How many places are disabled and unable to accept vehicles at this stop? | +| parent_stop | UUID | Optional | Describe a basic hierarchy of stops (e.g.a stop inside of a greater stop) | +| devices | UUID[] | Optional | List of device_ids for vehicles which are currently at this stop | +| image_url | URL | Optional | Link to an image, photo, or diagram of the stop. Could be used by providers to help riders find or use the stop. | ### Stop Status @@ -301,14 +299,14 @@ This table describes the list of vehicle conditions that may be used by regulato In a multi-jurisdiction environment, the status of a vehicle is per-jurisdiction. For example, a vehicle may be in the `on_trip` status for a county that contains five cities, and also in the `on_trip` status for one of those cities, but `elsewhere` for the other four cities. In such a condition, generally a Provider would send the device data to the over-arching jurisdiction (the county) and the vehicle state with respect to each city would be determined by the Agency managing the jurisdictions. -| `vehicle_state` | In PROW? | Description | -| --- | --- | --- | -| `removed` | no | Examples include: at the Provider's warehouse, in a Provider's truck, or destroyed and in a landfill. | -| `available` | yes | Available for rental via the Provider's app. In PROW. | -| `non_operational` | yes | Not available for rent. Examples include: vehicle has low battery, or currently outside legal operating hours. | -| `reserved` | yes | Reserved via Provider's app, waiting to be picked up by a rider. | -| `on_trip` | yes | In possession of renter. May or may not be in motion. | -| `elsewhere` | no | Outside of regulator's jurisdiction, and thus not subject to cap-counts or other regulations. Example: a vehicle that started a trip in L.A. has transitioned to Santa Monica. | +| `vehicle_state` | In PROW? | Description | +| ----------------- | -------- | ----------- | +| `removed` | no | Examples include: at the Provider's warehouse, in a Provider's truck, or destroyed and in a landfill. | +| `available` | yes | Available for rental via the Provider's app. In PROW. | +| `non_operational` | yes | Not available for rent. Examples include: vehicle has low battery, or currently outside legal operating hours. | +| `reserved` | yes | Reserved via Provider's app, waiting to be picked up by a rider. | +| `on_trip` | yes | In possession of renter. May or may not be in motion. | +| `elsewhere` | no | Outside of regulator's jurisdiction, and thus not subject to cap-counts or other regulations. Example: a vehicle that started a trip in L.A. has transitioned to Santa Monica. | | `unknown` | unknown | Provider has lost contact with the vehicle and its disposition is unknown. Examples include: taken into a private residence, thrown in river. | [Top][toc] @@ -318,7 +316,7 @@ In a multi-jurisdiction environment, the status of a vehicle is per-jurisdiction Event types are the possible transitions between some vehicle states. | `event_type` | Description | -|---|---| +|--------------|-------------| | `agency_drop_off` | Drop off by the agency | | `agency_pick_up` | Pick up by the agency | | `battery_charged` | Battery charged | @@ -372,8 +370,8 @@ Note that to handle out-of-order events, the validity of the prior-state shall n Vehicles can enter the `unknown` state to and from any other state with the following event types: any state can go to `unknown` with event type `comms_lost`, `missing`, or `unspecified`, and `unknown` can go to any state with event type `comms_restored` of `unspecified`. -| Valid prior `vehicle_state` values | `vehicle_state` | `event_type` | Description | -| --- | --- | --- | --- | +| Valid prior `vehicle_state` values | `vehicle_state` | `event_type` | Description | +| ---------------------------------- | --------------- | ------------ | ----------- | | `non_operational` | `available` | `battery_charged` | The vehicle became available because its battery is now charged. | | `non_operational` | `available` | `on_hours` | The vehicle has entered operating hours (per the regulator or per the provider) | | `removed`, `unknown` | `available` | `provider_drop_off` | The vehicle was placed in the PROW by the provider | @@ -431,13 +429,13 @@ The *State Machine Diagram* shows how `vehicle_state` and `event_type` relate to The list of allowed `vehicle_type` values in MDS. Aligning with [GBFS vehicle types form factors](https://github.com/NABSA/gbfs/blob/master/gbfs.md#vehicle_typesjson-added-in-v21-rc). | `vehicle_type` | Description | -|---------------| --- | -| bicycle | A two-wheeled mobility device intended for personal transportation that can be operated via pedals, with or without a motorized assist (includes e-bikes, recumbents, and tandems) | -| cargo_bicycle | A two- or three-wheeled bicycle intended for transporting larger, heavier cargo than a standard bicycle (such as goods or passengers), with or without motorized assist (includes bakfiets/front-loaders, cargo trikes, and long-tails) | -| car | A passenger car or similar light-duty vehicle | -| scooter | A standing or seated fully-motorized mobility device intended for one rider, capable of travel at low or moderate speeds, and suited for operation in infrastructure shared with motorized bicycles | -| moped | A seated fully-motorized mobility device capable of travel at moderate or high speeds and suited for operation in general urban traffic | -| other | A device that does not fit in the other categories | +|----------------| ----------- | +| bicycle | A two-wheeled mobility device intended for personal transportation that can be operated via pedals, with or without a motorized assist (includes e-bikes, recumbents, and tandems) | +| cargo_bicycle | A two- or three-wheeled bicycle intended for transporting larger, heavier cargo than a standard bicycle (such as goods or passengers), with or without motorized assist (includes bakfiets/front-loaders, cargo trikes, and long-tails) | +| car | A passenger car or similar light-duty vehicle | +| scooter | A standing or seated fully-motorized mobility device intended for one rider, capable of travel at low or moderate speeds, and suited for operation in infrastructure shared with motorized bicycles | +| moped | A seated fully-motorized mobility device capable of travel at moderate or high speeds and suited for operation in general urban traffic | +| other | A device that does not fit in the other categories | [Top][toc] @@ -452,7 +450,7 @@ The version parameter specifies the dot-separated combination of major and minor Clients must specify the version they are targeting through the `Accept` header. For example: ```http -Accept: application/vnd.mds+json;version=0.3 +Accept: application/vnd.mds+json;version=1.2.0 ``` Since versioning was not available from the start, the following APIs provide a fallback version if the `Accept` header is not set as specified above: From d389db603d57d2fd8ce44e8cc5514fba6edeefbc Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 1 Nov 2021 13:56:45 -0400 Subject: [PATCH 73/81] Clarified UUID default/usage --- general-information.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/general-information.md b/general-information.md index 8de6fa03..20fd7589 100644 --- a/general-information.md +++ b/general-information.md @@ -289,7 +289,7 @@ A `timestamp` refers to integer milliseconds since Unix epoch. Object identifiers are described via Universally Unique Identifiers [(UUIDs)](https://en.wikipedia.org/wiki/Universally_unique_identifier). For example, the `device_id` field used to uniquely identify a vehicle is a UUID. -MDS uses Version 1 UUIDs. +MDS uses Version 1 UUIDs by default. Version 4 UUIDs may be used where noted. [Top][toc] From 9ec2023f4649d9284be33d0cb06c862f742f98f5 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 1 Nov 2021 19:55:55 -0400 Subject: [PATCH 74/81] Updated to reflect single MDS WG --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 50dc58bf..9093d904 100644 --- a/README.md +++ b/README.md @@ -70,7 +70,7 @@ The [`metrics`](/metrics) API endpoints are intended to be implemented by regula ## Modularity -MDS is designed to be a modular kit-of-parts. Regulatory agencies can use the components of the API that are appropriate for their needs. An agency may choose to use only `agency`, `provider`, or `policy`. Other APIs like `geography`, `jurisdiction`, and `metrics` can be used in coordination as described with these APIs or sometimes on their own. Or agencies may select specific elements (endpoints) from each API to help them implement their goals. Development of the APIs takes place under the guidance of either the OMF's [City Services](https://github.com/openmobilityfoundation/mobility-data-specification/wiki/MDS-City-Services-Working-Group) or [Provider Services](https://github.com/openmobilityfoundation/mobility-data-specification/wiki/MDS-Provider-Services-Working-Group) Working Groups. +MDS is designed to be a modular kit-of-parts. Regulatory agencies can use the components of the API that are appropriate for their needs. An agency may choose to use only `agency`, `provider`, or `policy`. Other APIs like `geography`, `jurisdiction`, and `metrics` can be used in coordination as described with these APIs or sometimes on their own. Or agencies may select specific elements (endpoints) from each API to help them implement their goals. Development of the APIs takes place under the guidance of the OMF's [MDS Working Group](https://github.com/openmobilityfoundation/mobility-data-specification/wiki/MDS-Working-Group). Many parts of the MDS definitions and APIs align across each other. In these cases, consolidated information can be found on the [General Information](/general-information.md) page. From 8e0a9bd64fb1eaddd6d94b36c67835a3e4fd59c4 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 1 Nov 2021 20:47:20 -0400 Subject: [PATCH 75/81] Simplified MDS owners --- CODEOWNERS | 11 ++--------- 1 file changed, 2 insertions(+), 9 deletions(-) diff --git a/CODEOWNERS b/CODEOWNERS index 8dc8e483..22519abe 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -3,12 +3,5 @@ ## All MDS approvals * @openmobilityfoundation/omf-admin -## Provider Services Working Group -/provider/* @openmobilityfoundation/provider-maintainers @openmobilityfoundation/omf-admin - -## City Services Working Group Specific, also JSON Schema -/agency/* @openmobilityfoundation/city-services-maintainers @openmobilityfoundation/omf-admin -/policy/* @openmobilityfoundation/city-services-maintainers @openmobilityfoundation/omf-admin - -## schema is changed by provider and city services working group -/schema/* @openmobilityfoundation/provider-maintainers @openmobilityfoundation/city-services-maintainers @openmobilityfoundation/omf-admin +## MDS Working Group +* @openmobilityfoundation/mds-maintainers @openmobilityfoundation/omf-admin From c118e96138b102a88afe7de580182dbf3ef3b311 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 1 Nov 2021 23:25:57 -0400 Subject: [PATCH 76/81] Add Data Privacy section --- README.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/README.md b/README.md index 9093d904..0ec3995b 100644 --- a/README.md +++ b/README.md @@ -166,6 +166,22 @@ Please [let us know](https://www.openmobilityfoundation.org/get-in-touch/) if yo [Top][toc] +# Data Privacy + +MDS includes information about vehicles, their location, and trips taken on those vehicles to allow agencies to regulate their use in the public right of way and to conduct transportation planning and analysis. While MDS is not designed to convey personal information about the users of shared mobility services, data collected about mobility can be sensitive. The OMF and MDS community have created a number of resources to help cities, mobility providers, and software companies handle vehicle data safely: + +* [MDS Privacy Guide for Cities](https://github.com/openmobilityfoundation/governance/raw/main/documents/OMF-MDS-Privacy-Guide-for-Cities.pdf) - guide that covers essential privacy topics and best practices +* [The Privacy Principles for Mobility Data](https://www.mobilitydataprivacyprinciples.org/) - principles endorsed by the OMF and other mobility organizations to guide the mobility ecosystem in the responsible use of data and the protection of individual privacy +* [Mobility Data State of Practice](https://github.com/openmobilityfoundation/privacy-committee/blob/main/products/state-of-the-practice.md) - real-world examples related to the handling and protection of MDS and other types of mobility data +* [Understanding the Data in MDS](https://github.com/openmobilityfoundation/mobility-data-specification/wiki/Understanding-the-Data-in-MDS) - technical document outlining what data is (and is not) in MDS +* [Use Case Database](https://github.com/openmobilityfoundation/mobility-data-specification/blob/main/README.md#use-cases) - a starting point for understanding how MDS can be used, and what parts of MDS is required to meet those use cases +* [Policy Requirements](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/policy#requirement) - built into MDS, allowing agencies to specify only the endpoints and fields needed for program regulation +* Using MDS Under GDPR (link coming soon) - how to use MDS in the context of GDPR in Europe + +Thank you to OMF’s [Privacy, Security, and Transparency Committee](https://github.com/openmobilityfoundation/privacy-committee#welcome-to-the-privacy-security-and-transparency-committee) for creating many of these resources, and for advising the OMF on principles and practices that ensure the secure handling of mobility data. The committee – which is composed of both private and public sector OMF members – also holds regular public meetings, which provide additional resources and an opportunity to discuss issues related to privacy and mobility data. Learn more [here](https://github.com/openmobilityfoundation/privacy-committee#welcome-to-the-privacy-security-and-transparency-committee). + +[Top][toc] + # Use Cases How cities use MDS depends on a variety of factors: their transportation goals, existing services and infrastructure, and the unique needs of their communities. Cities are using MDS to create policy, enforce rules, manage hundreds of devices, and ensure the safe operation of vehicles in the public right of way. Some examples of how cities are using MDS in practice are: From f0ebd722979f6ef81715eb25df133715be18ddb7 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Mon, 1 Nov 2021 23:26:33 -0400 Subject: [PATCH 77/81] Add Data Privacy to TOC --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 0ec3995b..78245281 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,7 @@ - [Cities Using MDS](#cities-using-mds) - [Providers Using MDS](#providers-using-mds) - [Software Companies Using MDS](#software-companies-using-mds) +- [Data Privacy](#data-privacy) - [Use Cases](#use-cases) - [Related Projects](#related-projects) From 4189d0540eef5656dce87ef13b8419b50e3b8705 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Wed, 3 Nov 2021 10:14:00 -0400 Subject: [PATCH 78/81] Tweaks to privacy area --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 78245281..af62e28c 100644 --- a/README.md +++ b/README.md @@ -175,11 +175,11 @@ MDS includes information about vehicles, their location, and trips taken on thos * [The Privacy Principles for Mobility Data](https://www.mobilitydataprivacyprinciples.org/) - principles endorsed by the OMF and other mobility organizations to guide the mobility ecosystem in the responsible use of data and the protection of individual privacy * [Mobility Data State of Practice](https://github.com/openmobilityfoundation/privacy-committee/blob/main/products/state-of-the-practice.md) - real-world examples related to the handling and protection of MDS and other types of mobility data * [Understanding the Data in MDS](https://github.com/openmobilityfoundation/mobility-data-specification/wiki/Understanding-the-Data-in-MDS) - technical document outlining what data is (and is not) in MDS -* [Use Case Database](https://github.com/openmobilityfoundation/mobility-data-specification/blob/main/README.md#use-cases) - a starting point for understanding how MDS can be used, and what parts of MDS is required to meet those use cases +* [Use Case Database](https://www.openmobilityfoundation.org/whats-possible-with-mds/) - a starting point for understanding how MDS can be used, and what parts of MDS is required to meet those use cases * [Policy Requirements](https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/policy#requirement) - built into MDS, allowing agencies to specify only the endpoints and fields needed for program regulation * Using MDS Under GDPR (link coming soon) - how to use MDS in the context of GDPR in Europe -Thank you to OMF’s [Privacy, Security, and Transparency Committee](https://github.com/openmobilityfoundation/privacy-committee#welcome-to-the-privacy-security-and-transparency-committee) for creating many of these resources, and for advising the OMF on principles and practices that ensure the secure handling of mobility data. The committee – which is composed of both private and public sector OMF members – also holds regular public meetings, which provide additional resources and an opportunity to discuss issues related to privacy and mobility data. Learn more [here](https://github.com/openmobilityfoundation/privacy-committee#welcome-to-the-privacy-security-and-transparency-committee). +The OMF’s [Privacy, Security, and Transparency Committee](https://github.com/openmobilityfoundation/privacy-committee#welcome-to-the-privacy-security-and-transparency-committee) creates many of these resources, and advises the OMF on principles and practices that ensure the secure handling of mobility data. The committee – which is composed of both private and public sector OMF members – also holds regular public meetings, which provide additional resources and an opportunity to discuss issues related to privacy and mobility data. Learn more [here](https://github.com/openmobilityfoundation/privacy-committee#welcome-to-the-privacy-security-and-transparency-committee). [Top][toc] From 34b9e33fe521afc2754e85607ecfbc203523d84f Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 4 Nov 2021 08:59:19 -0400 Subject: [PATCH 79/81] Revised Get Involved section --- README.md | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index af62e28c..08ef813a 100644 --- a/README.md +++ b/README.md @@ -87,17 +87,13 @@ All MDS compatible Provider feeds [must also expose](/provider/README.md#gbfs) a # Get Involved -To stay up to date on MDS releases, meetings, and events, please **subscribe to the [mds-announce](https://groups.google.com/a/groups.openmobilityfoundation.org/forum/#!forum/mds-announce) mailing list** and read our **[Community Wiki](https://github.com/openmobilityfoundation/mobility-data-specification/wiki)**. +To stay up to date on MDS, please **subscribe to the [mds-announce](https://groups.google.com/a/groups.openmobilityfoundation.org/g/mds-announce) mailing list** for general updates, the **[wg-mds](https://groups.google.com/a/groups.openmobilityfoundation.org/g/wg-mds) mailing list** for Working Group details and meetings, and read our **[Community Wiki](https://github.com/openmobilityfoundation/mobility-data-specification/wiki)**. -The Mobility Data Specification is an open source project with all development taking place on GitHub. Comments and ideas can be shared by [starting a discussion](https://github.com/openmobilityfoundation/mobility-data-specification/discussions), [creating an issue](https://github.com/openmobilityfoundation/mobility-data-specification/issues), and specific changes can be suggested by [opening a pull request](https://github.com/openmobilityfoundation/mobility-data-specification/pulls). Before contributing, please review our OMF [CONTRIBUTING page](https://github.com/openmobilityfoundation/governance/blob/main/CONTRIBUTING.md) and our [CODE OF CONDUCT page](https://github.com/openmobilityfoundation/governance/blob/main/CODE_OF_CONDUCT.md) to understand guidelines and policies for participation . +The Mobility Data Specification is an open source project with all development taking place on GitHub and public meetings through our [MDS Working Group](https://github.com/openmobilityfoundation/mobility-data-specification/wiki/MDS-Working-Group). Comments and ideas can be shared by [starting a discussion](https://github.com/openmobilityfoundation/mobility-data-specification/discussions), [creating an issue](https://github.com/openmobilityfoundation/mobility-data-specification/issues), suggesting changes with [a pull request](https://github.com/openmobilityfoundation/mobility-data-specification/pulls), and attending meetings. Before contributing, please review our OMF [CONTRIBUTING](https://github.com/openmobilityfoundation/governance/blob/main/CONTRIBUTING.md) and [CODE OF CONDUCT](https://github.com/openmobilityfoundation/governance/blob/main/CODE_OF_CONDUCT.md) pages to understand guidelines and policies for participation. -You can learn more about the polices, methodologies, and tools in the MDS ecosystem in the [Mobility Data Management State of Practice](https://github.com/openmobilityfoundation/privacy-committee/blob/main/products/state-of-the-practice.md) wiki. To help cities put the right privacy policies in place, the OMF [Privacy, Security, and Transparency Committee](https://github.com/openmobilityfoundation/privacy-committee) has created a comprehensive best-practices document called the [MDS Privacy Guide for Cities](https://github.com/openmobilityfoundation/governance/raw/main/documents/OMF-MDS-Privacy-Guide-for-Cities.pdf). +**Read our [How to Get Involved in the Open Mobility Foundation](https://www.openmobilityfoundation.org/how-to-get-involved-in-the-open-mobility-foundation/) blog post for more detail and an overview of how the OMF is organized.** -You can also get involved in development by joining the [MDS Working Group](https://github.com/openmobilityfoundation/mobility-data-specification/wiki/MDS-Working-Group). The working group maintains the OMF GitHub repositories and works through issues and pull requests. To receive relevant emails and calendar invites for meetings, please sign up for the [MDS Mailing List](https://groups.google.com/a/openmobilityfoundation.org/g/wg-mds). - -You can view info about current and past releases, the public OMF calendar, and review planning calls in the [wiki](https://github.com/openmobilityfoundation/mobility-data-specification/wiki). - -For questions about MDS please contact by email at [info@openmobilityfoundation.org](mailto:info@openmobilityfoundation.org) or [on our website](https://www.openmobilityfoundation.org/get-in-touch/). Media inquiries to [media@openmobilityfoundation.org](mailto:media@openmobilityfoundation.org). +For other questions about MDS or media inquiries please contact the OMF directly [on our website](https://www.openmobilityfoundation.org/get-in-touch/). ## Membership From a3e8a327d053780b8b8c0c42cbed9790b78ace2c Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 4 Nov 2021 09:19:42 -0400 Subject: [PATCH 80/81] Language pass on homepage --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 08ef813a..f2218813 100644 --- a/README.md +++ b/README.md @@ -19,13 +19,13 @@ # About -The Mobility Data Specification (**MDS**), a project of the [Open Mobility Foundation](http://www.openmobilityfoundation.org) (OMF), is a set of Application Programming Interfaces (APIs) focused on dockless e-scooters, bicycles, mopeds and carshare. Inspired by projects like [GTFS](https://developers.google.com/transit/gtfs/reference/) and [GBFS](https://github.com/NABSA/gbfs), the goals of MDS are to provide a standardized way for municipalities or other regulatory agencies to ingest, compare and analyze data from mobility service providers, and to give municipalities the ability to express regulation in machine-readable formats. +The Mobility Data Specification (**MDS**), a project of the [Open Mobility Foundation](http://www.openmobilityfoundation.org) (**OMF**), is a set of Application Programming Interfaces (APIs) focused on shared mobility services such as dockless scooters, bicycles, mopeds, and carshare, and inspired by projects like [GTFS](https://developers.google.com/transit/gtfs/reference/) and [GBFS](https://github.com/NABSA/gbfs). MDS is a digital tool that helps cities better manage transportation in the public right of way, standardizing communication and data-sharing between cities and private mobility providers, allowing cities to share and validate policy digitally, and enabling vehicle management and better outcomes for residents. -**MDS** helps cities interact with companies who operate dockless scooters, bicycles, mopeds and carshare in the public right-of-way. MDS is a key piece of digital infrastructure that supports the effective implementation of mobility policies in cities around the world. For a high level overview, see the [About MDS](https://www.openmobilityfoundation.org/about-mds/) page on the OMF website. +**MDS** is a key piece of digital infrastructure that supports the effective implementation of mobility policies in cities around the world. For a high level overview and visuals, see the [About MDS](https://www.openmobilityfoundation.org/about-mds/) page on the OMF website. ![MDS Main Logo](https://i.imgur.com/AiUedl3.png) -**MDS** is an open-source project. It was originally created by the [Los Angeles Department of Transportation](http://ladot.io) (LADOT). In November 2019, stewardship of MDS and the ownership of this repository were transferred to the Open Mobility Foundation. GitHub automatically redirects any links to this repository in the `CityOfLosAngeles` organization to the `openmobilityfoundation` instead. MDS continues to be used by LADOT and [many other municipalities](#cities-using-mds). +**MDS** is an open-source project originally created by the [Los Angeles Department of Transportation](http://ladot.io) (LADOT). In November 2019, stewardship of MDS and the ownership of this repository were transferred to the [Open Mobility Foundation](http://www.openmobilityfoundation.org). GitHub automatically redirects any links to this repository from the `CityOfLosAngeles` organization to the `openmobilityfoundation` instead. MDS continues to be used by LADOT and [many other municipalities](#cities-using-mds) and companies. [Top][toc] @@ -192,7 +192,7 @@ How cities use MDS depends on a variety of factors: their transportation goals, A list of use cases is useful to show what's possible with MDS, to list what other cities are accomplishing with the data, to see many use cases up front for privacy considerations, and to use for policy discussions and policy language. More details and examples can be seen on the [OMF website](https://www.openmobilityfoundation.org/whats-possible-with-mds/) and our [Wiki Database](https://github.com/openmobilityfoundation/governance/wiki/MDS-Use-Cases). -Please [let us know](https://www.openmobilityfoundation.org/get-in-touch/) if you have recommended updates or use cases to add. +Please [let us know](https://docs.google.com/forms/d/e/1FAIpQLScrMPgeb1TKMYCjjKsJh3y1TPTJO8HR_y1NByrf1rDmTEJS7Q/viewform) if you have recommended updates or use cases to add. [Top][toc] From b687433a0831363f3736aad491f6a79e9396b9a3 Mon Sep 17 00:00:00 2001 From: Michael Schnuerle <1285077+schnuerle@users.noreply.github.com> Date: Thu, 4 Nov 2021 09:24:09 -0400 Subject: [PATCH 81/81] Update release date --- ReleaseNotes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ReleaseNotes.md b/ReleaseNotes.md index f9e5d9c5..d93c3d45 100644 --- a/ReleaseNotes.md +++ b/ReleaseNotes.md @@ -1,6 +1,6 @@ ## 1.2.0 -> Release Candidate submitted 2021-09-29 +> Released: 2021-11-04 > [Release Plan](https://github.com/openmobilityfoundation/governance/wiki/Release-1.2.0)