[FEATURE REQUEST] Using the QR-Code as asset identifier

[matt-wirtz]

Is your feature request related to a problem? Please describe.

Currently assets are identified by their asset ID. For vehicle types like bikes it is very common to print the asset ID somewhere on the bike. Another option is to use a QR-code printed on the vehicle. The QR-code usually contains an URL to allow lookup via the web or a deep linking into the providers app. For that purpose the URL usually contains the asset ID somewhere. Since there is no standard describing how the asset ID should be represented in the QR-code it's TO specific how the asset ID is coded into the QR-code.
To make use of the QR-code in the booking process it would be very convenient for the MP to use the complete QR-code as an identifier for the asset. So the MP would not need to decode the QR-code. He only needs to identify to which TO the offer/booking request needs to be addressed.

Urgency

Major (the TOMP API works as advertised but this is really necessary to implement), because it makes use of the QR-Code in a very convenient manner for the MP.

Additional context

Describe the solution you'd like

Allow to use the QR-Code standard as externalAssetReference (v2.0). Then the complete QR-Code can be used in the offers/booking endpoints to identify the asset. Right now only the following standards can be used:
TOMP, GBFS, NeTEx, CDS, OSDM, AMADEUS, GTFS, OCPI, TRAVELER_CHARACTERISTICS

Describe alternatives you've considered

• An alternative approach would be to define a standard of how the asset-ID should be coded within a QR-Code. Since a standard doesn't seem to exist right now it would take a very long time until all TOs would adhere to this.

• Another approach would be that the TO specifies the structure of his QR-Code and exposes this via the endpoint e.g. /operator/information. A regex which extracts the asset ID from the QR-code would be sufficient too. The MP can use that info to parse the QR-Code and extract the asset ID.

Possible Implementation

[itziweb]

I can give you some input how we deal with this in the field of charging stations, where every connector has a CR-Code as well.
Usually it leads to an asset specific landing page of the CPO (=TO), where informations and (direct) access/payment options are offered.
As there is a standard for the ID-Format (EVSE ID), it is possible for other Apps, to extract the public id from any link.

E.g. https://chge.at/035?evseid=AT*WSG*ELNW*035*2
"35" is the CPO Station ID while "ATWSGELNW0352" is the global id. This format is detected by the native Apps of the MSPs.

If we want to avoid the necessity to manage an URL additional key, this would be possible ideas:

1. Recommend a standard for a global identifiers of mobility assets, so it can be detected universally in deeplinks.
2. The MP manages regex patterns for the connected TO to get the TO specific asset id. If an aggregation platform is used, this can take over the id resolving.

[edwinvandenbelt]

Hello Roman! What's against the idea of just supplying the QR code in the useAssets field? In that case, we should extend the list of known external standards with ISO15118 (which is the standard where the EV ID is part of, is this correct?) Or should we just refer to EV-ID as type (alongside uninterpreted QR)?

So, detailed, we'll extend in the 'meta' part the externalTypes, so you publish to the outer world that you expect an EV_ID in your 'useAssets' field.

 externalType:
      type: string
      description: this field must be used when adressing other standards for exchanging 'static' data (Level 1 MaaS)
      enum: [GBFS, GTFS, NeTEx, OSDM_Offline, IXSI5, APDS, BAR_CODE, QR_CODE, EV_ID]

example:
{ "method": "POST", "/planning/offers/", "status": "IMPLEMENTED", "externalType": "EV_ID", "useAssets": ["QR_CODE_CONTENT"] }

I'm not really convinced what to put in the 'useAssets'. Should we prescribe some possibilities? QR_CODE_BINARY, QR_CODE_HEX, QR_CODE_BASE64, etc?

This is really generic, and the complete URL (bar code or QR code content) should be placed in the useAssets. The interpretation can be done by the TO. This might even make a specific type as EV_ID superfluous. It can be represented as a bar code or a QR code. No need to publish information to interpret the content.

[marius-at-atb]

Hi guys, this would be a great feature to have!
As well as supporting it directly in useAssets, perhaps a new endpoint can be considered?

E.g. both Voi and Tier have endpoints where you can get a vehicle from either the vehicleCode or id. Having something similar in TOMP can solve a use case we currently have at Entur and AtB.

GET /asset?qrCode={qrCode}
GET /asset?vehicleCode={vehicleCode}
GET /asset?id={id}

Response: asset

In order to select the right TO in the MP, we can also add a new field such as qrRegExps in systemInformation (should probably be an array, as there might be more than one variation used by the same TO).

This could be used both to extract the vehicleCode and whether a given qrCode belongs to a TO. However, if the endpoint accepts the entire qrCode, the MP does not need to extract the vehicleCode. So if desired, this could simplify the reg exp to just return true or false whether a qrCode belongs to the given TO.

Note: using ?param={param} instead of /{param} because qrCode is a URL

Update: perhaps vehicleCode should instead be called assetCode? 🤔