š ļø How-to Upgrade to GBFS v3.0
Your GBFS v3.0 Implementation Starter Guide
We recently published a blog post to introduce GBFS v3.0 and why we think youāll love it. Now, with GBFS v3.0 officially part of the standard, we wanted to help kickstart your transition to v3.0! In this article you will see how changes look in v3.0 with examples of GBFS v3.0 feeds. If you havenāt reviewed the full specification already, you can read all about it here.
Letās not waste any time and get right to the details.
Versioning
First up, letās talk about versioning. Itās recommended that producers maintain the previous version of their feeds alongside the latest v3.0 feed for one year. This gives time for all consumers to migrate to the latest major version.
Producers should populateĀ gbfs_versions.jsonĀ with the supported versions (andĀ manifest.jsonĀ if applicable). They should also update theĀ systems.csvĀ catalog with the latest official version of their feeds.
To help with the migration to v3.0, we have worked with Entur to publish GBFS types in TypeScript (NPM package) and Java (Maven Central package). They are automatically generated from the official GBFS JSON Schemas. So when the specification changes, your data model evolves with it. You can find generator tools for many programming languages at json-schema.org.
gbfs_versions.json
{
"last_updated": "2023-07-17T13:34:13+02:00",
"ttl": 0,
"version": "3.0",
"data": {
"versions": [{
"version": "2.3",
"url": "https://www.example.com/gbfs/2/gbfs"
},
{
"version": "3.0",
"url": "https://www.example.com/gbfs/3/gbfs"
}
]}
}
Example of gbfs_versions.json listing the different versions of the same feed.
Protects Publishers & Riders
With GBFS v3.0, some changes were made to better protect the privacy of riders and publishers. Check out this table to see what the changes are and how they look now in v3.0
| Change | v2.3 and Below | v3.0 |
|---|---|---|
|
Static vehicle IDs compromised |
Vehicle IDs MUST be rotated after each rental to avoid unintentionally exposing private trip origins and destinations inĀ vehicles[ ].rental_uris (eg: com.example.ios://open.example.app/app?sid=952dcab50889) |
|
|
license_url (system_information.json) was optional.Ā |
license_id OR license_url (system_information.json) are now required. If both fields are blank or omitted, this indicates that the feed is provided under the Creative Commons Universal Public Domain Dedication. |
|
|
feed_contact_emailĀ (system_information.json) was optional. |
feed_contact_emailĀ (system_information.json) is now required. |
|
|
|
This new endpoint called manifest.jsonĀ is an index, required for publishers of feeds for multiple cities. |
Reduce Implementation Costs
GBFS was already an easy to use standard, but the community came together to make implementation even easier with GBFS v3.0.
Geofencing Made Simple
| Change | v2.3 and Below | v3.0 |
|---|---|---|
|
A clockwise arrangement of points defined the area enclosed by the polygon, while a counterclockwise order defined the area outside the polygon (right-hand rule). |
Global rules define restrictions that apply everywhere and specific rules are defined inside polygons. |
Fig. 1. Visualize the geofencing rules with the GBFS Validator.
In-line Translations
| Change | v2.3 and Below | v3.0 |
|---|---|---|
|
The whole dataset was duplicated for each supported language. |
A single dataset with in-line translations. |
system_pricing_plans.json
{
"last_updated": "2023-07-17T13:34:13+02:00",
"ttl": 0,
"version": "3.0",
"data": {
"plans": [{
"plan_id": "plan1",
"name": [
{
"text": "One-Way",
"language": "en"
},
{
"text": "Aller simple",
"language": "fr"
}
],
... more details about the pricing plan
}]
}
}
Example of system_pricing_plans.json listing in-line translations of a pricing plan name
Standardized Data Types
| Change | v2.3 and Below | v3.0 |
|---|---|---|
|
Timestamps were integers in POSIX time (eg:Ā 1706100760). |
Timestamps MUST be strings in RFC3339 format, (eg: 2024-01-24T12:52:40+01:00) |
|
|
IDs could contain special characters (eg: Ć©Ćp~1). |
IDs MUST be in the ASCII printable character range, space excluded, and SHOULD be restricted to A-Z, a-z, 0-9 and .@:/_- (eg: D9:N_c). |
|
|
Enum values could be of any case (eg: BICYCLE). |
Enum values MUST be lowercase (eg: bicycle). |
|
|
Opening hours were optional and defined in system_hours.json and system_calendar.json. |
Opening hours are required and defined in system_hours.json in the OpenStreetMap format |
|
|
Phone numbers were not standard (eg: 877-430-BIKE). |
Phone numbers MUST be in |
|
|
Prices in system_pricing_plans.json could be strings (eg: ā$1.50ā). |
Prices in system_pricing_plans.json MUST be Non-Negative Floats (eg: 1.50) |
The Spec is More Intuitive
Shared mobility isnāt just about bikes anymore and GBFS v3.0 reflects that by replacing the word ābikeā with āvehicleā. This change better reflects the use cases of GBFS today while still being broad enough to cover any future changes as well.
| Change | v2.3 and Below | v3.0 |
|---|---|---|
|
Endpoint was free_bikes_status.json. Previous field names: |
Endpoint is now vehicle_status.json. New field names: |
|
|
Previous field names and types: |
New field names and types: |
|
|
Previous field names: |
New field names: |
Improved Rider Experience
This major new change allows producers to add descriptions for vehicles, including their special features, how-tos, or any other information important to share with riders. It also adds the cargo bike and seated scooters form factors and warns users of a permanent shutdown of the service.
| Change | v2.3 and Below | v3.0 |
|---|---|---|
|
Vehicle types had no description. |
Vehicle types can have a free -form text description in vehicle_types[].description (eg: Extra comfortable seat). |
|
|
cargo_bicycle and scooter_seated form factors were not supported. |
cargo_bicycle and scooter_seated form factors are supported. scooter becomes scooter_standing. |
|
|
Data sources could become |
New field: |
You Can Upgrade to GBFS v3.0 Today
GBFS v3.0 is a more secure and intuitive version of the specification and you can implement these new changes now! You can also check out some examples of GBFS v3.0 feeds that have already been published: Check, ENTUR, Flamingo and TIER.
To further assist with the transition to v3.0, be sure to check out our recommended resources by going to the Implementation Guide for GBFS Producers. If you want to learn even more about the spec, click here.
If your v3.0 feed is ready to go, then make sure to paste your feed URL into the GBFS online validator and select version 3.0 to validate your new feed.
Use the GBFS Validator to validate your new v3.0 feed
Letās Keep Improving GBFS Together
To participate in discussions around GBFS and suggest changes and additions to the specification, join the public GBFS Slack channel and the Github repository!
Questions can be addressed to the community via the public GBFS Slack channel or to the Shared Mobility team at MobilityData: sharedmobility@mobilitydata.org.
