From acf0e6a78430a4d4e81b4e73a18df31a6812054f Mon Sep 17 00:00:00 2001 From: Fabien Richard-Allouard Date: Thu, 4 Jan 2024 09:13:07 +0100 Subject: [PATCH] Improve readability (#582) * Improve readability * replace < and > with < and > for display. * all fields have a definition --------- Co-authored-by: Tom <1955774+tdelmas@users.noreply.github.com> --- gbfs.md | 99 +++++++++++++++++++++++++++++---------------------------- 1 file changed, 50 insertions(+), 49 deletions(-) diff --git a/gbfs.md b/gbfs.md index 6b2b2b94..45e733c8 100644 --- a/gbfs.md +++ b/gbfs.md @@ -54,7 +54,7 @@ This section defines terms that are used throughout this document. * JSON - (JavaScript Object Notation) is a lightweight format for storing and transporting data. This document uses many terms defined by the JSON standard, including field, array, and object. (https://www.w3schools.com/js/js_json_datatypes.asp) * Field - In JSON, a name/value pair consists of a field name (in double quotes), followed by a colon, followed by a value. (https://www.w3schools.com/js/js_json_syntax.asp) * GeoJSON - GeoJSON is a format for encoding a variety of geographic data structures. (https://geojson.org/) -* REQUIRED - The field MUST be included in the dataset, and a value MUST be provided in that field for each record. +* REQUIRED - The field MUST be included in the dataset, and a value MUST be provided in that field for each record. (A required field inside an OPTIONAL Object is only required when the Object is present.) * OPTIONAL - The field MAY be omitted from the dataset. If an OPTIONAL column is included, some of the entries in that field MAY be empty strings. An omitted field is equivalent to a field that is empty. * Conditionally REQUIRED - The field or file is REQUIRED under certain conditions, which are outlined in the field or file description. Outside of these conditions, this field or file is OPTIONAL. @@ -188,9 +188,10 @@ The data returned by the near-realtime endpoints `station_status.json` and `vehi It is RECOMMENDED that all GBFS data sets be offered under an open data license. Open data licenses allow consumers to freely use, modify, and share GBFS data for any purpose in perpetuity. Licensing of GBFS data provides certainty to GBFS consumers, allowing them to integrate GBFS data into their work. All GBFS data sets SHOULD specify a license using the `license_id` field with an [SPDX identifier](https://spdx.org/licenses/) or by using the `license_url` field with a URL pointing to a custom license in `system_information.json`. See the GBFS repo for a [comparison of a subset of standard licenses](https://github.com/MobilityData/gbfs/blob/master/data-licenses.md). ## Field Types - +* Object - A JSON object, with its keys defined under it. * Array - A JSON element consisting of an ordered sequence of zero or more values. * Array<Type> - A JSON element consisting of an ordered sequence of zero or more values of the specified sub-type. +* Array<Object> - A JSON array of objects, with its keys defined under it. * Boolean - One of two possible values, `true` or `false`. Boolean values MUST be JSON booleans, not strings (meaning `true` or `false`, not `"true"` or `"false"`). *(as of v2.0)* * Country code - Country code following the [ISO 3166-1 alpha-2 notation](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). * Date - A date in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) Complete Date Extended Format: YYYY-MM-DD. Example: `2019-09-13` for September 13th, 2019. @@ -287,7 +288,7 @@ The `gbfs.json` discovery file SHOULD represent a single system or geographic ar Field Name | REQUIRED | Type | Defines ---|---|---|--- -`feeds` | Yes | Array | An array of all of the feeds that are published by this auto-discovery file. Each element in the array is an object with the keys below. +`feeds` | Yes | Array<Object> | An array of all of the feeds that are published by this auto-discovery file. \-  `name` | Yes | String | Key identifying the type of feed this is. The key MUST be the base file name defined in the spec for the corresponding feed type ( `system_information` for `system_information.json` file, `station_information` for `station_information.json` file). \-  `url` | Yes | URL | URL for the feed. Note that the actual feed endpoints (urls) may not be defined in the `file_name.json` format. For example, a valid feed endpoint could end with `station_info` instead of `station_information.json`. @@ -322,9 +323,9 @@ The following fields are all attributes within the main `data` object for this f Field Name | REQUIRED | Type | Defines ---|---|---|--- -`datasets` | Yes | Array | An array of objects, each containing the keys below. +`datasets` | Yes | Array<Object> | An array of `datasets` produced by a publisher. \- `system_id` | Yes | ID | The `system_id` from `system_information.json` for the corresponding data set(s). -\- `versions` | Yes | Array | Contains one object, as defined below, for each of the available versions of a feed. The array MUST be sorted by increasing MAJOR and MINOR version number. +\- `versions` | Yes | Array<Object> | Contains one object for each of the available versions of a feed. The array MUST be sorted by increasing MAJOR and MINOR version number.   \-`version` | Yes | String | The semantic version of the feed in the form `X.Y`.   \-`url` | Yes | URL | URL of the corresponding `gbfs.json` endpoint. @@ -374,7 +375,7 @@ The following fields are all attributes within the main `data` object for this f Field Name | REQUIRED | Type | Defines ---|---|---|--- -`versions` | Yes | Array | Contains one object, as defined below, for each of the available versions of a feed. The array MUST be sorted by increasing MAJOR and MINOR version number. +`versions` | Yes | Array<Object> | Contains one object, for each of the available versions of a feed. The array MUST be sorted by increasing MAJOR and MINOR version number. \-  `version` | Yes | String | The semantic version of the feed in the form `X.Y`. \-  `url` | Yes | URL | URL of the corresponding gbfs.json endpoint. @@ -407,7 +408,7 @@ The following fields are all attributes within the main `data` object for this f Field Name | REQUIRED | Type | Defines ---|---|---|--- `system_id` | Yes | ID | This is a globally unique identifier for the vehicle share system. Each distinct system or geographic area in which vehicles are operated MUST have its own unique `system_id`. It is up to the publisher of the feed to guarantee uniqueness and MUST be checked against existing `system_id` fields in [systems.csv](https://github.com/MobilityData/gbfs/blob/master/systems.csv) to ensure this. This value is intended to remain the same over the life of the system.

System IDs SHOULD be recognizable as belonging to a particular system as opposed to random strings - for example, `bcycle_austin` or `biketown_pdx`. -`languages`
*(added of v3.0-RC)* | Yes | Array | List of languages used in translated strings. Each element in the list must be of type Language. +`languages`
*(added of v3.0-RC)* | Yes | Array<Language> | List of languages used in translated strings. `name`
*(as of v3.0-RC)* | Yes | Array<Localized String> | Name of the system to be displayed to customers. `opening_hours`
*(added in v3.0-RC)*| Yes | String | Hours and dates of operation for the system in [OSM opening_hours](https://wiki.openstreetmap.org/wiki/Key:opening_hours) format. *(added in v3.0-RC)* `short_name` *(as of v3.0-RC)* | OPTIONAL | Array<Localized String> | Abbreviation for a system. @@ -425,23 +426,23 @@ Field Name | REQUIRED | Type | Defines `license_url` | Conditionally REQUIRED
*(as of v3.0-RC)* | URL | REQUIRED if the dataset is provided under a customized license. A fully qualified URL of a page that defines the license terms for the GBFS data for this system. Do not specify a `license_url` if `license_id` is specified. If the `license_id` and `license_url` fields are blank or omitted, this indicates that the feed is provided under the [Creative Commons Universal Public Domain Dedication](https://creativecommons.org/publicdomain/zero/1.0/legalcode). *(as of v3.0-RC)* `attribution_organization_name`
*(added in v3.0-RC)* | OPTIONAL | Array<Localized String> | If the feed license requires attribution, name of the organization to which attribution should be provided. `attribution_url`
*(added in v3.0-RC)* | OPTIONAL | URL | URL of the organization to which attribution should be provided. -`brand_assets`
*(added in v2.3)* | OPTIONAL | Object | An object where each key defines one of the items listed below. -\- `brand_last_modified`
*(added in v2.3)* | Conditionally REQUIRED | Date | REQUIRED if `brand_assets` object is defined. Date that indicates the last time any included brand assets were updated or modified. +`brand_assets`
*(added in v2.3)* | OPTIONAL | Object | Object containing branding information about the system. +\- `brand_last_modified`
*(added in v2.3)* | REQUIRED | Date | Date that indicates the last time any included brand assets were updated or modified. \- `brand_terms_url`
*(added in v2.3)* | OPTIONAL | URL | A fully qualified URL pointing to the location of a page that defines the license terms of brand icons, colors, or other trademark information. This field MUST NOT take the place of `license_url` or `license_id`. -\- `brand_image_url`
*(added in v2.3)* | Conditionally REQUIRED | URL | REQUIRED if `brand_assets` object is defined. A fully qualified URL pointing to the location of a graphic file representing the brand for the service. File MUST be in SVG V1.1 format and MUST be either square or round. +\- `brand_image_url`
*(added in v2.3)* | REQUIRED | URL | A fully qualified URL pointing to the location of a graphic file representing the brand for the service. File MUST be in SVG V1.1 format and MUST be either square or round. \- `brand_image_url_dark`
*(added in v2.3)* | OPTIONAL | URL | A fully qualified URL pointing to the location of a graphic file representing the brand for the service for use in dark mode applications. File MUST be in SVG V1.1 format and MUST be either square or round. \- `color`
*(added in v2.3)* | OPTIONAL | String | Color used to represent the brand for the service expressed as a 6 digit hexadecimal color code in the form #000000. -`terms_url`
*(as of v3.0-RC)* | OPTIONAL | Array<Localized URL> | A fully qualified URL pointing to the terms of service (also often called "terms of use" or "terms and conditions") for the service. -`terms_last_updated`
*(added in v2.3)* |Conditionally REQUIRED | Date | REQUIRED if `terms_url` is defined. The date that the terms of service provided at `terms_url` were last updated. -`privacy_url`
*(as of v3.0-RC)*| OPTIONAL | Array<Localized URL> | A fully qualified URL pointing to the privacy policy for the service. -`privacy_last_updated`
*(added in v2.3)* |Conditionally REQUIRED | Date | REQUIRED if `privacy_url` is defined. The date that the privacy policy provided at `privacy_url` was last updated. +`terms_url`
*(as of v3.0-RC)* | OPTIONAL | Array<Localized String> | A fully qualified URL pointing to the terms of service (also often called "terms of use" or "terms and conditions") for the service. +`terms_last_updated`
*(added in v2.3)* | REQUIRED | Date | The date that the terms of service provided at `terms_url` were last updated. +`privacy_url`
*(as of v3.0-RC)*| OPTIONAL | Array<Localized String> | A fully qualified URL pointing to the privacy policy for the service. +`privacy_last_updated`
*(added in v2.3)* | REQUIRED | Date | The date that the privacy policy provided at `privacy_url` was last updated. `rental_apps` | OPTIONAL | Object | Contains rental app information in the `android` and `ios` JSON objects. \- `android` | OPTIONAL | Object | Contains rental app download and app discovery information for the Android platform in the `store_uri` and `discovery_uri` fields. See [examples](#deep-links-examples) of how to use these fields and [supported analytics](#analytics). - - `store_uri` | Conditionally REQUIRED | URI | URI where the rental Android app can be downloaded from. Typically this will be a URI to an app store, such as Google Play. If the URI points to an app store, the URI SHOULD follow Android best practices so the viewing app can directly open the URI to the native app store app instead of a website.

If a `rental_uris`.`android` field is populated, then this field is REQUIRED.

See the [Analytics](#analytics) section for how viewing apps can report the origin of the deep link to rental apps.

Example value: `https://play.google.com/store/apps/details?id=com.example.android` - - `discovery_uri` | Conditionally REQUIRED | URI | URI that can be used to discover if the rental Android app is installed on the device (for example, using [`PackageManager.queryIntentActivities()`](https://developer.android.com/reference/android/content/pm/PackageManager.html#queryIntentActivities)). This intent is used by viewing apps to prioritize rental apps for a particular user based on whether they already have a particular rental app installed.

REQUIRED if a `rental_uris`.`android` field is populated.

Example value: `com.example.android://` + - `store_uri` | REQUIRED | URI | URI where the rental Android app can be downloaded from. Typically this will be a URI to an app store, such as Google Play. If the URI points to an app store, the URI SHOULD follow Android best practices so the viewing app can directly open the URI to the native app store app instead of a website.

See the [Analytics](#analytics) section for how viewing apps can report the origin of the deep link to rental apps.

Example value: `https://play.google.com/store/apps/details?id=com.example.android` + - `discovery_uri` | REQUIRED | URI | URI that can be used to discover if the rental Android app is installed on the device (for example, using [`PackageManager.queryIntentActivities()`](https://developer.android.com/reference/android/content/pm/PackageManager.html#queryIntentActivities)). This intent is used by viewing apps to prioritize rental apps for a particular user based on whether they already have a particular rental app installed.

Example value: `com.example.android://` \- `ios` | OPTIONAL | Object | Contains rental information for the iOS platform in the `store_uri` and `discovery_uri` fields. See [examples](#deep-links-examples) of how to use these fields and [supported analytics](#analytics). - - `store_uri` | Conditionally REQUIRED | URI | URI where the rental iOS app can be downloaded from. Typically this will be a URI to an app store, such as the Apple App Store. If the URI points to an app store, the URI SHOULD follow iOS best practices so the viewing app can directly open the URI to the native app store app instead of a website.

If a `rental_uris`.`ios` field is populated, then this field is REQUIRED.

See the [Analytics](#analytics) section for how viewing apps can report the origin of the deep link to rental apps.

Example value: `https://apps.apple.com/app/apple-store/id123456789` - - `discovery_uri` | Conditionally REQUIRED | URI | URI that can be used to discover if the rental iOS app is installed on the device (for example, using [`UIApplication canOpenURL:`](https://developer.apple.com/documentation/uikit/uiapplication/1622952-canopenurl?language=objc)). This intent is used by viewing apps to prioritize rental apps for a particular user based on whether they already have a particular rental app installed.

REQUIRED if a `rental_uris`.`ios` field is populated.

Example value: `com.example.ios://` + - `store_uri` | REQUIRED | URI | URI where the rental iOS app can be downloaded from. Typically this will be a URI to an app store, such as the Apple App Store. If the URI points to an app store, the URI SHOULD follow iOS best practices so the viewing app can directly open the URI to the native app store app instead of a website.

See the [Analytics](#analytics) section for how viewing apps can report the origin of the deep link to rental apps.

Example value: `https://apps.apple.com/app/apple-store/id123456789` + - `discovery_uri` | REQUIRED | URI | URI that can be used to discover if the rental iOS app is installed on the device (for example, using [`UIApplication canOpenURL:`](https://developer.apple.com/documentation/uikit/uiapplication/1622952-canopenurl?language=objc)). This intent is used by viewing apps to prioritize rental apps for a particular user based on whether they already have a particular rental app installed.

Example value: `com.example.ios://` **Example:** @@ -524,16 +525,16 @@ REQUIRED of systems that include information about vehicle types in the `vehicle Field Name | REQUIRED | Type | Defines ---|---|---|--- -`vehicle_types` | Yes | Array | Array that contains one object per vehicle type in the system as defined below. +`vehicle_types` | Yes | Array<Object> | Contains one object per vehicle type in the system. \- `vehicle_type_id` | Yes | ID | Unique identifier of a vehicle type. See [Field Types](#field-types) above for ID field requirements. \- `form_factor` | Yes | Enum | The vehicle's general form factor.

Current valid values are:
\- `rider_capacity`
*(added in v2.3)* | OPTIONAL | Non-negative integer | The number of riders (driver included) the vehicle can legally accommodate. \- `cargo_volume_capacity`
*(added in v2.3)* | OPTIONAL | Non-negative integer | Cargo volume available in the vehicle, expressed in liters. For cars, it corresponds to the space between the boot floor, including the storage under the hatch, to the rear shelf in the trunk. \- `cargo_load_capacity`
*(added in v2.3)* | OPTIONAL | Non-negative integer | The capacity of the vehicle cargo space (excluding passengers), expressed in kilograms. \- `propulsion_type` | Yes | Enum | The primary propulsion type of the vehicle.

Current valid values are:
This field was inspired by, but differs from the propulsion types field described in the [Open Mobility Foundation Mobility Data Specification](https://github.com/openmobilityfoundation/mobility-data-specification/blob/main/general-information.md#propulsion-types). -\- `eco_labels`
*(as of v3.0-RC2)* | OPTIONAL | Array | Vehicle air quality certificate. Official anti-pollution certificate, based on the information on the vehicle's registration certificate, attesting to its level of pollutant emissions based on a defined standard. In Europe, for example, it is the European emission standard. The aim of this measure is to encourage the use of the least polluting vehicles by allowing them to drive during pollution peaks or in low emission zones.

Each element in the array is an object with the keys below. - \-  `country_code`
*(added in v2.3)*| Conditionally REQUIRED | Country code | REQUIRED if `eco_labels` is defined. Country where the `eco_sticker` applies. - \-  `eco_sticker`
*(added in v2.3)* | Conditionally REQUIRED | String | REQUIRED if `eco_labels` is defined. Name of the eco label. The name must be written in lowercase, separated by an underscore.

Example of `eco_sticker` in Europe : +\- `eco_labels`
*(as of v3.0-RC2)* | OPTIONAL | Array<Object> | Vehicle air quality certificate. Official anti-pollution certificate, based on the information on the vehicle's registration certificate, attesting to its level of pollutant emissions based on a defined standard. In Europe, for example, it is the European emission standard. The aim of this measure is to encourage the use of the least polluting vehicles by allowing them to drive during pollution peaks or in low emission zones. + \-  `country_code`
*(added in v2.3)*| REQUIRED | Country code | Country where the `eco_sticker` applies. + \-  `eco_sticker`
*(added in v2.3)* | REQUIRED | String | Name of the eco label. The name must be written in lowercase, separated by an underscore.

Example of `eco_sticker` in Europe : \- `max_range_meters` | Conditionally REQUIRED | Non-negative float | If the vehicle has a motor (as indicated by having a value other than `human` in the `propulsion_type` field), this field is REQUIRED. This represents the furthest distance in meters that the vehicle can travel without recharging or refueling when it has the maximum amount of energy potential (for example, a full battery or full tank of gas). \- `name`
*(as of v3.0-RC)* | OPTIONAL | Array<Localized String> | The public name of this vehicle type. \- `vehicle_accessories`
*(added in v2.3)* | OPTIONAL | Array | Description of accessories available in the vehicle. These accessories are part of the vehicle and are not supposed to change frequently. Current valid values are: @@ -548,10 +549,10 @@ Field Name | REQUIRED | Type | Defines \- `rated_power`
*(added in v2.3)* | OPTIONAL | Non-negative Integer | The rated power of the motor for this vehicle type in watts. \- `default_reserve_time`
*(added in v2.3)* | Conditionally REQUIRED
*(as of v3.0-RC)* | Non-negative Integer | REQUIRED if `reservation_price_per_min` or `reservation_price_flat_rate` are defined. Maximum time in minutes that a vehicle can be reserved before a rental begins. When a vehicle is reserved by a user, the vehicle remains locked until the rental begins. During this time the vehicle is unavailable and cannot be reserved or rented by other users. The vehicle status in `vehicle_status.json` MUST be set to `is_reserved = true`. If the value of `default_reserve_time` elapses without a rental beginning, the vehicle status MUST change to `is_reserved = false`. If `default_reserve_time` is set to `0`, the vehicle type cannot be reserved. \- `return_constraint`
*(as of v2.3)*| OPTIONAL | Enum | The conditions for returning the vehicle at the end of the rental.

Current valid values are: