Skip to content

GBFS Go Implementation Rewrite #177

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 25 commits into
base: master
Choose a base branch
from

Conversation

DanielKerger
Copy link
Contributor

This Pull Request introduces a rewrite of the GBFS Go implementation, designed to provide full support for GBFS v2.3 and v3.0, v3.1RC, and v3.1RC2 specifications. The previous codebase has been completely replaced due to incompatibilities with current GBFS standards and insufficient type safety across different Feeds and specification versions.

Major Update: This rewrite adds complete support for GBFS v2.3, GBFS v3.1RC, and GBFS v3.1RC2, which were previously missing from the Go implementation, while maintaining compatibility with v3.0.

Key Motivations for the Rewrite:

  • The previous implementation lacked support for GBFS v2.3, which is widely used in production environments
  • The previous implemementation lacked support for GBFS v3.1RC and v3.1RC2, which are the latest versions of the GBFS specification
  • Redeclaration of identical types across different feeds. E.g. type Version string was declared in all Feeds, leading to redundancy and potential inconsistencies.
  • Codebase was not easy to use due to the lack of shared types and enums.
  • The codebase was not easily extensible for future GBFS versions
  • Non working examples.
  • Errors in the test implementation and data.

This rewrite establishes a solid foundation for GBFS processing in Go, with improved type safety, better maintainability, complete v2.3, v3.0, and v3.1RC, v3.1RC2 specification coverage, and a clear path for supporting future specification updates.

My changes include:

  • Complete GBFS v2.3, v3.0, v3.1RC, and v3.1RC2 Implementation: Added full support for GBFS v2.3, v3.0, v3.1RC, and v3.1RC2 specifications, including all feeds and data structures that were previously missing from the Go implementation
  • Multi-Version Support: Designed the architecture to seamlessly handle both v2.3, v3.0, v3.1RC, and v3.1RC2 specifications within a single, unified codebase
  • Shared Types: I have introduced shared types for common fields across v2.3, v3.0, v3.1RC, and v3.1RC2, ensuring consistency and reducing redundancy. Previously, the code had separate types for each version, leading to duplication and inconsistencies across the codebase.
  • Shared Enums: Enums that are common to both v2.3, v3.0, v3.1RC, and v3.1RC2 have been consolidated into shared enums, allowing for easier maintenance and updates. As for the shared types, the previous code had separate enums for each version, which made it difficult to manage changes and updates.
  • Updated Tests and Test Fixtures: The tests have been updated to reflect the new structure and functionality of the code, with test coverage for v2.3, v3.0, v3.1RC, and v3.1RC2 specifications. Test fixtures have been updated to include full examples with all fields (previously, some fields were missing as they are optional in the GBFS specification). This ensures that the tests cover all aspects of the GBFS feeds and validate the functionality of the new implementation and shared types. As this led to file changes outside of the direct Go code, I have also updated and extended the tests for TypeScript to ensure that the TypeScript code is still compatible with the new Go code. Tests for the Java and Rust implementations did not require changes, as they use test files directly from their own codebase.
  • Abstract Unmarshal Function: In the previous implementation, the unmarshal function was tightly coupled with specific feed types, making it difficult to handle different versions and types of feeds. The new implementation relies on the generic json unmarshalling capabilities of Go, allowing for more flexible and type-safe unmarshalling of GBFS feeds. This change simplifies the code and makes it easier to extend for future versions of GBFS.
  • New GBFS Example: A new example has been added to demonstrate the usage of the GBFS implementation with a sample feed. This example shows how to use it to unmarshal a GBFS feed and access its fields, providing a clear reference for developers on how to work with the new code.
  • Improved Documentation: Enhanced inline documentation and comments throughout the codebase to better explain the implementation details and usage patterns.

Breaking Changes: This is a breaking change that requires updating any existing code that depends on the previous GBFS Go implementation. However, this rewrite now provides GBFS v2.3, v3.1RC, and v3.1RC2 support that was entirely missing before, making it a significant upgrade for production use.

…re files with values respecting the minimum allowed timestamp for this field. No logic changes or new functionality introduced.
…ew station information and vehicle status data for typescript
- Added new vehicle_status and vehicle_types models based on v3.0.
- Updated test fixtures for gbfs.json, gbfs_versions.json, geofencing_zones.json, manifest.json, and system_information.json to reflect changes in versioning and TTL.
- Introduced new test fixtures for vehicle availability, vehicle status for carsharing and micromobility, and updated pricing plans.
- Removed deprecated system_pricing_plans.json and adjusted vehicle_status.json to align with new structure.
- Updated all relevant JSON files to use version "3.1-RC2" and adjusted TTL values accordingly.
…chemas to allow all dateTimes that are iso 8601 comlient

^
(\d{4}(-\d{2}(-\d{2})?)?|\d{8})         # Date: YYYY or YYYY-MM or YYYY-MM-DD or YYYYMMDD
T
(
  (\d{2}:\d{2}(:\d{2}(\.\d+)?)?) |      # Extended time: hh:mm, hh:mm:ss, hh:mm:ss.sss
  (\d{2}:\d{2}(\.\d+)?) |               # Extended time: hh:mm.mmm
  (\d{2}(\.\d+)?) |                     # Extended time: hh.hhh
  (\d{2}(\d{2}(\d{2}(\.\d+)?)?)?)       # Basic time: hhmm, hhmmss, hhmmss.sss
)
(Z|[+-]\d{2}(:?\d{2})?)?                # Optional timezone: Z or ±hh:mm or ±hhmm
$
- Changed version from 3.1-RC2 to 3.1-RC across multiple JSON files.
- Adjusted TTL values in various files, setting some to 0 and others to specific values.
- Updated geofencing zones to set ride_through_allowed to false for specific zones.
- Added new files for version 3.1-RC2, including gbfs.json, gbfs_versions.json, geofencing_zones.json, manifest.json, and others.
- Introduced new station information files for physical and virtual stations with detailed attributes.
- Added vehicle availability and status files for carsharing and micromobility vehicles.
- Included comprehensive vehicle types with detailed specifications and assets.
- Deleted obsolete test file for GBFS v3.1-RC1.
- Created new test file for GBFS v3.1-RC2 with updated schema paths and test functions.
- Updated station_information model to include city field and data structure.
- Removed unused fields from system_pricing_plans model.
- Updated vehicle_types model to reference v3.0 vehicle_types.
- Added new models for GBFS v3.1-RC2 including gbfs, gbfs_versions, geofencing_zones, manifest, station_status, system_alerts, system_information, system_pricing_plans, system_regions, vehicle_availability, vehicle_status, and vehicle_types.
- Ensured all new models inherit from their respective v3.1-RC counterparts.
…ions

- Removed redundant schema loading and validation functions from gbfsv30_test.go, gbfsv31-RC.go, and gbfsv31-RC2.go.
- Replaced calls to specific load and validate functions with a unified approach across all test files.
- Improved code readability and maintainability by reducing duplication in test implementations.
@richfab richfab requested review from davidgamez and Alessandro100 and removed request for davidgamez August 4, 2025 13:26
@richfab
Copy link
Contributor

richfab commented Aug 4, 2025

Hello @DanielKerger,

Thank you very much for this significant open source contribution 🙏

cc @davidgamez @emmambd for the next steps.

Thanks,
Fabien (MobilityData)

@richfab richfab requested a review from emmambd August 4, 2025 13:31
@davidgamez
Copy link
Member

Hi @DanielKerger,

Thanks for this contribution! 🚀 This is a large PR with many changes, and since our team has limited capacity at the moment, it may take us some time to review it thoroughly. We want to ensure that we give it the attention it deserves, so we appreciate your patience while we review it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants