Add images.txt + agency logo

gtfs/spec/en/reference.md

@@ -182,6 +182,19 @@ The following example demonstrates how a field value would appear in a comma-del
 
 ## Field Definitions
 
+### brands.txt
+
+File: **Conditionally Required**
+
+Primary key (`brand_id`)
+
+|  Field Name | Type | Presence | Description |
+|  ------ | ------ | ------ | ------ |
+|  `brand_id` | Unique ID | **Conditionally Required** | Identifies a transit brand which is often synonymous with a transit agency. Note that in some cases, such as when a single agency operates multiple separate services, agencies and brands are distinct. This document uses the term "agency" in place of "brand". A dataset may contain data from multiple agencies. <br><br>Conditionally Required:<br>- **Required** when the dataset contains data for multiple transit agencies. <br>- Recommended otherwise. |
+|  `brand_terms_url` |  URL | **Conditionally Forbidden** | A fully qualified URL pointing to the location of a page that defines the license terms of the brand icons or other trademark information. <br><br>It is recommended that the terms permit feed consumers, without taking additional actions, to use the logo in reference to the agency's services broadly throughout their products, provided an attribution citing these terms is visible to users somewhere in these products. <br><br> Consumers SHOULD respect standard HTTP caching headers when fetching this file. <br><br>Conditionally Forbidden:<br>- **Forbidden** when `agency_brand_image_url` is not set <br>- Optional otherwise |
+|  `brand_image_url` | URL | Optional | A fully qualified URL pointing to the location of a graphic file representing the agency's brand. The file SHOULD have a transparent background and contain a version of the brand image optimized to fill square or round formats larger than 16x16. Consumers SHOULD respect standard HTTP caching headers when fetching this file. File MUST be in SVG V1.1 format and MUST be either square or round. <br><br>A data consumer MUST store the brand image on their own servers to avoid direct traffic from end user devices to the agencies web servers. |
+|  `brand_image_url_dark` | URL  | Optional | A fully qualified URL pointing to the location of a graphic file representing the agency's brand for the service for use in dark mode applications. The file SHOULD have a transparent background and contain a version of the brand image optimized to fill square or round formats larger than 16x16. Consumers SHOULD respect standard HTTP caching headers when fetching this file. File MUST be in SVG V1.1 format and MUST be either square or round. <br><br>A data consumer MUST store the brand image on their own servers to avoid direct traffic from end user devices to the agencies web servers. |
+
 ### agency.txt
 
 File: **Required**
@@ -194,6 +207,7 @@ Primary key (`agency_id`)
 |  `agency_name` | Text | **Required** | Full name of the transit agency. |
 |  `agency_url` | URL | **Required** | URL of the transit agency. |
 |  `agency_timezone` | Timezone | **Required** | Timezone where the transit agency is located. If multiple agencies are specified in the dataset, each must have the same `agency_timezone`. |
+|  `brand_id` | Foreign ID referencing `brands.brand_id` | Optional | Brand for the specified agency. |
 |  `agency_lang` | Language code | Optional | Primary language used by this transit agency. Should be provided to help GTFS consumers choose capitalization rules and other language-specific settings for the dataset. |
 |  `agency_phone` | Phone number | Optional | A voice telephone number for the specified agency. This field is a string value that presents the telephone number as typical for the agency's service area. It may contain punctuation marks to group the digits of the number. Dialable text (for example, TriMet's "503-238-RIDE") is permitted, but the field must not contain any other descriptive text. |
 |  `agency_fare_url` | URL | Optional | URL of a web page where a rider can purchase tickets or other fare instruments for that agency, or a web page containing information about that agency's fares. |
@@ -235,6 +249,7 @@ Primary key (`route_id`)
 |  ------ | ------ | ------ | ------ |
 |  `route_id` | Unique ID | **Required** | Identifies a route. |
 |  `agency_id` | Foreign ID referencing `agency.agency_id` | **Conditionally Required** | Agency for the specified route.<br><br>Conditionally Required:<br>- **Required** if multiple agencies are defined in [agency.txt](#agency). <br>- Recommended otherwise. |
+|  `brand_id` | Foreign ID referencing `brands.brand_id` | Optional | Brand for the specified route. |
 |  `route_short_name` | Text | **Conditionally Required** | Short name of a route. Often a short, abstract identifier (e.g., "32", "100X", "Green") that riders use to identify a route. Both `route_short_name` and `route_long_name` may be defined.<br><br>Conditionally Required:<br>- **Required** if `routes.route_long_name` is empty.<br>- Recommended if there is a brief service designation. This should be the commonly-known passenger name of the service, and should be no longer than 12 characters. |
 |  `route_long_name` | Text | **Conditionally Required** | Full name of a route. This name is generally more descriptive than the `route_short_name` and often includes the route's destination or stop. Both `route_short_name` and `route_long_name` may be defined.<br><br>Conditionally Required:<br>- **Required** if `routes.route_short_name` is empty.<br>- Optional otherwise. |
 |  `route_desc` | Text | Optional | Description of a route that provides useful, quality information. Should not be a duplicate of `route_short_name` or `route_long_name`. <hr> _Example: "A" trains operate between Inwood-207 St, Manhattan and Far Rockaway-Mott Avenue, Queens at all times. Also from about 6AM until about midnight, additional "A" trains operate between Inwood-207 St and Lefferts Boulevard (trains typically alternate between Lefferts Blvd and Far Rockaway)._ |
@@ -260,6 +275,7 @@ Primary key (`trip_id`)
 |  `route_id` | Foreign ID referencing `routes.route_id` | **Required** | Identifies a route. |
 |  `service_id` | Foreign ID referencing `calendar.service_id` or `calendar_dates.service_id` | **Required** | Identifies a set of dates when service is available for one or more routes. |
 |  `trip_id` | Unique ID | **Required** | Identifies a trip. |
+|  `brand_id` | Foreign ID referencing `brands.brand_id` | Optional | Brand for the specified trip. |
 |  `trip_headsign` | Text | Optional | Text that appears on signage identifying the trip's destination to riders. This field is recommended for all services with headsign text displayed on the vehicle which may be used to distinguish amongst trips in a route.<br><br> If the headsign changes during a trip, values for `trip_headsign` may be overridden by defining values in `stop_times.stop_headsign` for specific `stop_time`s along the trip. |
 |  `trip_short_name` | Text | Optional | Public facing text used to identify the trip to riders, for instance, to identify train numbers for commuter rail trips. If riders do not commonly rely on trip names, `trip_short_name` should be empty. A `trip_short_name` value, if provided, should uniquely identify a trip within a service day; it should not be used for destination names or limited/express designations. |
 |  `direction_id` | Enum | Optional | Indicates the direction of travel for a trip. This field should not be used in routing; it provides a way to separate trips by direction when publishing time tables. Valid options are: <br><br>`0` - Travel in one direction (e.g. outbound travel).<br>`1` - Travel in the opposite direction (e.g. inbound travel).<hr>*Example: The `trip_headsign` and `direction_id` fields may be used together to assign a name to travel in each direction for a set of trips. A [trips.txt](#tripstxt) file could contain these records for use in time tables:* <br> `trip_id,...,trip_headsign,direction_id` <br> `1234,...,Airport,0` <br> `1505,...,Downtown,1` |