[CHANGE REQUEST] clear communication in TOMP API description about asset.rentalUrl* deep links

[zerwuff]

API Version

1.3.1 and above

Summary

Hi, id like to hear the strategy about currently deprecated deeplink urls for IOS / Anndroid in asset type in TOMP, since we would like to provide them to our customers.

Expected Behavior

Clear communication in the API what will happen with the asset deeplinks.

Current Behavior

Beginning from at least version 1.3.1, this asset deeplink urls are marked as deprecated but seem to be present until elephant. Is this a bug or strategy to remove the URLs ?
If removing is the strategy, where are the URLS are moving to ?

Possible Solution

Depending on the strategy communicate the following

1. Remove "deprecated" flag or
2. Provide new attribute in existing model to be more compliant with GBFS or
3. Communicate strategy where those URLs are moving to - in TOMP generally or in GBFS ? At least the note "deep-linking option from GBFS 2.0. Only added to be consistent with GBFS 2.0" is not easy to understand since GBFS provides newer versions

Steps to Reproduce

Check the API Model in branch 1.3.1 to elephant

  asset:
     type: object
     required:
       - id
         description: The date and time when any rental of the vehicle must be completed. The vehicle must be returned and made available for the next user by this time. If this field is empty, it indicates that the vehicle is available indefinitely.
           This field SHOULD be published by carsharing or other mobility systems where vehicles can be booked in advance for future travel.
         format: date-time

       rentalUrl:
         type: string
         description: deep-linking option from GBFS+. Only added to be consistent with GBFS 2.0
         format: URL
         example: https://www.rentmyfreebike.com/app?sid=1234567890
         deprecated: true <------
       rentalUrlAndroid:
         type: string
         description: deep-linking option from GBFS 2.0. Only added to be consistent with GBFS 2.0
         format: URL
         example: https://www.rentmyfreebike.com/app?sid=1234567890&platform=android
         deprecated:  true <------
       rentalUrlIOS:
         type: string
         description: deep-linking option from GBFS 2.0. Only added to be consistent with GBFS 2.0
         format: URL
         example: https://www.rentmyfreebike.com/app?sid=1234567890&platform=ios
         deprecated:  true <------ 

Context (Environment)

We have MaaS Partners, that only use /available-assets url and jump out to our own apps. So they are only light integrating, and use booking etc from our apps. Therefore, we need to communicate the deep link URLs.
We are curious to know if the urls are completely removed out of TOMP, so we strive to GBFS for this use case.

Detailed Description

What is the strategy behind this attributes ? Are they are going to move, to be deleted ? I see the deprecation mark since 1.3.1 and
are curious about how long this state will last. If they are finally removed, we will look more into GBFS as a solution for this.

Possible Implementation

Depending on the strategy

1. Remove deprecated flag in the API or
2. Provide new attribute in existing API model or
3. at least communicate strategy where those URLs are moving to (e.g. GBFS) and provide clear decision for us which API (TOMP / GBFS) to use for delivering deep link urls

[edwinvandenbelt]

Good question. They are depricated, because they are inherited from GBFS. In v2.0 (Elephant), we want to remove direct relations, and will refer in the asset only to the external source & identifier. I'm still struggling with the fact if we shouldn't incorporate common attributes, and make it clear that they should contain the same value as the source attribute, but it always ends up in 2 versions of the truth. On the other hand, it makes it easier for the consumers, since they don't need to access the external source.

[zerwuff]

Yeah, either hard cut - remove all attributes from assets and externalize to GBFS (i wonder if this discussion is still ongoing or if there is any trend for this yet ?) or going the path of duplicating attributes.
In general, this issue should be decided at least till elephant, so we clearly know how to communicate this in the api and find ways for our partners to implement against TOMP.
With 1.5 we are. fine, we would provide the deprecated attributes, but for 2.0 we would need our customers to implement TOMP & GBFS meshup to provide the asset attributes if the plan is really to remove the attributes in elephant.