Feature/image in alerts

gtfs-realtime/proto/gtfs-realtime.proto

@@ -647,6 +647,11 @@ message Alert {
 
   optional SeverityLevel severity_level = 14 [default = UNKNOWN_SEVERITY];
 
+  // List of TranslatedImage to be displayed along the alert text. Used to explain visually the alert effect of a detour, station closure, etc. The image must enhance the understanding of the alert. Any essential information communicated within the image must also be contained in the alert text.
+  // The following types of images are discouraged : image containing mainly text, marketing or branded images that add no additional information. 
+  // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future.
+  repeated TranslatedImage image = 15; 
+
   // The extensions namespace allows 3rd-party developers to extend the
   // GTFS Realtime Specification in order to add and evaluate new features
   // and modifications to the spec.
@@ -906,6 +911,56 @@ message TranslatedString {
   extensions 9000 to 9999;
 }
 
+// An internationalized image containing per-language versions of a URL linking to an image
+// along with meta information
+// Only one of the images from a message will be retained by consumers. The resolution proceeds
+// as follows:
+// 1. If the UI language matches the language code of a translation,
+//    the first matching translation is picked.
+// 2. If a default UI language (e.g., English) matches the language code of a
+//    translation, the first matching translation is picked.
+// 3. If some translation has an unspecified language code, that translation is
+//    picked.
+// NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future.
+message TranslatedImage {
+  message LocalizedImage {
+    // String containing a fully qualified URL linking to an image
+    // The image linked needs to be less than 500kB. 
+    required string url = 1;
+
+    // A UTF-8 string describing the appearance of the linked image (e.g., in case the image can't be displayed
+    // or the user can't see the image for accessibility reasons). See the HTML spec for alt image text - https://html.spec.whatwg.org/#alt.
+    optional string alternative_text = 2;
+
+    // IANA media type as to specify the type of image to be displayed. 
+    // The type must start with "image/"
+    required string media_type = 3;
+
+    // BCP-47 language code. Can be omitted if the language is unknown or if
+    // no i18n is done at all for the feed. At most one translation is
+    // allowed to have an unspecified language tag.
+    optional string language = 4;
+
+
+    // The extensions namespace allows 3rd-party developers to extend the
+    // GTFS Realtime Specification in order to add and evaluate new features and
+    // modifications to the spec.
+    extensions 1000 to 1999;
+
+    // The following extension IDs are reserved for private use by any organization.
+    extensions 9000 to 9999;
+  }
+  // At least one localized image must be provided.
+  repeated LocalizedImage localized_image = 1;
+
+  // The extensions namespace allows 3rd-party developers to extend the
+  // GTFS Realtime Specification in order to add and evaluate new features and
+  // modifications to the spec.
+  extensions 1000 to 1999;
+
+  // The following extension IDs are reserved for private use by any organization.
+  extensions 9000 to 9999;
+}
 
 // Describes the physical path that a vehicle takes when it's not part of the (CSV) GTFS,
 // such as for a detour. Shapes belong to Trips, and consist of a sequence of shape points.

gtfs-realtime/spec/en/reference.md

@@ -336,6 +336,7 @@ An alert, indicating some sort of incident in the public transit network.
 | **tts_header_text** | [TranslatedString](#message-translatedstring) | Optional | One | Text containing the alert's header to be used for text-to-speech implementations. This field is the text-to-speech version of header_text. It should contain the same information as header_text but formatted such that it can read as text-to-speech (for example, abbreviations removed, numbers spelled out, etc.) |
 | **tts_description_text** | [TranslatedString](#message-translatedstring) | Optional | One | Text containing a description for the alert to be used for text-to-speech implementations. This field is the text-to-speech version of description_text. It should contain the same information as description_text but formatted such that it can be read as text-to-speech (for example, abbreviations removed, numbers spelled out, etc.) |
 | **severity_level** | [SeverityLevel](#enum-severitylevel) | Optional | One | Severity of the alert. |
+| **image** | [TranslatedImage](#message-translatedimage) | Optional | Many | List of TranslatedImage to be displayed along the alert text. Used to explain visually the alert effect of a detour, station closure, etc. The image should enhance the understanding of the alert and must not be the only location of essential information. The following types of images are discouraged : image containing mainly text, marketing or branded images that add no additional information. <br><br>**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. |
 
 ## _enum_ Cause
 
@@ -502,11 +503,32 @@ An internationalized message containing per-language versions of a snippet of te
 
 A localized string mapped to a language.
 
+| _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ |
+|------------------|------------|----------------|-------------------|-------------------|
+| **text** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Required | One | A UTF-8 string containing the message. |
+| **language** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Conditionally required | One | BCP-47 language code. Can be omitted if the language is unknown or if no internationalization is done at all for the feed. At most one translation is allowed to have an unspecified language tag - if there is more than one translation, the language must be provided. |
+
+## _message_ TranslatedImage
+
+An internationalized message containing per-language versions of an image. One of the images from a message will be picked up. The resolution proceeds as follows: If the UI language matches the language code of a translation, the first matching translation is picked. If a default UI language (e.g., English) matches the language code of a translation, the first matching translation is picked. If some translation has an unspecified language code, that translation is picked.
+
+**Caution:** this message is still **experimental**, and subject to change. It may be formally adopted in the future.
+
 #### Fields
 
 | _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ |
 |------------------|------------|----------------|-------------------|-------------------|
-| **text** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Required | One | A UTF-8 string containing the message. |
+| **localized_image** | [LocalizedImage](#message-localizedimage) | Required | Many | At least one localized image must be provided. |
+
+## _message_ LocalizedImage
+
+A localized image URL mapped to a language.
+
+| _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ |
+|------------------|------------|----------------|-------------------|-------------------|
+| **url** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Required | One | String containing a fully qualified URL linking to an image. The image linked needs to be less than 500kB. |
+| **alternative_text** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | Text describing the appearance of the linked image if the image can't be displayed or the user can't see the image for accessiblity reasons |
+| **media_type** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Required | One | IANA media type as to specify the type of image to be displayed. The type must start with "image/" |
 | **language** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Conditionally required | One | BCP-47 language code. Can be omitted if the language is unknown or if no internationalization is done at all for the feed. At most one translation is allowed to have an unspecified language tag - if there is more than one translation, the language must be provided. |
 
 ## _message_ Shape