Icons and Brand Information

[mplsmitch]

What is the issue and why is it an issue?

Some consuming applications have expressed a need for Icons and/or other brand related information to represent the mobility services that they aggregate.

Please describe some potential solutions you have considered (even if they aren’t related to GBFS).

This data could be added to system_information.json. Here's a rough draft of what I'm thinking:

Field Name	REQUIRED	Type	Defines
icon_url_standard	Optional	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.
icon_url_dark	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.
brand_color	Optional	String	Color used to represent the service expressed as a 6 digit hexadecimal color code.
brand_terms_url	Optional	URL	A fully qualified URL pointing to the location of a page that defines the license terms of icons, colors or other trademark information. This field MUST NOT take the place of license_url or license_id

Example:

From Transit

Is your potential solution a breaking change?

• [ ] Yes
• [X] No
• [ ] Unsure

Questions:

• Would this meet the needs of GBFS consumers?
• Are there other shapes beyond round and square that should be considered?
• Are there other brand assets beyond icon and color that should be considered?
• Are there standard licenses that could be applied to trademarks or other brand materials via an ID like is done with the license_id field?

[kanagy]

Hi Mitch, thanks for bringing this up! Few suggestions:

• What do you think about wrapping all these in an object "branding" or "brand_assets"? Other than logically grouping it (and so make it easier to extend with more brand fields), it would make it clear that the whole group is optional. Then you could make icon_url_standard a required field (i.e. if brand assets are defined, we require at least the standard icon).
• What do you think about adding last_updated timestamp to the brand_assets? For consumer apps that bundle the assets with the app or manually handle the URLs (e.g. changing the format, converting to PNG, etc), this would be a good indication that the asset needs to be manually updated.
• In future proposals it would be useful to also have icons for different vehicle types (these typically appear on the map in bikesharing apps), e.g. a branded scooter icon, a bike icon, an electric bike icon. Any suggestions of where these should live? In system_information or in vehicle_types feed?
• I would suggest renaming icon_url_standard to logo_icon_url_standard or brand_icon_url_standard or app_icon_url_standard (and similar for dark version) to not confuse these with vehicle icons.

[mplsmitch]

Here's a revised version based on comments from @kanagy. In system_information.json there is a brand_assets object which contains the other fields. In vehicle_types.json there are two new fields added to the vehicle_types array, one for a standard vehicle icon and one for a dark mode vehicle icon.

system_information.json

Field Name	REQUIRED	Type	Defines
brand_assets	Optional	Object	An object where each key defines on of the items listed below
- brand_assets_last_updated	Conditionally REQUIRED	Timestamp	REQUIRED if brand_assets object is defined. Indicates the last time any included brand assets were updated.
- brand_icon_url_standard	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_icon_url_dark	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.
- brand_color	Optional	String	Color used to represent the service expressed as a 6 digit hexadecimal color code.
-brand_assets_terms_url	Optional	URL	A fully qualified URL pointing to the location of a page that defines the license terms of icons, colors or other trademark information. This field MUST NOT take the place of license_url or license_id

vehicle_types.json

Field Name	REQUIRED	Type	Defines
- vehicle_icon_url_standard	Optional	URL	A fully qualified URL pointing to the location of a branded graphic icon file to be used to represent this vehicle type on maps and in other applications. File MUST be in SVG V1.1 format and MUST be either square or round.
- vehicle_icon_url_dark	Optional	URL	A fully qualified URL pointing to the location of a branded graphic icon file to be used to represent this vehicle type when in dark mode on maps and in other applications . File MUST be in SVG V1.1 format and MUST be either square or round.

Example:

{
  "last_updated": 1609866247,
  "ttl": 0,
  "version": "3.0",
  "data": {
    "vehicle_types": [
      {
        "vehicle_type_id": "abc123",
        "form_factor": "bicycle",
        "propulsion_type": "human",
        "name": "Example Basic Bike",
        "vehicle_icon_standard": "https://www.example.com/assets/icon_bicycle_standard.svg", 
        "vehicle_icon_dark": "https://www.example.com/assets/icon_bicycle_dark.svg"
      },
      {
        "vehicle_type_id": "def456",
        "form_factor": "scooter",
        "propulsion_type": "electric",
        "name": "Example E-scooter V2",
        "max_range_meters": 12345,
        "vehicle_icon_standard": "https://www.example.com/assets/icon_escooter_standard.svg", 
        "vehicle_icon_dark": "https://www.example.com/assets/icon_escooter_dark.svg"
      }
    ]
  }
}

[petoc]

Maybe it is intentional, but I think some parameter names are too verbose and removing few prefixes and suffixes could clean it little bit. In case of last_updated timestamp, is it really that necessary? I think there are other options to check modification time, for example by checking HTTP header Last-Modified, before actual download. Otherwise, should not have other resources such timestamp too, like suggested icons for vehicle types? Just my opinion.

Here is parameter brand_assets with little cleanup, to consider:

{
  "brand_assets": {
    "icon_url": "https://www.example.com/assets/icon_system.svg",
    "icon_url_dark": "https://www.example.com/assets/icon_system_dark.svg",
    "color": "#ff0000",
    "terms_url": "https://www.example.com/assets/brand.pdf"
  }
}

and in case of vehicle_types.json, to follow other URL parameters in specifications it could contain _url part. Also parameters are in vehicle type section, so I think prefix vehicle_ should not be necessary.

{
  "vehicle_type_id": "abc123",
  "form_factor": "bicycle",
  "propulsion_type": "human",
  "name": "Example Basic Bike",
  "icon_url": "https://www.example.com/assets/icon_escooter.svg", 
  "icon_url_dark": "https://www.example.com/assets/icon_escooter_dark.svg"
}

What do you think?

[kanagy]

Simpler prefixes look good to me. For the Last-Modified timestamp:

• Should that be mentioined in the documentation for icon_url?
• Would that actually give the date of last time the iconchanged, or if provider has setup e.g. daily autmated releases, the last time the icon has released (which is not saying that it is dfferent now)?

[petoc]

Fair point about Last-Modified, in such case it would also change. Usually there is available also expiration date header, but it does not say it changed, too, just for how long it could be cached.

I am just not sure, if it is worth. If it is not easier for consumers to just download resource every release or if they decide not to bundle this file, just to cache it for some time when application would download it. SVG is textual format so it should be compressed significantly during transport, downloading it every time should not be a big issue, if that is concern.

I think it would complicate things for producers a little bit, they would need to manually track content changes, store timestamp along with image file (database or extra file) probably just for GBFS feeds.

Maybe also some other producers/consumers could provide their opinion on that and if the result would be need for such field, than maybe icon_checksum and icon_checksum_dark with file hash (crc32, md5, sha1, ...) could be solution. But again, even hash would not guarantee that file is actually different, in case of SVG, lets say, just element ID would be removed or changed, or few elements would be grouped, or editor would change metadata (version for example) or change order of elements without actually visually changing the icon, it would result in the new hash.

I am not strictly against such field and if it should be optional it will not hurt anyone I suppose.

[mplsmitch]

This issue has moved to PR #330. Please follow along there.