From 4093c3659f6cdd8889b551f195f607d6e1a16807 Mon Sep 17 00:00:00 2001 From: Emma Blue <90632321+emmambd@users.noreply.github.com> Date: Wed, 16 Apr 2025 12:23:13 -0400 Subject: [PATCH 1/4] Update README.md --- README.md | 38 ++++++++++++++------------------------ 1 file changed, 14 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index 00ab677e7..6f95bbd2e 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,7 @@ To search feeds easily, you can download [the CSV spreadsheet](https://files.mob ## Browsing and Consuming The Spreadsheet -If you're only interested in browsing the feeds or pulling all the latest URLs, [download the CSV](https://files.mobilitydatabase.org/feeds_v2.csv). This is the second version of the spreadsheet, which includes all feeds available on the Mobility Database, as well as automatically extracted features and feed status information. You can cross reference IDs from the Mobility Database, TransitFeeds and Transitland with [this ID map spreadsheet](https://docs.google.com/spreadsheets/d/1Q96KDppKsn2khdrkraZCQ7T_qRSfwj7WsvqXvuMt4Bc/edit?resourcekey#gid=1787149399). +If you're only interested in browsing the feeds or pulling all the latest URLs, [download the CSV](https://files.mobilitydatabase.org/feeds_v2.csv). This is the second version of the spreadsheet, which includes all feeds available on the Mobility Database, as well as automatically extracted features and feed status information. The legacy CSV will be deprecated and unavailable for use after July 30th, 2025. You can cross reference IDs from the Mobility Database, TransitFeeds and Transitland with [this ID map spreadsheet](https://docs.google.com/spreadsheets/d/1Q96KDppKsn2khdrkraZCQ7T_qRSfwj7WsvqXvuMt4Bc/edit?resourcekey#gid=1787149399). If you are consuming the spreadsheet, we recommend downloading a new version every time you use it, since the `latest.url` is occasionally updated to match any changes made to the provider and subdivision name within the feed file. @@ -46,44 +46,31 @@ Contains the tools to search, add and update the feeds. The `tools.operations` m Contains the JSON schemas used to validate the feeds in the integration tests. -### Spreadsheet - -The JSON files are added to the pipeline for https://github.com/MobilityData/mobility-feed-api and combined with other feeds that are automatically imported into https://github.com/MobilityData/mobility-feed-api from sources outside the catalogs repo. [The Canonical GTFS Schedule Validator](https://gtfs-validator.mobilitydata.org/) is run on all feeds, and then the results are exported as a [spreadsheet](https://files.mobilitydatabase.org/feeds_v2.csv). - -## GTFS Schedule Spreadsheet Schema +#### GTFS Schedule JSON Schema |Field Name|Type|Presence|Definition| |-|-|-|-| | mdb_source_id | Unique ID | System generated | Unique numerical identifier for the feed. | | data_type | Enum| Required| The data format that the feed uses: `gtfs`.| -| features | Array of Enums | Optional | An array of features that the feed includes based on https://gtfs.org/getting-started/features/overview/. This list is automatically extracted from [the Canonical GTFS Schedule Validator](https://gtfs-validator.mobilitydata.org/). -| status | Enum | Optional | Describes status of the feed. Should be one of: `active` and `inactive` statuses are updated based on the [feedServiceWindowStart and feedServiceWindowEnd values extracted from the Canonical GTFS Schedule Validator](https://gtfs-validator.mobilitydata.org/rules.html#JsonReportFeedInfo-type).| +| features | Array of Enums | Optional | An array of features which can be any of: | +| status | Enum | Optional | Describes status of the feed. Should be one of: Feed is assumed to be `active` if status is not explicitly provided.| | is_official | Enum | Optional | Flag indicating if the source comes from the agency itself or not. Feed's is_official flag is assumed to be `False` if it is not explicitly provided.| |redirect| Object | Optional | When a feed is deprecated by a provider and replaced with a new URL, redirect information is provided to point to the new feed.| | - id | String | Optional | New feed ID that replaces the current feed that is out of date or no longer maintained by the provider. | | - comment | Optional | Optional | comment to explain redirect if needed (e.g new aggregate feed) | |location| Object | Required |Contains | -| - country_code | Text |Required | ISO 3166-1 alpha-2 code designating the country where the feed service is located based on the number of stops. When multiple countries are included, the country with the most stops is displayed. For a list of valid codes [see here](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes). | -| - subdivision_name | Text |Optional | ISO 3166-2 subdivision name designating the subdivision (e.g province, state, region) where the feed service is located based on the number of stops. When multiple subdivisions are included, the one with the most stops is displayed. For a list of valid names [see here](https://unece.org/trade/uncefact/unlocode-country-subdivisions-iso-3166-2).| -| - municipality | Text |Optional | Municipality in which the feed service is located based on the number of stops. When there are multiple municipalities, the one with the most stops is displayed | -| - bounding_box | Object|System generated | Bounding box of the feed based on stops. Contains `minimum_latitude`, `maximum_latitude`, `minimum_longitude`, `maximum_longitude` and `extracted_on` fields. If the bounding box information displays as "null", you can check any potential feed errors with [the GTFS validator](https://github.com/MobilityData/gtfs-validator). | +| - country_code | Text |Required | ISO 3166-1 alpha-2 code designating the country where the feed service is located. For a list of valid codes [see here](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes). | +| - subdivision_name | Text |Optional | ISO 3166-2 subdivision name designating the subdivision (e.g province, state, region) where the feed service is located. For a list of valid names [see here](https://unece.org/trade/uncefact/unlocode-country-subdivisions-iso-3166-2).| +| - municipality | Text |Optional | Primary municipality in which the feed service is located.| +| - bounding_box | Object|System generated | Bounding box of the feed when it was first added to the catalog. Contains `minimum_latitude`, `maximum_latitude`, `minimum_longitude`, `maximum_longitude` and `extracted_on` fields. If the bounding box information displays as "null", you can check any potential feed errors with [the GTFS validator](https://github.com/MobilityData/gtfs-validator). | | --minimum_latitude | Latitude | System generated | The minimum latitude for the feed's bounding box. | --maximum_latitude | Latitude | System generated | The maximum latitude for the feed's bounding box. | --minimum_longitude | Longitude | System generated | The minimum longitude for the feed's bounding box. -| --maximum_longitude | Longitude | System generated | The maximum longitude for the feed's bounding box. -| --extracted_on | Date and Time | System generated | The date and timestamp the bounding box was extracted on in UTC. -| provider | Text | Required | A commonly used name for the transit provider included in the feed. | -| feed_contact_email | Text | Optional | The contact information for the data producer of the feed, discovered via feed_info.feed_contact_email in the feed, the provider's website, or the Mobility Database contributor form. | -| name | Text |Optional | An optional description of the feed, e.g to specify if the feed is an aggregate of multiple providers, or which network is represented by the feed. | -|urls| Object | Required | Contains URLs associated with the feed in the `direct_download_url`, `latest`, and `license` fields. | -|- direct_download |URL|Optional | URL that automatically opens the feed. | -|- authentication_type |Enum|Optional | The **authentication_type** field defines the type of authentication required to access the URL. Valid values for this field are: When not provided, the authentication type is assumed to be **0**.| -|- authentication_info_url | URL| Conditionally required | If authentication is required, the **authentication_info_url** field contains a URL to a human-readable page describing how the authentication should be performed and how credentials can be created. This field is required for `authentication_type=1` and `authentication_type=2`. | -|- api_key_parameter_name |Text|Conditionally required | The **api_key_parameter_name** field defines the name of the parameter to pass in the URL to provide the API key. This field is required for `authentication_type=1` and `authentication_type=2`. | +@@ -79,7 +83,7 @@ Contains the JSON schemas used to validate the feeds in the integration tests. | - latest | URL | System generated | A stable URL for the latest dataset of a feed. | |- license |URL| Optional | The license information for the direct download URL. | -## GTFS Realtime Spreadsheet Schema +#### GTFS Realtime Schema |Field Name|Type|Presence|Definition| |-|-|-|-| @@ -107,7 +94,10 @@ The JSON files are added to the pipeline for https://github.com/MobilityData/mob |- api_key_parameter_name |Text|Conditionally required | The **api_key_parameter_name** field defines the name of the parameter to pass in the URL to provide the API key. This field is required for `authentication_type=1` and `authentication_type=2`. | |- license_url |URL| Optional | The license information for `direct_download_url`. -In [the CSV](https://share.mobilitydata.org/catalogs-csv), realtime feeds include the location metadata of their static reference when provided. + +### Spreadsheet + +The JSON files are added to the pipeline for https://github.com/MobilityData/mobility-feed-api and combined with other feeds that are automatically imported from sources outside the catalogs repo. [The Canonical GTFS Schedule Validator](https://gtfs-validator.mobilitydata.org/) is run on all feeds, and then the results are exported as a [spreadsheet](https://files.mobilitydatabase.org/feeds_v2.csv). [Learn more about the spreadsheet schema here](https://github.com/MobilityData/mobility-feed-api/blob/main/docs/SpreadsheetSchemaV2.md). ## Installation From 8de2c462c36bbc9dffc5eaf9afc5bc0683fd46a9 Mon Sep 17 00:00:00 2001 From: Emma Blue <90632321+emmambd@users.noreply.github.com> Date: Wed, 16 Apr 2025 14:35:28 -0400 Subject: [PATCH 2/4] Update README.md --- README.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 6f95bbd2e..84f864155 100644 --- a/README.md +++ b/README.md @@ -66,9 +66,16 @@ Contains the JSON schemas used to validate the feeds in the integration tests. | --minimum_latitude | Latitude | System generated | The minimum latitude for the feed's bounding box. | --maximum_latitude | Latitude | System generated | The maximum latitude for the feed's bounding box. | --minimum_longitude | Longitude | System generated | The minimum longitude for the feed's bounding box. -@@ -79,7 +83,7 @@ Contains the JSON schemas used to validate the feeds in the integration tests. -| - latest | URL | System generated | A stable URL for the latest dataset of a feed. | -|- license |URL| Optional | The license information for the direct download URL. | +| --maximum_longitude | Longitude | System generated | The maximum longitude for the feed's bounding box. +| --extracted_on | Date and Time | System generated | The date and timestamp the bounding box was extracted on in UTC. +| provider | Text | Required | A commonly used name for the transit provider included in the feed. | +| feed_contact_email | Text | Optional | The contact information for the data producer of the feed, discovered via feed_info.feed_contact_email in the feed, the provider's website, or the Mobility Database contributor form. | +| name | Text |Optional | An optional description of the feed, e.g to specify if the feed is an aggregate of multiple providers, or which network is represented by the feed. | +|urls| Object | Required | Contains URLs associated with the feed in the `direct_download_url`, `latest`, and `license` fields. | +|- direct_download |URL|Optional | URL that automatically opens the feed. | +|- authentication_type |Enum|Optional | The **authentication_type** field defines the type of authentication required to access the URL. Valid values for this field are: When not provided, the authentication type is assumed to be **0**.| +|- authentication_info_url | URL| Conditionally required | If authentication is required, the **authentication_info_url** field contains a URL to a human-readable page describing how the authentication should be performed and how credentials can be created. This field is required for `authentication_type=1` and `authentication_type=2`. | +|- api_key_parameter_name |Text|Conditionally required | The **api_key_parameter_name** field defines the name of the parameter to pass in the URL to provide the API key. This field is required for `authentication_type=1` and `authentication_type=2`. | #### GTFS Realtime Schema From 12eaff3e5e527c2757423bd81e613109e2d78c65 Mon Sep 17 00:00:00 2001 From: Emma Blue <90632321+emmambd@users.noreply.github.com> Date: Wed, 16 Apr 2025 14:35:59 -0400 Subject: [PATCH 3/4] Update README.md --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index 84f864155..0c0698b83 100644 --- a/README.md +++ b/README.md @@ -73,10 +73,13 @@ Contains the JSON schemas used to validate the feeds in the integration tests. | name | Text |Optional | An optional description of the feed, e.g to specify if the feed is an aggregate of multiple providers, or which network is represented by the feed. | |urls| Object | Required | Contains URLs associated with the feed in the `direct_download_url`, `latest`, and `license` fields. | |- direct_download |URL|Optional | URL that automatically opens the feed. | +| - latest | URL | System generated | A stable URL for the latest dataset of a feed. | +|- license |URL| Optional | The license information for the direct download URL. | |- authentication_type |Enum|Optional | The **authentication_type** field defines the type of authentication required to access the URL. Valid values for this field are: When not provided, the authentication type is assumed to be **0**.| |- authentication_info_url | URL| Conditionally required | If authentication is required, the **authentication_info_url** field contains a URL to a human-readable page describing how the authentication should be performed and how credentials can be created. This field is required for `authentication_type=1` and `authentication_type=2`. | |- api_key_parameter_name |Text|Conditionally required | The **api_key_parameter_name** field defines the name of the parameter to pass in the URL to provide the API key. This field is required for `authentication_type=1` and `authentication_type=2`. | + #### GTFS Realtime Schema |Field Name|Type|Presence|Definition| From cbab58b8eb642f75c9038191f7379f3e54e09508 Mon Sep 17 00:00:00 2001 From: Emma Blue <90632321+emmambd@users.noreply.github.com> Date: Wed, 16 Apr 2025 14:46:38 -0400 Subject: [PATCH 4/4] Revert json schema documentation to be exactly what it was before #829 --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 0c0698b83..d737f6259 100644 --- a/README.md +++ b/README.md @@ -73,11 +73,11 @@ Contains the JSON schemas used to validate the feeds in the integration tests. | name | Text |Optional | An optional description of the feed, e.g to specify if the feed is an aggregate of multiple providers, or which network is represented by the feed. | |urls| Object | Required | Contains URLs associated with the feed in the `direct_download_url`, `latest`, and `license` fields. | |- direct_download |URL|Optional | URL that automatically opens the feed. | -| - latest | URL | System generated | A stable URL for the latest dataset of a feed. | -|- license |URL| Optional | The license information for the direct download URL. | |- authentication_type |Enum|Optional | The **authentication_type** field defines the type of authentication required to access the URL. Valid values for this field are: When not provided, the authentication type is assumed to be **0**.| |- authentication_info_url | URL| Conditionally required | If authentication is required, the **authentication_info_url** field contains a URL to a human-readable page describing how the authentication should be performed and how credentials can be created. This field is required for `authentication_type=1` and `authentication_type=2`. | |- api_key_parameter_name |Text|Conditionally required | The **api_key_parameter_name** field defines the name of the parameter to pass in the URL to provide the API key. This field is required for `authentication_type=1` and `authentication_type=2`. | +| - latest | URL | System generated | A stable URL for the latest dataset of a feed. | +|- license |URL| Optional | The license information for the direct download URL. | #### GTFS Realtime Schema