From d3d53fec0bb4f694b76837dd13f226b5307cdc12 Mon Sep 17 00:00:00 2001 From: Paul Swartz Date: Mon, 27 Apr 2020 11:29:54 -0400 Subject: [PATCH 01/29] feat: `direction_id` no longer experimental (#210) --- gtfs-realtime/proto/gtfs-realtime.proto | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/gtfs-realtime/proto/gtfs-realtime.proto b/gtfs-realtime/proto/gtfs-realtime.proto index a65f5397f..077bbc700 100644 --- a/gtfs-realtime/proto/gtfs-realtime.proto +++ b/gtfs-realtime/proto/gtfs-realtime.proto @@ -230,7 +230,7 @@ message TripUpdate { // stops in the trip are considered to be unspecified as well. // Neither arrival nor departure should be supplied. NO_DATA = 2; - + // The vehicle is operating a trip defined in GTFS frequencies.txt with exact_times = 0. // This value should not be used for trips that are not defined in GTFS frequencies.txt, // or trips in GTFS frequencies.txt with exact_times = 1. Trips containing StopTimeUpdates @@ -563,9 +563,7 @@ message TripDescriptor { optional string route_id = 5; // The direction_id from the GTFS feed trips.txt file, indicating the - // direction of travel for trips this selector refers to. This field is - // still experimental, and subject to change. It may be formally adopted in - // the future. + // direction of travel for trips this selector refers to. optional uint32 direction_id = 6; // The initially scheduled start time of this trip instance. @@ -666,8 +664,7 @@ message EntitySelector { optional TripDescriptor trip = 4; optional string stop_id = 5; // Corresponds to trip direction_id in GTFS trips.txt. If provided the - // route_id must also be provided. This field is still experimental, and - // subject to change. It may be formally adopted in the future. + // route_id must also be provided. optional uint32 direction_id = 6; // The extensions namespace allows 3rd-party developers to extend the From 270830c9cce471a3ce21dea9d3ae1f0fca041558 Mon Sep 17 00:00:00 2001 From: Guillaume Campagna Date: Tue, 28 Apr 2020 10:00:11 -0400 Subject: [PATCH 02/29] Add occupancy_percentage (#213) --- gtfs-realtime/proto/gtfs-realtime.proto | 9 +++++++++ gtfs-realtime/spec/en/reference.md | 4 +++- 2 files changed, 12 insertions(+), 1 deletion(-) diff --git a/gtfs-realtime/proto/gtfs-realtime.proto b/gtfs-realtime/proto/gtfs-realtime.proto index 077bbc700..fd653b7fe 100644 --- a/gtfs-realtime/proto/gtfs-realtime.proto +++ b/gtfs-realtime/proto/gtfs-realtime.proto @@ -393,6 +393,15 @@ message VehiclePosition { } optional OccupancyStatus occupancy_status = 9; + // A percentage value representing the degree of passenger occupancy of the vehicle. + // The values are represented as an integer without decimals. 0 means 0% and 100 means 100%. + // The value 100 should represent the total maximum occupancy the vehicle was designed for, + // including both seated and standing capacity, and current operating regulations allow. + // It is possible that the value goes over 100 if there are currently more passengers than what the vehicle was designed for. + // The precision of occupancy_percentage should be low enough that you can't track a single person boarding and alighting for privacy reasons. + // This field is still experimental, and subject to change. It may be formally adopted in the future. + optional uint32 occupancy_percentage = 10; + // 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. diff --git a/gtfs-realtime/spec/en/reference.md b/gtfs-realtime/spec/en/reference.md index 45e3620fe..e99cee767 100644 --- a/gtfs-realtime/spec/en/reference.md +++ b/gtfs-realtime/spec/en/reference.md @@ -213,6 +213,8 @@ Realtime positioning information for a given vehicle. | **timestamp** | [uint64](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | Moment at which the vehicle's position was measured. In POSIX time (i.e., number of seconds since January 1st 1970 00:00:00 UTC). | | **congestion_level** | [CongestionLevel](#enum-congestionlevel) | Optional | One | | _**occupancy_status**_ | _[OccupancyStatus](#enum-occupancystatus)_ | _Optional_ | One | The degree of passenger occupancy of the vehicle.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.| +| **occupancy_percentage** | [uint32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | A percentage value representing the degree of passenger occupancy of the vehicle. The value 100 should represent total the maximum occupancy the vehicle was designed for, including both seating and standing capacity, and current operating regulations allow. It's not impossible that the value goes over 100 if there are currently more passenger than the vehicle was designed for. The precision of precision should be low enough that you can't track a single person boarding and alighting for privacy reasons.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | + ## _enum_ VehicleStopStatus @@ -364,7 +366,7 @@ To specify a single trip instance, in many cases a `trip_id` by itself is suffic * If the trip lasts for more than 24 hours, or is delayed such that it would collide with a scheduled trip on the following day, then `start_date` is required in addition to `trip_id` * If the `trip_id` field can't be provided, then `route_id`, `direction_id`, `start_date`, and `start_time` must all be provided -In all cases, if `route_id` is provided in addition to `trip_id`, then the `route_id` must be the same `route_id` as assigned to the given trip in GTFS trips.txt. +In all cases, if `route_id` is provided in addition to `trip_id`, then the `route_id` must be the same `route_id` as assigned to the given trip in GTFS trips.txt. The `trip_id` field cannot, by itself or in combination with other TripDescriptor fields, be used to identify multiple trip instances. For example, a TripDescriptor should never specify trip_id by itself for GTFS frequencies.txt exact_times=0 trips because start_time is also required to resolve to a single trip instance starting at a specific time of the day. If the TripDescriptor does not resolve to a single trip instance (i.e., it resolves to zero or multiple trip instances), it is considered an error and the entity containing the erroneous TripDescriptor may be discarded by consumers. From 8521ceef78eb20a66d34374dea4cc486bf8a6483 Mon Sep 17 00:00:00 2001 From: Guillaume Campagna Date: Tue, 28 Apr 2020 10:03:46 -0400 Subject: [PATCH 03/29] Mark severity level as final (#214) --- gtfs-realtime/proto/gtfs-realtime.proto | 1 - gtfs-realtime/spec/en/reference.md | 2 +- 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/gtfs-realtime/proto/gtfs-realtime.proto b/gtfs-realtime/proto/gtfs-realtime.proto index fd653b7fe..bd7d02ab4 100644 --- a/gtfs-realtime/proto/gtfs-realtime.proto +++ b/gtfs-realtime/proto/gtfs-realtime.proto @@ -478,7 +478,6 @@ message Alert { optional TranslatedString tts_description_text = 13; // Severity of this alert. - // This field is still experimental, and subject to change. It may be formally adopted in the future. enum SeverityLevel { UNKNOWN_SEVERITY = 1; INFO = 2; diff --git a/gtfs-realtime/spec/en/reference.md b/gtfs-realtime/spec/en/reference.md index e99cee767..8f34d290c 100644 --- a/gtfs-realtime/spec/en/reference.md +++ b/gtfs-realtime/spec/en/reference.md @@ -275,7 +275,7 @@ An alert, indicating some sort of incident in the public transit network. | **description_text** | [TranslatedString](#message-translatedstring) | Required | One | Description for the alert. This plain-text string will be formatted as the body of the alert (or shown on an explicit "expand" request by the user). The information in the description should add to the information of the header. | | **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.) **Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | | **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.) **Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | -| **severity_level** | [SeverityLevel](#enum-severitylevel) | Optional | One | Severity of the alert.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | +| **severity_level** | [SeverityLevel](#enum-severitylevel) | Optional | One | Severity of the alert. | ## _enum_ Cause From 4eeb3b4992cde24eceafd545594c329b98c16b22 Mon Sep 17 00:00:00 2001 From: Alexej Ababilov Date: Mon, 27 Apr 2020 19:42:13 +1000 Subject: [PATCH 04/29] Mention pathways.txt and attributions.txt in translations.txt Fields in pathways.txt and attributions.txt also may be translated. --- gtfs/spec/en/reference.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/gtfs/spec/en/reference.md b/gtfs/spec/en/reference.md index 67a16b01b..0bb5973fb 100644 --- a/gtfs/spec/en/reference.md +++ b/gtfs/spec/en/reference.md @@ -370,12 +370,12 @@ In regions that have multiple official languages, transit agencies/operators typ | Field Name | Type | Required | Description | | ------ | ------ | ------ | ------ | -| `table_name` | Enum | **Required** | Defines the table that contains the field to be translated. Allowed values are: `agency`, `stops`, `routes`, `trips`, `stop_times`, `levels` and `feed_info` (do not include the `.txt` file extension). If a table with a new file name is added by another proposal in the future, the table name is the name of the filename without the `.txt` file extension. | +| `table_name` | Enum | **Required** | Defines the table that contains the field to be translated. Allowed values are: `agency`, `stops`, `routes`, `trips`, `stop_times`, `pathways`, `levels`, `feed_info` and `attributions` (do not include the `.txt` file extension). If a table with a new file name is added by another proposal in the future, the table name is the name of the filename without the `.txt` file extension. | | `field_name` | Text | **Required** | Name of the field to be translated. Fields with type `Text` can be translated, fields with type `URL`, `Email` and `Phone number` can also be “translated” to provide resources in the correct language. Fields with other types should not be translated. | | `language` | Language code | **Required** | Language of translation.

If the language is the same as in `feed_info.feed_lang`, the original value of the field will be assumed to be the default value to use in languages without specific translations (if `default_lang` doesn't specify otherwise).

Example: In Switzerland, a city in an officially bilingual canton is officially called “Biel/Bienne”, but would simply be called “Bienne” in French and “Biel” in German. | | `translation` | Text or URL or Email or Phone number | **Required** | Translated value. | -| `record_id` | ID | **Conditionally Required** | Defines the record that corresponds to the field to be translated. The value in `record_id` should be a main ID of the table, as defined below:
• `agency_id` for `agency.txt`;
• `stop_id` for `stops.txt`;
• `route_id` for `routes.txt`;
• `trip_id` for `trips.txt`;
• `trip_id` for `stop_times.txt`.

No field should be translated in the other tables. However producers sometimes add extra fields that are outside the official specification and these unofficial fields may need to be translated. Below is the recommended way to use `record_id` for those tables:
• `service_id` for `calendar.txt`;
• `service_id` for `calendar_dates.txt`;
• `fare_id` for `fare_attributes.txt`;
• `fare_id` for `fare_rules.txt`;
• `shape_id` for `shapes.txt`;
• `trip_id` for `frequencies.txt`;
• `from_stop_id` for `transfers.txt`;
• `pathway_id` for `pathways.txt`;
• `level_id` for `levels.txt`.

**Conditionally Required:**
- **forbidden** if `table_name` is `feed_info`;
- **forbidden** if `field_value` is defined;
- **required** if `field_value` is empty. | -| `record_sub_id` | ID | **Conditionally Required** | Helps the record that contains the field to be translated when the table doesn’t have a unique ID. Therefore, the value in `record_sub_id` is the secondary ID of the table, as defined by the table below:
• None for `agency.txt`;
• None for `stops.txt`;
• None for `routes.txt`;
• None for `trips.txt`;
• `stop_sequence` for `stop_times.txt`;

No field should be translated in the other tables. However producers sometimes add extra fields that are outside the official specification and these unofficial fields may need to be translated. Below is the recommended way to use `record_sub_id` for those tables:
• None for `calendar.txt`;
• `date` for `calendar_dates.txt`;
• None for `fare_attributes.txt`;
• `route_id` for `fare_rules.txt`;
• None for `shapes.txt`;
• `start_time` for `frequencies.txt`;
• `to_stop_id` for `transfers.txt`;
• None for `pathways.txt`;
• None for `levels.txt`.

**Conditionally Required:**
- **forbidden** if `table_name` is `feed_info`;
- **forbidden** if `field_value` is defined;
- **required** if `table_name=stop_times` and `record_id` is defined. | +| `record_id` | ID | **Conditionally Required** | Defines the record that corresponds to the field to be translated. The value in `record_id` should be a main ID of the table, as defined below:
• `agency_id` for `agency.txt`;
• `stop_id` for `stops.txt`;
• `route_id` for `routes.txt`;
• `trip_id` for `trips.txt`;
• `trip_id` for `stop_times.txt`.

No field should be translated in the other tables. However producers sometimes add extra fields that are outside the official specification and these unofficial fields may need to be translated. Below is the recommended way to use `record_id` for those tables:
• `service_id` for `calendar.txt`;
• `service_id` for `calendar_dates.txt`;
• `fare_id` for `fare_attributes.txt`;
• `fare_id` for `fare_rules.txt`;
• `shape_id` for `shapes.txt`;
• `trip_id` for `frequencies.txt`;
• `from_stop_id` for `transfers.txt`;
• `pathway_id` for `pathways.txt`;
• `level_id` for `levels.txt`;
• `attribution_id` for `attribution.txt`.

**Conditionally Required:**
- **forbidden** if `table_name` is `feed_info`;
- **forbidden** if `field_value` is defined;
- **required** if `field_value` is empty. | +| `record_sub_id` | ID | **Conditionally Required** | Helps the record that contains the field to be translated when the table doesn’t have a unique ID. Therefore, the value in `record_sub_id` is the secondary ID of the table, as defined by the table below:
• None for `agency.txt`;
• None for `stops.txt`;
• None for `routes.txt`;
• None for `trips.txt`;
• `stop_sequence` for `stop_times.txt`;

No field should be translated in the other tables. However producers sometimes add extra fields that are outside the official specification and these unofficial fields may need to be translated. Below is the recommended way to use `record_sub_id` for those tables:
• None for `calendar.txt`;
• `date` for `calendar_dates.txt`;
• None for `fare_attributes.txt`;
• `route_id` for `fare_rules.txt`;
• None for `shapes.txt`;
• `start_time` for `frequencies.txt`;
• `to_stop_id` for `transfers.txt`;
• None for `pathways.txt`;
• None for `levels.txt`;
• None for `attributions.txt`.

**Conditionally Required:**
- **forbidden** if `table_name` is `feed_info`;
- **forbidden** if `field_value` is defined;
- **required** if `table_name=stop_times` and `record_id` is defined. | | `field_value` | Text or URL or Email or Phone number | **Conditionally Required** | Instead of defining which record should be translated by using `record_id` and `record_sub_id`, this field can be used to define the value which should be translated. When used, the translation will be applied when the fields identified by `table_name` and `field_name` contains the exact same value defined in field_value.

The field must have **exactly** the value defined in `field_value`. If only a subset of the value matches `field_value`, the translation won’t be applied.

If two translation rules match the same record (one with `field_value`, and the other one with `record_id`), then the rule with `record_id` is the one which should be used.

**Conditionally Required:**
- **forbidden** if `table_name` is `feed_info`;
- **forbidden** if `record_id` is defined;
- **required** if `record_id` is empty. | ### feed_info.txt From e92edf7ff17b93498183785cd8b03af26cb456bd Mon Sep 17 00:00:00 2001 From: Sean Barbeau Date: Tue, 5 May 2020 15:41:06 -0400 Subject: [PATCH 05/29] fix: Add translations.txt to the files table (#218) --- gtfs/spec/en/reference.md | 1 + 1 file changed, 1 insertion(+) diff --git a/gtfs/spec/en/reference.md b/gtfs/spec/en/reference.md index 0bb5973fb..c8fd1acc1 100644 --- a/gtfs/spec/en/reference.md +++ b/gtfs/spec/en/reference.md @@ -82,6 +82,7 @@ This specification defines the following files: | [transfers.txt](#transferstxt) | Optional | Rules for making connections at transfer points between routes. | | [pathways.txt](#pathwaystxt) | Optional | Pathways linking together locations within stations. | | [levels.txt](#levelstxt) | Optional | Levels within stations. | +| [translations.txt](#translationstxt) | Optional | Translations of customer-facing dataset values. | | [feed_info.txt](#feed_infotxt) | Optional | Dataset metadata, including publisher, version, and expiration information. | | [attributions.txt](#attributionstxt) | Optional | Dataset attributions. | From 6aeb49fe1ec8f78278c0bd53b350dab5221eeb1b Mon Sep 17 00:00:00 2001 From: Tim Millet Date: Wed, 13 May 2020 19:57:08 -0400 Subject: [PATCH 06/29] Add GTFS-ContinousStops (#208) --- gtfs/spec/en/reference.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/gtfs/spec/en/reference.md b/gtfs/spec/en/reference.md index c8fd1acc1..a9a5aaab4 100644 --- a/gtfs/spec/en/reference.md +++ b/gtfs/spec/en/reference.md @@ -159,6 +159,8 @@ File: **Required** | `route_color` | Color | Optional | Route color designation that matches public facing material. Defaults to white (`FFFFFF`) when omitted or left empty. The color difference between `route_color` and `route_text_color` should provide sufficient contrast when viewed on a black and white screen. | | `route_text_color` | Color | Optional | Legible color to use for text drawn against a background of `route_color`. Defaults to black (`000000`) when omitted or left empty. The color difference between `route_color` and `route_text_color` should provide sufficient contrast when viewed on a black and white screen. | | `route_sort_order` | Non-negative integer | Optional | Orders the routes in a way which is ideal for presentation to customers. Routes with smaller `route_sort_order` values should be displayed first. | +| `continuous_pickup` | Enum | Optional | Indicates that the rider can board the transit vehicle at any point along the vehicle’s travel path as described by `shapes.txt`, on every trip of the route. Valid options are:

`0` - Continuous stopping pickup.
`1` or empty - No continuous stopping pickup.
`2` - Must phone agency to arrange continuous stopping pickup.
`3` - Must coordinate with driver to arrange continuous stopping pickup.

The continuous pickup behavior defined in `routes.txt` can be overridden in `stop_times.txt`. | +| `continuous_drop_off` | Enum | Optional | Indicates that the rider can alight from the transit vehicle at any point along the vehicle’s travel path as described by `shapes.txt`, on every trip of the route. Valid options are:

`0` - Continuous stopping drop off.
`1` or empty - No continuous stopping drop off.
`2` - Must phone agency to arrange continuous stopping drop off.
`3` - Must coordinate with driver to arrange continuous stopping drop off.

The continuous drop-off behavior defined in `routes.txt` can be overridden in `stop_times.txt`. | ### trips.txt @@ -173,7 +175,7 @@ File: **Required** | `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, leave this field 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 is not used in routing; it provides a way to separate trips by direction when publishing time tables. Valid options are:

`0` - Travel in one direction (e.g. outbound travel).
`1` - Travel in the opposite direction (e.g. inbound travel).
*Example: The `trip_headsign` and `direction_id` fields could 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:*
`trip_id,...,trip_headsign,direction_id`
`1234,...,Airport,0`
`1505,...,Downtown,1` | | `block_id` | ID | Optional | Identifies the block to which the trip belongs. A block consists of a single trip or many sequential trips made using the same vehicle, defined by shared service days and `block_id`. A `block_id` can have trips with different service days, making distinct blocks. See the [example below](#example-blocks-and-service-day) | -| `shape_id` | ID referencing `shapes.shape_id` | Optional | Identifies a geospatial shape describing the vehicle travel path for a trip. | +| `shape_id` | ID referencing `shapes.shape_id` | **Conditionally Required** | Identifies a geospatial shape describing the vehicle travel path for a trip.

Conditionally Required:
- **Required** if the trip has a continuous pickup or drop-off behavior defined either in `routes.txt` or in `stop_times.txt`.
- **Optional** otherwise. | | `wheelchair_accessible` | Enum | Optional | Indicates wheelchair accessibility. Valid options are:

`0` or empty - No accessibility information for the trip.
`1` - Vehicle being used on this particular trip can accommodate at least one rider in a wheelchair.
`2` - No riders in wheelchairs can be accommodated on this trip. | | `bikes_allowed` | Enum | Optional | Indicates whether bikes are allowed. Valid options are:

`0` or empty - No bike information for the trip.
`1` - Vehicle being used on this particular trip can accommodate at least one bicycle.
`2` - No bicycles are allowed on this trip. | @@ -208,6 +210,8 @@ File: **Required** | `stop_headsign` | Text | Optional | Text that appears on signage identifying the trip's destination to riders. This field overrides the default `trips.trip_headsign` when the headsign changes between stops. If the headsign is displayed for an entire trip, use `trips.trip_headsign` instead.

A `stop_headsign` value specified for one `stop_time` does not apply to subsequent `stop_time`s in the same trip. If you want to override the `trip_headsign` for multiple `stop_time`s in the same trip, the `stop_headsign` value must be repeated in each `stop_time` row. | | `pickup_type` | Enum | Optional | Indicates pickup method. Valid options are:

`0` or empty - Regularly scheduled pickup.
`1` - No pickup available.
`2` - Must phone agency to arrange pickup.
`3` - Must coordinate with driver to arrange pickup. | | `drop_off_type` | Enum | Optional | Indicates drop off method. Valid options are:

`0` or empty - Regularly scheduled drop off.
`1` - No drop off available.
`2` - Must phone agency to arrange drop off.
`3` - Must coordinate with driver to arrange drop off. | +| `continuous_pickup` | Enum | Optional | Indicates that the rider can board the transit vehicle at any point along the vehicle’s travel path as described by `shapes.txt`, from this `stop_time` to the next `stop_time` in the trip’s `stop_sequence`. Valid options are:

`0` - Continuous stopping pickup.
`1` or empty - No continuous stopping pickup.
`2` - Must phone agency to arrange continuous stopping pickup.
`3` - Must coordinate with driver to arrange continuous stopping pickup.

If this field is populated, it overrides any continuous pickup behavior defined in `routes.txt`. If this field is empty, the `stop_time` inherits any continuous pickup behavior defined in `routes.txt`. | +| `continuous_drop_off` | Enum | Optional | Indicates that the rider can alight from the transit vehicle at any point along the vehicle’s travel path as described by `shapes.txt`, from this `stop_time` to the next `stop_time` in the trip’s `stop_sequence`. Valid options are:

`0` - Continuous stopping drop off.
`1` or empty - No continuous stopping drop off.
`2` - Must phone agency to arrange continuous stopping drop off.
`3` - Must coordinate with driver to arrange continuous stopping drop off.

If this field is populated, it overrides any continuous drop-off behavior defined in `routes.txt`. If this field is empty, the `stop_time` inherits any continuous drop-off behavior defined in `routes.txt`. | | `shape_dist_traveled` | Non-negative float | Optional | Actual distance traveled along the associated shape, from the first stop to the stop specified in this record. This field specifies how much of the shape to draw between any two stops during a trip. Must be in the same units used in [shapes.txt](#shapestxt). Values used for `shape_dist_traveled` must increase along with `stop_sequence`; they cannot be used to show reverse travel along a route.
*Example: If a bus travels a distance of 5.25 kilometers from the start of the shape to the stop,`shape_dist_traveled`=`5.25`.*| | `timepoint` | Enum | Optional | Indicates if arrival and departure times for a stop are strictly adhered to by the vehicle or if they are instead approximate and/or interpolated times. This field allows a GTFS producer to provide interpolated stop-times, while indicating that the times are approximate. Valid options are:

`0` - Times are considered approximate.
`1` or empty - Times are considered exact. | From 030c1582bfa764641c58c2dd387985534d382f04 Mon Sep 17 00:00:00 2001 From: Alexej Ababilov Date: Thu, 30 Apr 2020 08:53:42 +1000 Subject: [PATCH 07/29] Move pathways, levels and attributions to the list of translatable tables The following standard fields in those tables can be translated: * pathways.txt - signposted_as, reversed_signposted_as * levels.txt - level_name * attributions.txt - organization_name, attribution_url, attribution_phone Previously, the documentation placed them in a list of tables whose standard fields should not be translated. --- gtfs/spec/en/reference.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/gtfs/spec/en/reference.md b/gtfs/spec/en/reference.md index a9a5aaab4..b4253bd2a 100644 --- a/gtfs/spec/en/reference.md +++ b/gtfs/spec/en/reference.md @@ -379,8 +379,8 @@ In regions that have multiple official languages, transit agencies/operators typ | `field_name` | Text | **Required** | Name of the field to be translated. Fields with type `Text` can be translated, fields with type `URL`, `Email` and `Phone number` can also be “translated” to provide resources in the correct language. Fields with other types should not be translated. | | `language` | Language code | **Required** | Language of translation.

If the language is the same as in `feed_info.feed_lang`, the original value of the field will be assumed to be the default value to use in languages without specific translations (if `default_lang` doesn't specify otherwise).

Example: In Switzerland, a city in an officially bilingual canton is officially called “Biel/Bienne”, but would simply be called “Bienne” in French and “Biel” in German. | | `translation` | Text or URL or Email or Phone number | **Required** | Translated value. | -| `record_id` | ID | **Conditionally Required** | Defines the record that corresponds to the field to be translated. The value in `record_id` should be a main ID of the table, as defined below:
• `agency_id` for `agency.txt`;
• `stop_id` for `stops.txt`;
• `route_id` for `routes.txt`;
• `trip_id` for `trips.txt`;
• `trip_id` for `stop_times.txt`.

No field should be translated in the other tables. However producers sometimes add extra fields that are outside the official specification and these unofficial fields may need to be translated. Below is the recommended way to use `record_id` for those tables:
• `service_id` for `calendar.txt`;
• `service_id` for `calendar_dates.txt`;
• `fare_id` for `fare_attributes.txt`;
• `fare_id` for `fare_rules.txt`;
• `shape_id` for `shapes.txt`;
• `trip_id` for `frequencies.txt`;
• `from_stop_id` for `transfers.txt`;
• `pathway_id` for `pathways.txt`;
• `level_id` for `levels.txt`;
• `attribution_id` for `attribution.txt`.

**Conditionally Required:**
- **forbidden** if `table_name` is `feed_info`;
- **forbidden** if `field_value` is defined;
- **required** if `field_value` is empty. | -| `record_sub_id` | ID | **Conditionally Required** | Helps the record that contains the field to be translated when the table doesn’t have a unique ID. Therefore, the value in `record_sub_id` is the secondary ID of the table, as defined by the table below:
• None for `agency.txt`;
• None for `stops.txt`;
• None for `routes.txt`;
• None for `trips.txt`;
• `stop_sequence` for `stop_times.txt`;

No field should be translated in the other tables. However producers sometimes add extra fields that are outside the official specification and these unofficial fields may need to be translated. Below is the recommended way to use `record_sub_id` for those tables:
• None for `calendar.txt`;
• `date` for `calendar_dates.txt`;
• None for `fare_attributes.txt`;
• `route_id` for `fare_rules.txt`;
• None for `shapes.txt`;
• `start_time` for `frequencies.txt`;
• `to_stop_id` for `transfers.txt`;
• None for `pathways.txt`;
• None for `levels.txt`;
• None for `attributions.txt`.

**Conditionally Required:**
- **forbidden** if `table_name` is `feed_info`;
- **forbidden** if `field_value` is defined;
- **required** if `table_name=stop_times` and `record_id` is defined. | +| `record_id` | ID | **Conditionally Required** | Defines the record that corresponds to the field to be translated. The value in `record_id` should be a main ID of the table, as defined below:
• `agency_id` for `agency.txt`;
• `stop_id` for `stops.txt`;
• `route_id` for `routes.txt`;
• `trip_id` for `trips.txt`;
• `trip_id` for `stop_times.txt`;
• `pathway_id` for `pathways.txt`;
• `level_id` for `levels.txt`;
• `attribution_id` for `attribution.txt`.

No field should be translated in the other tables. However producers sometimes add extra fields that are outside the official specification and these unofficial fields may need to be translated. Below is the recommended way to use `record_id` for those tables:
• `service_id` for `calendar.txt`;
• `service_id` for `calendar_dates.txt`;
• `fare_id` for `fare_attributes.txt`;
• `fare_id` for `fare_rules.txt`;
• `shape_id` for `shapes.txt`;
• `trip_id` for `frequencies.txt`;
• `from_stop_id` for `transfers.txt`.

**Conditionally Required:**
- **forbidden** if `table_name` is `feed_info`;
- **forbidden** if `field_value` is defined;
- **required** if `field_value` is empty. | +| `record_sub_id` | ID | **Conditionally Required** | Helps the record that contains the field to be translated when the table doesn’t have a unique ID. Therefore, the value in `record_sub_id` is the secondary ID of the table, as defined by the table below:
• None for `agency.txt`;
• None for `stops.txt`;
• None for `routes.txt`;
• None for `trips.txt`;
• `stop_sequence` for `stop_times.txt`;
• None for `pathways.txt`;
• None for `levels.txt`;
• None for `attributions.txt`.

No field should be translated in the other tables. However producers sometimes add extra fields that are outside the official specification and these unofficial fields may need to be translated. Below is the recommended way to use `record_sub_id` for those tables:
• None for `calendar.txt`;
• `date` for `calendar_dates.txt`;
• None for `fare_attributes.txt`;
• `route_id` for `fare_rules.txt`;
• None for `shapes.txt`;
• `start_time` for `frequencies.txt`;
• `to_stop_id` for `transfers.txt`.

**Conditionally Required:**
- **forbidden** if `table_name` is `feed_info`;
- **forbidden** if `field_value` is defined;
- **required** if `table_name=stop_times` and `record_id` is defined. | | `field_value` | Text or URL or Email or Phone number | **Conditionally Required** | Instead of defining which record should be translated by using `record_id` and `record_sub_id`, this field can be used to define the value which should be translated. When used, the translation will be applied when the fields identified by `table_name` and `field_name` contains the exact same value defined in field_value.

The field must have **exactly** the value defined in `field_value`. If only a subset of the value matches `field_value`, the translation won’t be applied.

If two translation rules match the same record (one with `field_value`, and the other one with `record_id`), then the rule with `record_id` is the one which should be used.

**Conditionally Required:**
- **forbidden** if `table_name` is `feed_info`;
- **forbidden** if `record_id` is defined;
- **required** if `record_id` is empty. | ### feed_info.txt From 044ea68f2d6d43aac40a3f46b8ea4d94d00fd348 Mon Sep 17 00:00:00 2001 From: Alexej Ababilov Date: Thu, 7 May 2020 11:15:33 +1000 Subject: [PATCH 08/29] Update comment for pathways.signposted_as to allow translations --- gtfs/spec/en/reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gtfs/spec/en/reference.md b/gtfs/spec/en/reference.md index b4253bd2a..309688d1b 100644 --- a/gtfs/spec/en/reference.md +++ b/gtfs/spec/en/reference.md @@ -351,7 +351,7 @@ To go from the entrance (which is a node represented as a location with location | `stair_count` | Non-null Integer | Optional | Number of stairs of the pathway.

Best Practices: one could use the approximation of 1 floor = 15 stairs to generate approximative values.

A positive `stair_count` implies that the rider walk up from `from_stop_id` to `to_stop_id`. And a negative `stair_count` implies that the rider walk down from `from_stop_id` to `to_stop_id`.

This field is recommended for stairs (`pathway_mode=2`).| | `max_slope` | Float | Optional | Maximum slope ratio of the pathway. Valid values for this field are:
• 0 or (empty): no slope.
• A float: slope ratio of the pathway, positive for upwards, negative for downwards.

This field should be used only with walkways (`pathway_mode=1`) and moving sidewalks (`pathway_mode=3`).

Example: In the US, 0.083 (also written 8.3%) is the maximum slope ratio for hand-propelled wheelchair, which mean an increase of 0.083m (so 8.3cm) for each 1m.| | `min_width` | Positive Float | Optional | Minimum width of the pathway in meters.

This field is highly recommended if the minimum width is less than 1 meter.| -| `signposted_as` | Text | Optional | String of text from physical signage visible to transit riders. The string can be used to provide text directions to users, such as 'follow signs to '. The language text should appear in this field exactly how it is printed on the signs - it should not be translated.| +| `signposted_as` | Text | Optional | String of text from physical signage visible to transit riders. The string can be used to provide text directions to users, such as 'follow signs to '. The language text should appear in this field exactly how it is printed on the signs.

When the physical signage is multilingual, this field may be populated and translated following the example of `stops.stop_name` in the field definition of `feed_info.feed_lang`.| | `reversed_signposted_as` | Text | Optional | Same than the `signposted_as` field, but when the pathways is used backward, i.e. from the `to_stop_id` to the `from_stop_id`.| ### levels.txt From 102179ff7b0c5e2c6025dc6b8cef825d8999aed3 Mon Sep 17 00:00:00 2001 From: scmcca <62957380+scmcca@users.noreply.github.com> Date: Tue, 2 Jun 2020 17:18:17 -0400 Subject: [PATCH 09/29] Updated revision history for GTFS CHANGES.md (#225) Updated GTFS revision history for transit/gtfs/CHANGES.md as of May 21, 2020. --- gtfs/CHANGES.md | 93 +++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 90 insertions(+), 3 deletions(-) diff --git a/gtfs/CHANGES.md b/gtfs/CHANGES.md index b967fdd60..ee791648f 100644 --- a/gtfs/CHANGES.md +++ b/gtfs/CHANGES.md @@ -50,9 +50,73 @@ Every new feature adds complexity to the creation and reading of feeds. Therefor ### Revision History -#### January 17, 2019 +#### May 28, 2020 -* Editorial and formatting changes for clarity. See [pull request](https://github.com/google/transit/pull/120). +* Updated major GTFS changes under "Revision History" in `CHANGES.md`. Last revised in January 2019 with some historical entries missing. + +#### May 13, 2020 + +* Added `continuous_pickup` and `continuous_drop_off` to `routes.txt` and `stop_times.txt`. See [discussion](https://github.com/google/transit/pull/208). +* Changed `shape_id` from "Optional" to "Conditionally required". See [discussion](https://github.com/google/transit/pull/208). + +#### March 24, 2020 + +* Defined text-to-speech field and added `tts_stop_name` to `stops.txt`. See [discussion](https://github.com/google/transit/pull/49). + +#### February 5, 2020 + +* Added trolleybus and monorail `route_types`. See [discussion](https://github.com/google/transit/pull/174). + +#### January 9, 2020 + +* Added `translations.txt`. See [discussion](https://github.com/google/transit/pull/180). + +#### December 26, 2019 + +* Updated definitions for cable tram and aerial lift in `route_type`. See [discussion](https://github.com/google/transit/pull/186). + +#### December 20, 2019 + +* Added `attributions.txt`. See [discussion](https://github.com/google/transit/pull/192). + +#### August 26, 2019 + +* Specified that `stop_lat` and `stop_lon` be positioned where passengers wait to board the vehicle. See [discussion](https://github.com/google/transit/pull/179). + +#### July 9, 2019 + +* Added arrival and departure time best practices. See [discussion](https://github.com/google/transit/pull/165). +* Added headsign best practices. See [discussion](https://github.com/google/transit/pull/167). +* Added `stop_id` best practices. See [discussion](https://github.com/google/transit/pull/169). + +#### June 25, 2019 + +* Clarified relationship of shape points and stops. See [discussion](https://github.com/google/transit/pull/39). + +#### April 4, 2019 + +* Added `platform_code` field in `stops.txt`. See [discussion](https://github.com/google/transit/pull/146). + +#### March 27, 2019 + +* Added `pathways.txt` and `levels.txt` to GTFS-static. See [discussion](https://github.com/google/transit/pull/143). + +#### February 6, 2019 + +* Editorial and formatting changes for clarity. See [discussion](https://github.com/google/transit/pull/120). + +#### October 2, 2018 + +* Factorized field types for conciseness. See [discussion](https://github.com/google/transit/pull/104). + +#### September 4, 2018 + +* Added "Conditionally required" concept. See [discussion](https://github.com/google/transit/pull/100). +* Unified the definitions of `agency_lang` and `feed_lang`. See [discussion](https://github.com/google/transit/pull/98). + +#### August 27, 2018 + +* Updated `CHANGES.md` and last revised date. See [discussion](https://github.com/google/transit/pull/99). #### August 22, 2018 @@ -60,15 +124,38 @@ Every new feature adds complexity to the creation and reading of feeds. Therefor #### December 11, 2017 +* Added `route_sort_order` to `routes.txt`. See [discussion](https://github.com/google/transit/pull/83). + +#### March 15, 2017 + +* Clarified that a proposer's vote does not count towards total. See [discussion](https://github.com/google/transit/pull/50). +* Specified that at before calling a vote, at least one GTFS producer and one GTFS consumer should implement the proposed change. See [discussion](https://github.com/google/transit/pull/46). + +#### February 7, 2017 + +* Clarified relationship of `block_id` and `service_id`. See [discussion](https://github.com/google/transit/pull/44). +* Clarified that frequency-based service begins at vehicle departure. See [discussion](https://github.com/google/transit/pull/42). +* Clarified descriptions of `stop_id` and `stop_code`. See [discussion](https://github.com/google/transit/pull/40). + +#### December 11, 2017 + * Added `route_sort_order` field in the `routes.txt` file. See [discussion](https://github.com/google/transit/pull/83). +#### November 27, 2016 + +* Added station entrance as a `stops.location_type`. See [discussion](https://github.com/google/transit/pull/30). + +#### September 2, 2016 + +* Updated documentation to add `agency_id` under `fare_attributes.txt`. See [discussion](https://github.com/google/transit/pull/27). + #### March 16, 2016 * Transition of GTFS documentation to Github at https://github.com/google/transit #### February 3, 2016 -* Added agency.txt 'agency_email' proposal to spec: [discussion](https://groups.google.com/forum/?fromgroups#!topic/gtfs-changes/aezjQsriLYA) +* Added `agency_email` to `agency.txt` proposal to spec: [discussion](https://groups.google.com/forum/?fromgroups#!topic/gtfs-changes/aezjQsriLYA) #### February 2, 2015 From 422b46187697df7c85e3173024b28587021a05bb Mon Sep 17 00:00:00 2001 From: Sean Barbeau Date: Fri, 10 Jul 2020 09:52:53 -0400 Subject: [PATCH 10/29] feat: Add GitHub CI Action for GTFS-RT .proto validation (#232) --- .github/workflows/validate-proto.yml | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 .github/workflows/validate-proto.yml diff --git a/.github/workflows/validate-proto.yml b/.github/workflows/validate-proto.yml new file mode 100644 index 000000000..36505985b --- /dev/null +++ b/.github/workflows/validate-proto.yml @@ -0,0 +1,25 @@ +name: Validate GTFS-realtime .proto file + +on: + push: + branches: [ master ] + pull_request: + branches: [ master ] + +jobs: + build: + + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v2 + - name: Set up JDK 1.8 + uses: actions/setup-java@v1 + with: + java-version: 1.8 + server-id: github # Value of the distributionManagement/repository/id field of the pom.xml + settings-path: ${{ github.workspace }} # location for the settings.xml file + - name: Install Protoc + uses: arduino/setup-protoc@master + - name: Compile Java bindings + run: protoc --java_out=gtfs-realtime/proto gtfs-realtime/proto/gtfs-realtime.proto From 2ae5df1c281332679e89363a5eb0e4766d8e046b Mon Sep 17 00:00:00 2001 From: Sean Barbeau Date: Wed, 15 Jul 2020 10:44:25 -0400 Subject: [PATCH 11/29] feat: Label GTFS-RT ADDED trips as not fully specified (#230) --- gtfs-realtime/proto/gtfs-realtime.proto | 4 ++++ gtfs-realtime/spec/en/reference.md | 2 +- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/gtfs-realtime/proto/gtfs-realtime.proto b/gtfs-realtime/proto/gtfs-realtime.proto index bd7d02ab4..a18b6820f 100644 --- a/gtfs-realtime/proto/gtfs-realtime.proto +++ b/gtfs-realtime/proto/gtfs-realtime.proto @@ -613,6 +613,10 @@ message TripDescriptor { // An extra trip that was added in addition to a running schedule, for // example, to replace a broken vehicle or to respond to sudden passenger // load. + // NOTE: Currently, behavior is unspecified for feeds that use this mode. There are discussions on the GTFS GitHub + // [(1)](https://github.com/google/transit/issues/106) [(2)](https://github.com/google/transit/pull/221) + // [(3)](https://github.com/google/transit/pull/219) around fully specifying or deprecating ADDED trips and the + // documentation will be updated when those discussions are finalized. ADDED = 1; // A trip that is running with no schedule associated to it (GTFS frequencies.txt exact_times=0). diff --git a/gtfs-realtime/spec/en/reference.md b/gtfs-realtime/spec/en/reference.md index 8f34d290c..888aa518c 100644 --- a/gtfs-realtime/spec/en/reference.md +++ b/gtfs-realtime/spec/en/reference.md @@ -394,7 +394,7 @@ The relation between this trip and the static schedule. If a trip is done in acc | _**Value**_ | _**Comment**_ | |-------------|---------------| | **SCHEDULED** | Trip that is running in accordance with its GTFS schedule, or is close enough to the scheduled trip to be associated with it. | -| **ADDED** | An extra trip that was added in addition to a running schedule, for example, to replace a broken vehicle or to respond to sudden passenger load. | +| **ADDED** | An extra trip that was added in addition to a running schedule, for example, to replace a broken vehicle or to respond to sudden passenger load. *NOTE: Currently, behavior is unspecified for feeds that use this mode. There are discussions on the GTFS GitHub [(1)](https://github.com/google/transit/issues/106) [(2)](https://github.com/google/transit/pull/221) [(3)](https://github.com/google/transit/pull/219) around fully specifying or deprecating ADDED trips and the documentation will be updated when those discussions are finalized.* | | **UNSCHEDULED** | A trip that is running with no schedule associated to it - this value is used to identify trips defined in GTFS frequencies.txt with exact_times = 0. It should not be used to describe trips not defined in GTFS frequencies.txt, or trips in GTFS frequencies.txt with exact_times = 1. Trips with `schedule_relationship: UNSCHEDULED` must also set all StopTimeUpdates `schedule_relationship: UNSCHEDULED`| | **CANCELED** | A trip that existed in the schedule but was removed. | From 24f8f3881acc2b939d53bbd9edf6f1214bd3a687 Mon Sep 17 00:00:00 2001 From: Sean Barbeau Date: Mon, 20 Jul 2020 14:04:41 -0400 Subject: [PATCH 12/29] fix: Fix a typo in occupancy_percentage description (#234) --- gtfs-realtime/spec/en/reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gtfs-realtime/spec/en/reference.md b/gtfs-realtime/spec/en/reference.md index 888aa518c..a9ff1cd8c 100644 --- a/gtfs-realtime/spec/en/reference.md +++ b/gtfs-realtime/spec/en/reference.md @@ -213,7 +213,7 @@ Realtime positioning information for a given vehicle. | **timestamp** | [uint64](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | Moment at which the vehicle's position was measured. In POSIX time (i.e., number of seconds since January 1st 1970 00:00:00 UTC). | | **congestion_level** | [CongestionLevel](#enum-congestionlevel) | Optional | One | | _**occupancy_status**_ | _[OccupancyStatus](#enum-occupancystatus)_ | _Optional_ | One | The degree of passenger occupancy of the vehicle.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.| -| **occupancy_percentage** | [uint32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | A percentage value representing the degree of passenger occupancy of the vehicle. The value 100 should represent total the maximum occupancy the vehicle was designed for, including both seating and standing capacity, and current operating regulations allow. It's not impossible that the value goes over 100 if there are currently more passenger than the vehicle was designed for. The precision of precision should be low enough that you can't track a single person boarding and alighting for privacy reasons.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | +| **occupancy_percentage** | [uint32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | A percentage value representing the degree of passenger occupancy of the vehicle. The value 100 should represent total the maximum occupancy the vehicle was designed for, including both seating and standing capacity, and current operating regulations allow. It's not impossible that the value goes over 100 if there are currently more passenger than the vehicle was designed for. The precision of occupancy_percentage should be low enough that you can't track a single person boarding and alighting for privacy reasons.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | ## _enum_ VehicleStopStatus From fec428e9023a8dabb1a23cbd56ba607fe5e3e96c Mon Sep 17 00:00:00 2001 From: Alexej Ababilov Date: Wed, 22 Jul 2020 18:53:16 +1000 Subject: [PATCH 13/29] Fix a typo can can --- gtfs/spec/en/reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gtfs/spec/en/reference.md b/gtfs/spec/en/reference.md index 309688d1b..04a7904e1 100644 --- a/gtfs/spec/en/reference.md +++ b/gtfs/spec/en/reference.md @@ -259,7 +259,7 @@ File: **Optional** | `payment_method` | Enum | **Required** | Indicates when the fare must be paid. Valid options are:

`0` - Fare is paid on board.
`1` - Fare must be paid before boarding. | | `transfers` | Enum | **Required** | Indicates the number of transfers permitted on this fare. The fact that this field can be left empty is an exception to the requirement that a Required field must not be empty. Valid options are:

`0` - No transfers permitted on this fare.
`1` - Riders may transfer once.
`2` - Riders may transfer twice.
empty - Unlimited transfers are permitted. | | `agency_id` | ID referencing `agency.agency_id` | **Conditionally Required** | Identifies the relevant agency for a fare. This field is required for datasets with multiple agencies defined in [agency.txt](#agencytxt), otherwise it is optional. | -| `transfer_duration` | Non-negative integer | Optional | Length of time in seconds before a transfer expires. When `transfers`=`0` this field can be used to indicate how long a ticket is valid for or it can can be left empty. | +| `transfer_duration` | Non-negative integer | Optional | Length of time in seconds before a transfer expires. When `transfers`=`0` this field can be used to indicate how long a ticket is valid for or it can be left empty. | ### fare_rules.txt From df73737e3ca2010db5766a99ffc3a7e049794fac Mon Sep 17 00:00:00 2001 From: Sean Barbeau Date: Thu, 23 Jul 2020 16:10:06 -0400 Subject: [PATCH 14/29] feat: Alert `tts_header_text`, `tts_description_text` no longer experimental (#229) --- gtfs-realtime/proto/gtfs-realtime.proto | 2 -- gtfs-realtime/spec/en/reference.md | 4 ++-- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/gtfs-realtime/proto/gtfs-realtime.proto b/gtfs-realtime/proto/gtfs-realtime.proto index a18b6820f..ce7e0ebfa 100644 --- a/gtfs-realtime/proto/gtfs-realtime.proto +++ b/gtfs-realtime/proto/gtfs-realtime.proto @@ -470,11 +470,9 @@ message Alert { optional TranslatedString description_text = 11; // Text for alert header to be used in text-to-speech implementations. This field is the text-to-speech version of header_text. - // This field is still experimental, and subject to change. It may be formally adopted in the future. optional TranslatedString tts_header_text = 12; // Text for full description for the alert to be used in text-to-speech implementations. This field is the text-to-speech version of description_text. - // This field is still experimental, and subject to change. It may be formally adopted in the future. optional TranslatedString tts_description_text = 13; // Severity of this alert. diff --git a/gtfs-realtime/spec/en/reference.md b/gtfs-realtime/spec/en/reference.md index a9ff1cd8c..78956a824 100644 --- a/gtfs-realtime/spec/en/reference.md +++ b/gtfs-realtime/spec/en/reference.md @@ -273,8 +273,8 @@ An alert, indicating some sort of incident in the public transit network. | **url** | [TranslatedString](#message-translatedstring) | Optional | One | The URL which provides additional information about the alert. | | **header_text** | [TranslatedString](#message-translatedstring) | Required | One | Header for the alert. This plain-text string will be highlighted, for example in boldface. | | **description_text** | [TranslatedString](#message-translatedstring) | Required | One | Description for the alert. This plain-text string will be formatted as the body of the alert (or shown on an explicit "expand" request by the user). The information in the description should add to the information of the header. | -| **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.) **Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | -| **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.) **Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | +| **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. | ## _enum_ Cause From 770ffeed2ac33bf2a384bb22ba113686187fce8c Mon Sep 17 00:00:00 2001 From: Sean Barbeau Date: Wed, 29 Jul 2020 17:32:24 -0400 Subject: [PATCH 15/29] Proposal: Support DUPLICATED trips in GTFS-RT (#221) * Support DUPLICATED trips in GTFS-RT * Revert deprecation of ADDED * Remove auto-format change * Better explanation of "forbidden" * Add experimental labels for message/fields * Add experimental labels for field * Add experimental label for message * Clarify DUPLICATED use with VehiclePosition * Clarify that true frequency-based trips can't be duplicated * Explicitly define how the duplicated trip schedule and RT values are calculated * docs: Add migration guide for transition from ADDED to DUPLICATED trips * docs: Normalize comments in code * docs: Allow trip.trip_id->trip_properties.trip_id link in migration guide --- gtfs-realtime/proto/gtfs-realtime.proto | 52 ++++++++- gtfs-realtime/spec/en/examples/README.md | 7 ++ .../spec/en/examples/migration-duplicated.md | 104 ++++++++++++++++++ gtfs-realtime/spec/en/reference.md | 22 +++- gtfs-realtime/spec/en/trip-updates.md | 1 + 5 files changed, 183 insertions(+), 3 deletions(-) create mode 100644 gtfs-realtime/spec/en/examples/migration-duplicated.md diff --git a/gtfs-realtime/proto/gtfs-realtime.proto b/gtfs-realtime/proto/gtfs-realtime.proto index ce7e0ebfa..373ae2a64 100644 --- a/gtfs-realtime/proto/gtfs-realtime.proto +++ b/gtfs-realtime/proto/gtfs-realtime.proto @@ -296,6 +296,36 @@ message TripUpdate { // formally adopted in the future. optional int32 delay = 5; + // Defines updated properties of the trip + // NOTE: This message is still experimental, and subject to change. It may be formally adopted in the future. + message TripProperties { + // Defines the identifier of a new trip that is a duplicate of an existing trip defined in (CSV) GTFS trips.txt + // but will start at a different service date and/or time (defined using the TripProperties.start_date and + // TripProperties.start_time fields). See definition of trips.trip_id in (CSV) GTFS. Its value must be different + // than the ones used in the (CSV) GTFS. Required if schedule_relationship=DUPLICATED, otherwise this field must not + // be populated and will be ignored by consumers. + // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future. + optional string trip_id = 1; + // Service date on which the DUPLICATED trip will be run, in YYYYMMDD format. Required if + // schedule_relationship=DUPLICATED, otherwise this field must not be populated and will be ignored by consumers. + // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future. + optional string start_date = 2; + // Defines the departure start time of the trip when it’s duplicated. See definition of stop_times.departure_time + // in (CSV) GTFS. Scheduled arrival and departure times for the duplicated trip are calculated based on the offset + // between the original trip departure_time and this field. For example, if a GTFS trip has stop A with a + // departure_time of 10:00:00 and stop B with departure_time of 10:01:00, and this field is populated with the value + // of 10:30:00, stop B on the duplicated trip will have a scheduled departure_time of 10:31:00. Real-time prediction + // delay values are applied to this calculated schedule time to determine the predicted time. For example, if a + // departure delay of 30 is provided for stop B, then the predicted departure time is 10:31:30. Real-time + // prediction time values do not have any offset applied to them and indicate the predicted time as provided. + // For example, if a departure time representing 10:31:30 is provided for stop B, then the predicted departure time + // is 10:31:30. This field is required if schedule_relationship is DUPLICATED, otherwise this field must not be + // populated and will be ignored by consumers. + // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future. + optional string start_time = 3; + } + optional TripProperties trip_properties = 6; + // 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. @@ -562,7 +592,9 @@ message TripDescriptor { // The trip_id from the GTFS feed that this selector refers to. // For non frequency-based trips, this field is enough to uniquely identify // the trip. For frequency-based trip, start_time and start_date might also be - // necessary. + // necessary. When schedule_relationship is DUPLICATED within a TripUpdate, the trip_id identifies the trip from + // static GTFS to be duplicated. When schedule_relationship is DUPLICATED within a VehiclePosition, the trip_id + // identifies the new duplicate trip and must contain the value for the corresponding TripUpdate.TripProperties.trip_id. optional string trip_id = 1; // The route_id from the GTFS that this selector refers to. @@ -626,7 +658,25 @@ message TripDescriptor { // Should not be used - for backwards-compatibility only. REPLACEMENT = 5 [deprecated=true]; + + // An extra trip that was added in addition to a running schedule, for example, to replace a broken vehicle or to + // respond to sudden passenger load. Used with TripUpdate.TripProperties.trip_id, TripUpdate.TripProperties.start_date, + // and TripUpdate.TripProperties.start_time to copy an existing trip from static GTFS but start at a different service + // date and/or time. Duplicating a trip is allowed if the service related to the original trip in (CSV) GTFS + // (in calendar.txt or calendar_dates.txt) is operating within the next 30 days. The trip to be duplicated is + // identified via TripUpdate.TripDescriptor.trip_id. This enumeration does not modify the existing trip referenced by + // TripUpdate.TripDescriptor.trip_id - if a producer wants to cancel the original trip, it must publish a separate + // TripUpdate with the value of CANCELED. Trips defined in GTFS frequencies.txt with exact_times that is empty or + // equal to 0 cannot be duplicated. The VehiclePosition.TripDescriptor.trip_id for the new trip must contain + // the matching value from TripUpdate.TripProperties.trip_id and VehiclePosition.TripDescriptor.ScheduleRelationship + // must also be set to DUPLICATED. + // Existing producers and consumers that were using the ADDED enumeration to represent duplicated trips must follow + // the migration guide (https://github.com/google/transit/tree/master/gtfs-realtime/spec/en/examples/migration-duplicated.md) + // to transition to the DUPLICATED enumeration. + // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future. + DUPLICATED = 6; } + // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future. optional ScheduleRelationship schedule_relationship = 4; // The extensions namespace allows 3rd-party developers to extend the diff --git a/gtfs-realtime/spec/en/examples/README.md b/gtfs-realtime/spec/en/examples/README.md index d38444d2a..d0d924608 100644 --- a/gtfs-realtime/spec/en/examples/README.md +++ b/gtfs-realtime/spec/en/examples/README.md @@ -1,4 +1,11 @@ +### Plain text feed examples + The following examples show a textual representation of feeds. During development it is more convenient to produce ASCII protocol buffer output for easier debugging. You can compare your text output with these examples to check for the validity of data. * [Alerts](alerts.asciipb) * [Trip update (full dataset)](trip-updates-full.asciipb) + +### Migration guides + +The following migration guides can help consumers and producers transition from "unofficial" practices to new "official" features of the spec: +* [Transition from ADDED to DUPLICATED trips](migration-duplicated.md) - A duplicated trip is new trip that is the same as an existing scheduled trip except for service start date and time. This [migration guide](migration-duplicated.md) defines how existing producers and consumers that were using the `ADDED` enumeration to represent duplicated trips should transition to the `DUPLICATED` enumeration. \ No newline at end of file diff --git a/gtfs-realtime/spec/en/examples/migration-duplicated.md b/gtfs-realtime/spec/en/examples/migration-duplicated.md new file mode 100644 index 000000000..b617a5732 --- /dev/null +++ b/gtfs-realtime/spec/en/examples/migration-duplicated.md @@ -0,0 +1,104 @@ +## Migration Guide - Transition from ADDED to DUPLICATED trips + +The GTFS-realtime `trip.schedule_relationship` of `DUPLICATED` represents a new trip that is the same as an existing scheduled trip except for service start date and time. + +This migration guide defines how existing producers and consumers that were using the `ADDED` enumeration to represent duplicated trips should transition to the `DUPLICATED` enumeration. The goal is to minimize disruption to producers and consumers during the transition. + +*If you are a producer or consumer that has **not** used the `ADDED` enumeration to describe duplicated trips, no action is required - you can produce/consume `DUPLICATED` trips without producing/consuming any `ADDED` entities.* + +For a full history of the `DUPLICATED` enumeration, see the [`DUPLICATED` proposal on GitHub](https://github.com/google/transit/pull/221). + +### Using ADDED and DUPLICATED entities in same feed + +#### Producers + +If you are a producer who has been using the `ADDED` enumeration for duplicated trips, to avoid disruption to existing consumers it is recommended that you continue to produce `ADDED` entities for these trips but also add `DUPLICATED` entities for the same trip. + +However, to prevent consumers from accidentally adding the same trip twice, the entities referencing the same trip **must** be linked using the same `trip_id`. You can link the two entities in **one** of two ways: + + 1. `trip.trip_id` of both entities **must** be the same, OR + 2. `trip.trip_id` of the `ADDED` trip **must** be the same as the `DUPLICATED` trip `trip_properties.trip_id` + +Here's an example of the first option (1) to duplicate GTFS `trip_id 1`, with the `trip.trip_id` matching in the `ADDED` and `DUPLICATED` entities: + +~~~ +entity { + id: "ei0" + trip_update { + trip: { + trip_id: "1" // <-- trip_id from static GTFS to copy + schedule_relationship: ADDED + start_date: "20200821" // <-- New trip date + start_time: "11:30:00" // <-- New trip time + } + stop_time_update { + ... + } + } +} + +entity { + id: "ei10" + trip_update { + trip: { + trip_id: "1" // <-- trip_id from static GTFS to copy + schedule_relationship: DUPLICATED + } + trip_properties { + trip_id: "NewTripId987" // <-- New trip_id unique to this trip + start_date: "20200821" // <-- New trip date + start_time: "11:30:00" // <-- New trip time + } + stop_time_update { + ... + } + } +} +~~~ + +Here's an example of the second option (2) to duplicate GTFS `trip_id 1`, with the `trip.trip_id` of the `ADDED` trip matching the `DUPLICATED` trip `trip_properties.trip_id`: + +~~~ +entity { + id: "ei0" + trip_update { + trip: { + trip_id: "NewTripId987" // <-- New trip_id unique to this trip + schedule_relationship: ADDED + start_date: "20200821" // <-- New trip date + start_time: "11:30:00" // <-- New trip time + } + stop_time_update { + ... + } + } +} + +entity { + id: "ei10" + trip_update { + trip: { + trip_id: "1" // <-- trip_id from static GTFS to copy + schedule_relationship: DUPLICATED + } + trip_properties { + trip_id: "NewTripId987" // <-- Matches the ADDED trip.trip_id + start_date: "20200821" // <-- New trip date + start_time: "11:30:00" // <-- New trip time + } + stop_time_update { + ... + } + } +} +~~~ + +It is suggested that you notify existing consumers (e.g., via a developer mailing list) that the use of `ADDED` for duplicated trips is being deprecated by a set deadline and that consumers should start consuming the `DUPLICATED` trips instead. The above strategy being used to match `ADDED` and `DUPLICATED` trip entities should also be mentioned and a link to this migration guide should be included. After the deadline passes, you can remove the `ADDED` entities from your feed and publish only the `DUPLICATED` entities for duplicated trips. + +#### Consumers + +As mentioned above, producers will transition from `ADDED` to `DUPLICATED` enumerations by initially publishing two entities for each duplicated trip, using one of the two above options for matching IDs between the entities. + +Therefore, when a consumer implements support for `DUPLICATED` trips, it is important that consumers: + 1. Ignore any `ADDED` trips that have the same `trip.trip_id` as a `DUPLICATED` trip `trip.trip_id` + 1. Ignore any `ADDED` trips that have the same `trip.trip_id` as a `DUPLICATED` trip `trip_properties.trip_id` \ No newline at end of file diff --git a/gtfs-realtime/spec/en/reference.md b/gtfs-realtime/spec/en/reference.md index 78956a824..428442889 100644 --- a/gtfs-realtime/spec/en/reference.md +++ b/gtfs-realtime/spec/en/reference.md @@ -49,6 +49,7 @@ Fields labeled as **experimental** are subject to change and not yet formally ad * [StopTimeUpdate](#message-stoptimeupdate) * [StopTimeEvent](#message-stoptimeevent) * [ScheduleRelationship](#enum-schedulerelationship) + * [TripProperties](#message-tripproperties) * [VehiclePosition](#message-vehicleposition) * [TripDescriptor](#message-tripdescriptor) * [ScheduleRelationship](#enum-schedulerelationship-1) @@ -130,6 +131,7 @@ Depending on the value of ScheduleRelationship, a TripUpdate can specify: * A trip that proceeds along the schedule. * A trip that proceeds along a route but has no fixed schedule. * A trip that has been added or removed with regard to schedule. +* A new trip that is a copy of an existing trip in static GTFS. It will run at the service date and time specified in TripProperties. The updates can be for future, predicted arrival/departure events, or for past events that already occurred. In most cases information about past events is a measured value thus its uncertainty value is recommended to be 0\. Although there could be cases when this does not hold so it is allowed to have uncertainty value different from 0 for past events. If an update's uncertainty is not 0, either the update is an approximate prediction for a trip that has not completed or the measurement is not precise or the update was a prediction for the past that has not been verified after the event occurred. @@ -145,9 +147,10 @@ Note that the update can describe a trip that has already completed.To this end, |------------------|------------|----------------|-------------------|-------------------| | **trip** | [TripDescriptor](#message-tripdescriptor) | Required | One | The Trip that this message applies to. There can be at most one TripUpdate entity for each actual trip instance. If there is none, that means there is no prediction information available. It does *not* mean that the trip is progressing according to schedule. | | **vehicle** | [VehicleDescriptor](#message-vehicledescriptor) | Optional | One | Additional information on the vehicle that is serving this trip. | -| **stop_time_update** | [StopTimeUpdate](#message-stoptimeupdate) | Conditionally required | Many | Updates to StopTimes for the trip (both future, i.e., predictions, and in some cases, past ones, i.e., those that already happened). The updates must be sorted by stop_sequence, and apply for all the following stops of the trip up to the next specified stop_time_update. At least one stop_time_update must be provided for the trip unless the trip.schedule_relationship is CANCELED - if the trip is canceled, no stop_time_updates need to be provided. | +| **stop_time_update** | [StopTimeUpdate](#message-stoptimeupdate) | Conditionally required | Many | Updates to StopTimes for the trip (both future, i.e., predictions, and in some cases, past ones, i.e., those that already happened). The updates must be sorted by stop_sequence, and apply for all the following stops of the trip up to the next specified stop_time_update. At least one stop_time_update must be provided for the trip unless the trip.schedule_relationship is CANCELED or DUPLICATED - if the trip is canceled, no stop_time_updates need to be provided. If the trip is duplicated, stop_time_updates may be provided to indicate real-time information for the new trip. | | **timestamp** | [uint64](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | Moment at which the vehicle's real-time progress was measured. In POSIX time (i.e., the number of seconds since January 1st 1970 00:00:00 UTC). | | **delay** | [int32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | The current schedule deviation for the trip. Delay should only be specified when the prediction is given relative to some existing schedule in GTFS.
Delay (in seconds) can be positive (meaning that the vehicle is late) or negative (meaning that the vehicle is ahead of schedule). Delay of 0 means that the vehicle is exactly on time.
Delay information in StopTimeUpdates take precedent of trip-level delay information, such that trip-level delay is only propagated until the next stop along the trip with a StopTimeUpdate delay value specified.
Feed providers are strongly encouraged to provide a TripUpdate.timestamp value indicating when the delay value was last updated, in order to evaluate the freshness of the data.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.| +| **trip_properties** | [TripProperties](#message-tripproperties) | Optional | One | Provides the updated properties for the trip.
**Caution:** this message is still **experimental**, and subject to change. It may be formally adopted in the future. | ## _message_ StopTimeEvent @@ -196,6 +199,20 @@ The relation between this StopTime and the static schedule. | **NO_DATA** | No data is given for this stop. It indicates that there is no realtime information available. When set NO_DATA is propagated through subsequent stops so this is the recommended way of specifying from which stop you do not have realtime information. When NO_DATA is set neither arrival nor departure should be supplied. | | **UNSCHEDULED** | The vehicle is operating a frequency-based trip (GTFS frequencies.txt with exact_times = 0). This value should not be used for trips that are not defined in GTFS frequencies.txt, or trips in GTFS frequencies.txt with exact_times = 1. Trips containing `stop_time_updates` with `schedule_relationship: UNSCHEDULED` must also set the TripDescriptor `schedule_relationship: UNSCHEDULED`
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.
. +## _message_ TripProperties + +Defines updated properties of the trip + +**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**_ | +|------------------|------------|----------------|-------------------|-------------------| +| **trip_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Conditionally required | One | Defines the identifier of a new trip that is a duplicate of an existing trip defined in (CSV) GTFS trips.txt but will start at a different service date and/or time (defined using `TripProperties.start_date` and `TripProperties.start_time`). See definition of `trips.trip_id` in (CSV) GTFS. Its value must be different than the ones used in the (CSV) GTFS. This field is required if `schedule_relationship` is `DUPLICATED`, otherwise this field must not be populated and will be ignored by consumers.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | +| **start_date** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Conditionally required | One | Service date on which the duplicated trip will be run. Must be provided in YYYYMMDD format. This field is required if `schedule_relationship` is `DUPLICATED`, otherwise this field must not be populated and will be ignored by consumers.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | +| **start_time** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Conditionally required | One | Defines the departure start time of the trip when it’s duplicated. See definition of `stop_times.departure_time` in (CSV) GTFS. Scheduled arrival and departure times for the duplicated trip are calculated based on the offset between the original trip `departure_time` and this field. For example, if a GTFS trip has stop A with a `departure_time` of `10:00:00` and stop B with `departure_time` of `10:01:00`, and this field is populated with the value of `10:30:00`, stop B on the duplicated trip will have a scheduled `departure_time` of `10:31:00`. Real-time prediction `delay` values are applied to this calculated schedule time to determine the predicted time. For example, if a departure `delay` of `30` is provided for stop B, then the predicted departure time is `10:31:30`. Real-time prediction `time` values do not have any offset applied to them and indicate the predicted time as provided. For example, if a departure `time` representing 10:31:30 is provided for stop B, then the predicted departure time is `10:31:30`.This field is required if `schedule_relationship` is `DUPLICATED`, otherwise this field must not be populated and will be ignored by consumers.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | + ## _message_ VehiclePosition Realtime positioning information for a given vehicle. @@ -378,7 +395,7 @@ TripDescriptor.route_id cannot be used within an Alert EntitySelector to specify | _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ | |------------------|------------|----------------|-------------------|-------------------| -| **trip_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Conditionally required | One | The trip_id from the GTFS feed that this selector refers to. For non frequency-based trips (trips not defined in GTFS frequencies.txt), this field is enough to uniquely identify the trip. For frequency-based trips defined in GTFS frequencies.txt, trip_id, start_time, and start_date are all required. For scheduled-based trips (trips not defined in GTFS frequencies.txt), trip_id can only be omitted if the trip can be uniquely identified by a combination of route_id, direction_id, start_time, and start_date, and all those fields are provided. | +| **trip_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Conditionally required | One | The trip_id from the GTFS feed that this selector refers to. For non frequency-based trips (trips not defined in GTFS frequencies.txt), this field is enough to uniquely identify the trip. For frequency-based trips defined in GTFS frequencies.txt, trip_id, start_time, and start_date are all required. For scheduled-based trips (trips not defined in GTFS frequencies.txt), trip_id can only be omitted if the trip can be uniquely identified by a combination of route_id, direction_id, start_time, and start_date, and all those fields are provided. When schedule_relationship is DUPLICATED within a TripUpdate, the trip_id identifies the trip from static GTFS to be duplicated. When schedule_relationship is DUPLICATED within a VehiclePosition, the trip_id identifies the new duplicate trip and must contain the value for the corresponding TripUpdate.TripProperties.trip_id. | | **route_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Conditionally required | One | The route_id from the GTFS that this selector refers to. If trip_id is omitted, route_id, direction_id, start_time, and schedule_relationship=SCHEDULED must all be set to identify a trip instance. TripDescriptor.route_id should not be used within an Alert EntitySelector to specify a route-wide alert that affects all trips for a route - use EntitySelector.route_id instead. | | **direction_id** | [uint32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Conditionally required | One | The direction_id from the GTFS feed trips.txt file, indicating the direction of travel for trips this selector refers to. If trip_id is omitted, direction_id must be provided.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.
| | **start_time** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Conditionally required | One | The initially scheduled start time of this trip instance. When the trip_id corresponds to a non-frequency-based trip, this field should either be omitted or be equal to the value in the GTFS feed. When the trip_id correponds to a frequency-based trip defined in GTFS frequencies.txt, start_time is required and must be specified for trip updates and vehicle positions. If the trip corresponds to exact_times=1 GTFS record, then start_time must be some multiple (including zero) of headway_secs later than frequencies.txt start_time for the corresponding time period. If the trip corresponds to exact_times=0, then its start_time may be arbitrary, and is initially expected to be the first departure of the trip. Once established, the start_time of this frequency-based exact_times=0 trip should be considered immutable, even if the first departure time changes -- that time change may instead be reflected in a StopTimeUpdate. If trip_id is omitted, start_time must be provided. Format and semantics of the field is same as that of GTFS/frequencies.txt/start_time, e.g., 11:15:35 or 25:15:35. | @@ -397,6 +414,7 @@ The relation between this trip and the static schedule. If a trip is done in acc | **ADDED** | An extra trip that was added in addition to a running schedule, for example, to replace a broken vehicle or to respond to sudden passenger load. *NOTE: Currently, behavior is unspecified for feeds that use this mode. There are discussions on the GTFS GitHub [(1)](https://github.com/google/transit/issues/106) [(2)](https://github.com/google/transit/pull/221) [(3)](https://github.com/google/transit/pull/219) around fully specifying or deprecating ADDED trips and the documentation will be updated when those discussions are finalized.* | | **UNSCHEDULED** | A trip that is running with no schedule associated to it - this value is used to identify trips defined in GTFS frequencies.txt with exact_times = 0. It should not be used to describe trips not defined in GTFS frequencies.txt, or trips in GTFS frequencies.txt with exact_times = 1. Trips with `schedule_relationship: UNSCHEDULED` must also set all StopTimeUpdates `schedule_relationship: UNSCHEDULED`| | **CANCELED** | A trip that existed in the schedule but was removed. | +| **DUPLICATED** | A new trip that is the same as an existing scheduled trip except for service start date and time. Used with `TripUpdate.TripProperties.trip_id`, `TripUpdate.TripProperties.start_date`, and `TripUpdate.TripProperties.start_time` to copy an existing trip from static GTFS but start at a different service date and/or time. Duplicating a trip is allowed if the service related to the original trip in (CSV) GTFS (in `calendar.txt` or `calendar_dates.txt`) is operating within the next 30 days. The trip to be duplicated is identified via `TripUpdate.TripDescriptor.trip_id`.

This enumeration does not modify the existing trip referenced by `TripUpdate.TripDescriptor.trip_id` - if a producer wants to cancel the original trip, it must publish a separate `TripUpdate` with the value of CANCELED. Trips defined in GTFS `frequencies.txt` with `exact_times` that is empty or equal to `0` cannot be duplicated. The `VehiclePosition.TripDescriptor.trip_id` for the new trip must contain the matching value from `TripUpdate.TripProperties.trip_id` and `VehiclePosition.TripDescriptor.ScheduleRelationship` must also be set to `DUPLICATED`.

*Existing producers and consumers that were using the ADDED enumeration to represent duplicated trips must follow the [migration guide](/gtfs-realtime/spec/en/examples/migration-duplicated.md) to transition to the DUPLICATED enumeration.* | ## _message_ VehicleDescriptor diff --git a/gtfs-realtime/spec/en/trip-updates.md b/gtfs-realtime/spec/en/trip-updates.md index 67ba5a653..ec45bee66 100644 --- a/gtfs-realtime/spec/en/trip-updates.md +++ b/gtfs-realtime/spec/en/trip-updates.md @@ -58,6 +58,7 @@ The information provided by the trip descriptor depends on the schedule relation | **Added** | This trip was not scheduled and has been added. For example, to cope with demand, or replace a broken down vehicle. | | **Unscheduled** | This trip is running and is never associated with a schedule. For example, if there is no schedule and the buses run on a shuttle service. | | **Canceled** | This trip was scheduled, but is now removed. | +| **Duplicated** | This new trip is a copy of an existing trip in static GTFS except for the service start date and time. The new trip will run at the service date and time specified in TripProperties. | In most cases, you should provide the trip_id of the scheduled trip in GTFS that this update relates to. From 993c2c0b3222c6ded8bd47e9baea1d5690a4ef13 Mon Sep 17 00:00:00 2001 From: Sean Barbeau Date: Mon, 10 Aug 2020 09:44:20 -0400 Subject: [PATCH 16/29] fix: Add extensions to TripProperties, remove extra comment (#238) This is an editorial follow-up to https://github.com/google/transit/pull/221 to fix two items: * New messages should have the extensions fields to allow 3rd party and internal extensions - this commit adds these fields * An erroneous comment was added that labeled schedule_relationship as experimental - this commit removes it --- gtfs-realtime/proto/gtfs-realtime.proto | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/gtfs-realtime/proto/gtfs-realtime.proto b/gtfs-realtime/proto/gtfs-realtime.proto index 373ae2a64..88581ab05 100644 --- a/gtfs-realtime/proto/gtfs-realtime.proto +++ b/gtfs-realtime/proto/gtfs-realtime.proto @@ -323,6 +323,14 @@ message TripUpdate { // populated and will be ignored by consumers. // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future. optional string start_time = 3; + + // 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; } optional TripProperties trip_properties = 6; @@ -676,7 +684,6 @@ message TripDescriptor { // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future. DUPLICATED = 6; } - // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future. optional ScheduleRelationship schedule_relationship = 4; // The extensions namespace allows 3rd-party developers to extend the From b28d6efab405556789b724682b57802379e70932 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Fontolliet?= <39090838+lfontolliet@users.noreply.github.com> Date: Thu, 10 Sep 2020 09:49:51 -0400 Subject: [PATCH 17/29] Proposal: Support multi-car crowding in GTFS-RT (#237) --- gtfs-realtime/proto/gtfs-realtime.proto | 85 ++++++++++++++++++++++--- gtfs-realtime/spec/en/reference.md | 37 ++++++++--- 2 files changed, 104 insertions(+), 18 deletions(-) diff --git a/gtfs-realtime/proto/gtfs-realtime.proto b/gtfs-realtime/proto/gtfs-realtime.proto index 88581ab05..ae914ad35 100644 --- a/gtfs-realtime/proto/gtfs-realtime.proto +++ b/gtfs-realtime/proto/gtfs-realtime.proto @@ -394,41 +394,49 @@ message VehiclePosition { } optional CongestionLevel congestion_level = 6; - // The degree of passenger occupancy of the vehicle. This field is still - // experimental, and subject to change. It may be formally adopted in the - // future. + // The degree of passenger occupancy of the vehicle or carriage. This field is still + // experimental, and subject to change. It may be formally adopted in the future. enum OccupancyStatus { - // The vehicle is considered empty by most measures, and has few or no + // The vehicle or carriage is considered empty by most measures, and has few or no // passengers onboard, but is still accepting passengers. EMPTY = 0; - // The vehicle has a relatively large percentage of seats available. + // The vehicle or carriage has a relatively large percentage of seats available. // What percentage of free seats out of the total seats available is to be // considered large enough to fall into this category is determined at the // discretion of the producer. MANY_SEATS_AVAILABLE = 1; - // The vehicle has a relatively small percentage of seats available. + // The vehicle or carriage has a relatively small percentage of seats available. // What percentage of free seats out of the total seats available is to be // considered small enough to fall into this category is determined at the // discretion of the feed producer. FEW_SEATS_AVAILABLE = 2; - // The vehicle can currently accommodate only standing passengers. + // The vehicle or carriage can currently accommodate only standing passengers. STANDING_ROOM_ONLY = 3; - // The vehicle can currently accommodate only standing passengers + // The vehicle or carriage can currently accommodate only standing passengers // and has limited space for them. CRUSHED_STANDING_ROOM_ONLY = 4; - // The vehicle is considered full by most measures, but may still be + // The vehicle or carriage is considered full by most measures, but may still be // allowing passengers to board. FULL = 5; - // The vehicle is not accepting additional passengers. + // The vehicle or carriage is not accepting passengers, but usually accepts passengers for boarding. NOT_ACCEPTING_PASSENGERS = 6; + // The vehicle or carriage doesn't have any occupancy data available at that time. + NO_DATA_AVAILABLE = 7; + + // The vehicle or carriage is not boardable and never accepts passengers. + // Useful for special vehicles or carriages (engine, maintenance carriage, etc…). + NOT_BOARDABLE = 8; + } + // If multi_carriage_status is populated with per-carriage OccupancyStatus, + // then this field should describe the entire vehicle with all carriages accepting passengers considered. optional OccupancyStatus occupancy_status = 9; // A percentage value representing the degree of passenger occupancy of the vehicle. @@ -437,9 +445,66 @@ message VehiclePosition { // including both seated and standing capacity, and current operating regulations allow. // It is possible that the value goes over 100 if there are currently more passengers than what the vehicle was designed for. // The precision of occupancy_percentage should be low enough that you can't track a single person boarding and alighting for privacy reasons. + // If multi_carriage_status is populated with per-carriage occupancy_percentage, + // then this field should describe the entire vehicle with all carriages accepting passengers considered. // This field is still experimental, and subject to change. It may be formally adopted in the future. optional uint32 occupancy_percentage = 10; + // Carriage specific details, used for vehicles composed of several carriages + // This message/field is still experimental, and subject to change. It may be formally adopted in the future. + message CarriageDetails { + + // Identification of the carriage. Should be unique per vehicle. + optional string id = 1; + + // User visible label that may be shown to the passenger to help identify + // the carriage. Example: "7712", "Car ABC-32", etc... + // This message/field is still experimental, and subject to change. It may be formally adopted in the future. + optional string label = 2; + + // Occupancy status for this given carriage, in this vehicle + // This message/field is still experimental, and subject to change. It may be formally adopted in the future. + optional OccupancyStatus occupancy_status = 3 [default = NO_DATA_AVAILABLE]; + + // Occupancy percentage for this given carriage, in this vehicle. + // Follows the same rules as "VehiclePosition.occupancy_percentage" + // -1 in case data is not available for this given carriage (as protobuf defaults to 0 otherwise) + // This message/field is still experimental, and subject to change. It may be formally adopted in the future. + optional int32 occupancy_percentage = 4 [default = -1]; + + // Identifies the order of this carriage with respect to the other + // carriages in the vehicle's list of CarriageDetails. + // The first carriage in the direction of travel must have a value of 1. + // The second value corresponds to the second carriage in the direction + // of travel and must have a value of 2, and so forth. + // For example, the first carriage in the direction of travel has a value of 1. + // If the second carriage in the direction of travel has a value of 3, + // consumers will discard data for all carriages (i.e., the multi_carriage_details field). + // Carriages without data must be represented with a valid carriage_sequence number and the fields + // without data should be omitted (alternately, those fields could also be included and set to the "no data" values). + // This message/field is still experimental, and subject to change. It may be formally adopted in the future. + optional uint32 carriage_sequence = 5; + + // 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; + } + + // Details of the multiple carriages of this given vehicle. + // The first occurrence represents the first carriage of the vehicle, + // given the current direction of travel. + // The number of occurrences of the multi_carriage_details + // field represents the number of carriages of the vehicle. + // It also includes non boardable carriages, + // like engines, maintenance carriages, etc… as they provide valuable + // information to passengers about where to stand on a platform. + // This message/field is still experimental, and subject to change. It may be formally adopted in the future. + repeated CarriageDetails multi_carriage_details = 11; + // 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. diff --git a/gtfs-realtime/spec/en/reference.md b/gtfs-realtime/spec/en/reference.md index 428442889..387639c7f 100644 --- a/gtfs-realtime/spec/en/reference.md +++ b/gtfs-realtime/spec/en/reference.md @@ -58,6 +58,7 @@ Fields labeled as **experimental** are subject to change and not yet formally ad * [VehicleStopStatus](#enum-vehiclestopstatus) * [CongestionLevel](#enum-congestionlevel) * [OccupancyStatus](#enum-occupancystatus) + * [CarriageDetails](#message-CarriageDetails) * [Alert](#message-alert) * [TimeRange](#message-timerange) * [EntitySelector](#message-entityselector) @@ -229,8 +230,9 @@ Realtime positioning information for a given vehicle. | **current_status** | [VehicleStopStatus](#enum-vehiclestopstatus) | Optional | One | The exact status of the vehicle with respect to the current stop. Ignored if current_stop_sequence is missing. | | **timestamp** | [uint64](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | Moment at which the vehicle's position was measured. In POSIX time (i.e., number of seconds since January 1st 1970 00:00:00 UTC). | | **congestion_level** | [CongestionLevel](#enum-congestionlevel) | Optional | One | -| _**occupancy_status**_ | _[OccupancyStatus](#enum-occupancystatus)_ | _Optional_ | One | The degree of passenger occupancy of the vehicle.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.| -| **occupancy_percentage** | [uint32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | A percentage value representing the degree of passenger occupancy of the vehicle. The value 100 should represent total the maximum occupancy the vehicle was designed for, including both seating and standing capacity, and current operating regulations allow. It's not impossible that the value goes over 100 if there are currently more passenger than the vehicle was designed for. The precision of occupancy_percentage should be low enough that you can't track a single person boarding and alighting for privacy reasons.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | +| **occupancy_status** | [OccupancyStatus](#enum-occupancystatus) | _Optional_ | One | The degree of passenger occupancy of the vehicle or carriage. If multi_carriage_details is populated with per-carriage OccupancyStatus, then this field should describe the entire vehicle with all carriages accepting passengers considered.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.| +| **occupancy_percentage** | [uint32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | A percentage value representing the degree of passenger occupancy of the vehicle. The value 100 should represent total the maximum occupancy the vehicle was designed for, including both seating and standing capacity, and current operating regulations allow. It's not impossible that the value goes over 100 if there are currently more passenger than the vehicle was designed for. The precision of occupancy_percentage should be low enough that you can't track a single person boarding and alighting for privacy reasons. If multi_carriage_details is populated with per-carriage occupancy_percentage, then this field should describe the entire vehicle with all carriages accepting passengers considered.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | +| **multi_carriage_details** | [CarriageDetails](#message-CarriageDetails) | Optional | Many | Details of the multiple carriages of this given vehicle. The first occurrence represents the first carriage of the vehicle, **given the current direction of travel**. The number of occurrences of the multi_carriage_details field represents the number of carriages of the vehicle. It also includes non boardable carriages, like engines, maintenance carriages, etc… as they provide valuable information to passengers about where to stand on a platform.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | ## _enum_ VehicleStopStatus @@ -259,7 +261,7 @@ Congestion level that is affecting this vehicle. ## _enum OccupancyStatus_ -The degree of passenger occupancy for the vehicle. +The degree of passenger occupancy for the vehicle or carriage. **Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. @@ -268,12 +270,31 @@ The degree of passenger occupancy for the vehicle. | _**Value**_ | _**Comment**_ | |-------------|---------------| | _**EMPTY**_ | _The vehicle is considered empty by most measures, and has few or no passengers onboard, but is still accepting passengers._ | -| _**MANY_SEATS_AVAILABLE**_ | _The vehicle has a large percentage of seats available. What percentage of free seats out of the total seats available is to be considered large enough to fall into this category is determined at the discretion of the producer._ | -| _**FEW_SEATS_AVAILABLE**_ | _The vehicle has a small percentage of seats available. What percentage of free seats out of the total seats available is to be considered small enough to fall into this category is determined at the discretion of the producer._ | -| _**STANDING_ROOM_ONLY**_ | _The vehicle can currently accommodate only standing passengers._ | -| _**CRUSHED_STANDING_ROOM_ONLY**_ | _The vehicle can currently accommodate only standing passengers and has limited space for them._ | +| _**MANY_SEATS_AVAILABLE**_ | _The vehicle or carriage has a large percentage of seats available. What percentage of free seats out of the total seats available is to be considered large enough to fall into this category is determined at the discretion of the producer._ | +| _**FEW_SEATS_AVAILABLE**_ | _The vehicle or carriage has a small percentage of seats available. What percentage of free seats out of the total seats available is to be considered small enough to fall into this category is determined at the discretion of the producer._ | +| _**STANDING_ROOM_ONLY**_ | _The vehicle or carriage can currently accommodate only standing passengers._ | +| _**CRUSHED_STANDING_ROOM_ONLY**_ | _The vehicle or carriage can currently accommodate only standing passengers and has limited space for them._ | | _**FULL**_ | _The vehicle is considered full by most measures, but may still be allowing passengers to board._ | -| _**NOT_ACCEPTING_PASSENGERS**_ | _The vehicle can not accept passengers._ | +| _**NOT_ACCEPTING_PASSENGERS**_ | _The vehicle or carriage is not accepting passengers. The vehicle or carriage usually accepts passengers for boarding._ | +| _**NO_DATA_AVAILABLE**_ | _The vehicle or carriage doesn't have any occupancy data available at that time._ | +| _**NOT_BOARDABLE**_ | _The vehicle or carriage is not boardable and never accepts passengers. Useful for special vehicles or carriages (engine, maintenance carriage, etc…)._ | + + +## _message_ CarriageDetails + +Carriage specific details, used for vehicles composed of several carriages + +**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**_ | +|------------------|------------|----------------|-------------------|-------------------| +| **id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | Identification of the carriage. Should be unique per vehicle.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | +| **label** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | User visible label that may be shown to the passenger to help identify the carriage. Example: "7712", "Car ABC-32", etc...
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | +| **occupancy_status** | [OccupancyStatus](#enum-occupancystatus) | Optional | One | Occupancy status for this given carriage, in this vehicle. Default is set to `NO_DATA_AVAILABLE`.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.| +| **occupancy_percentage** | [int32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | Occupancy percentage for this given carriage, in this vehicle. Follows the same rules as "VehiclePosition.occupancy_percentage". Use -1 in case data is not available for this given carriage.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | +| **carriage_sequence** | [uint32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Required | One | Identifies the order of this carriage with respect to the other carriages in the vehicle's list of CarriageStatus. The first carriage in the direction of travel must have a value of 1. The second value corresponds to the second carriage in the direction of travel and must have a value of 2, and so forth. For example, the first carriage in the direction of travel has a value of 1. If the second carriage in the direction of travel has a value of 3, consumers will discard data for all carriages (i.e., the multi_carriage_details field). Carriages without data must be represented with a valid carriage_sequence number and the fields without data should be omitted (alternately, those fields could also be included and set to the "no data" values).
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | ## _message_ Alert From 0fb98c32f053f1455db6a2842493a9889c09e964 Mon Sep 17 00:00:00 2001 From: Alexej Ababilov Date: Mon, 28 Sep 2020 14:38:35 +1000 Subject: [PATCH 18/29] Change type of headway_secs to positive integer headway_secs=0 does not have a physical meaning. This must be the time between departures for the same stop for a single trip. --- gtfs/spec/en/reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gtfs/spec/en/reference.md b/gtfs/spec/en/reference.md index 04a7904e1..d6650fc83 100644 --- a/gtfs/spec/en/reference.md +++ b/gtfs/spec/en/reference.md @@ -310,7 +310,7 @@ File: **Optional** | `trip_id` | ID referencing `trips.trip_id` | **Required** | Identifies a trip to which the specified headway of service applies. | | `start_time` | Time | **Required** | Time at which the first vehicle departs from the first stop of the trip with the specified headway. | | `end_time` | Time | **Required** | Time at which service changes to a different headway (or ceases) at the first stop in the trip. | -| `headway_secs` | Non-negative integer | **Required** | Time, in seconds, between departures from the same stop (headway) for the trip, during the time interval specified by `start_time` and `end_time`. Multiple headways for the same trip are allowed, but may not overlap. New headways may start at the exact time the previous headway ends. | +| `headway_secs` | Positive integer | **Required** | Time, in seconds, between departures from the same stop (headway) for the trip, during the time interval specified by `start_time` and `end_time`. Multiple headways for the same trip are allowed, but may not overlap. New headways may start at the exact time the previous headway ends. | | `exact_times` | Enum | Optional | Indicates the type of service for a trip. See the file description for more information. Valid options are:

`0` or empty - Frequency-based trips.
`1` - Schedule-based trips with the exact same headway throughout the day. In this case the `end_time` value must be greater than the last desired trip `start_time` but less than the last desired trip start_time + `headway_secs`. | ### transfers.txt From 480ad2e23dc6869f942520e3a08d90dcaf72ac46 Mon Sep 17 00:00:00 2001 From: Sean Barbeau Date: Thu, 12 Nov 2020 11:49:44 -0500 Subject: [PATCH 19/29] Proposal: Support stop assignments in GTFS-RT (#219) --- gtfs-realtime/proto/gtfs-realtime.proto | 31 +++++++++++++++++++++++++ gtfs-realtime/spec/en/reference.md | 22 ++++++++++++++---- 2 files changed, 49 insertions(+), 4 deletions(-) diff --git a/gtfs-realtime/proto/gtfs-realtime.proto b/gtfs-realtime/proto/gtfs-realtime.proto index ae914ad35..730c97b96 100644 --- a/gtfs-realtime/proto/gtfs-realtime.proto +++ b/gtfs-realtime/proto/gtfs-realtime.proto @@ -242,6 +242,37 @@ message TripUpdate { optional ScheduleRelationship schedule_relationship = 5 [default = SCHEDULED]; + // Provides the updated values for the stop time. + // NOTE: This message is still experimental, and subject to change. It may be formally adopted in the future. + message StopTimeProperties { + // Supports real-time stop assignments. Refers to a stop_id defined in the GTFS stops.txt. + // The new assigned_stop_id should not result in a significantly different trip experience for the end user than + // the stop_id defined in GTFS stop_times.txt. In other words, the end user should not view this new stop_id as an + // "unusual change" if the new stop was presented within an app without any additional context. + // For example, this field is intended to be used for platform assignments by using a stop_id that belongs to the + // same station as the stop originally defined in GTFS stop_times.txt. + // To assign a stop without providing any real-time arrival or departure predictions, populate this field and set + // StopTimeUpdate.schedule_relationship = NO_DATA. + // If this field is populated, it is preferred to omit `StopTimeUpdate.stop_id` and use only `StopTimeUpdate.stop_sequence`. If + // `StopTimeProperties.assigned_stop_id` and `StopTimeUpdate.stop_id` are populated, `StopTimeUpdate.stop_id` must match `assigned_stop_id`. + // Platform assignments should be reflected in other GTFS-realtime fields as well + // (e.g., `VehiclePosition.stop_id`). + // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future. + optional string assigned_stop_id = 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; + } + + // Realtime updates for certain properties defined within GTFS stop_times.txt + // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future. + optional StopTimeProperties stop_time_properties = 6; + // 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. diff --git a/gtfs-realtime/spec/en/reference.md b/gtfs-realtime/spec/en/reference.md index 387639c7f..a49a21211 100644 --- a/gtfs-realtime/spec/en/reference.md +++ b/gtfs-realtime/spec/en/reference.md @@ -49,7 +49,8 @@ Fields labeled as **experimental** are subject to change and not yet formally ad * [StopTimeUpdate](#message-stoptimeupdate) * [StopTimeEvent](#message-stoptimeevent) * [ScheduleRelationship](#enum-schedulerelationship) - * [TripProperties](#message-tripproperties) + * [StopTimeProperties](#message-stoptimeproperties) + * [TripProperties](#message-tripproperties) * [VehiclePosition](#message-vehicleposition) * [TripDescriptor](#message-tripdescriptor) * [ScheduleRelationship](#enum-schedulerelationship-1) @@ -181,11 +182,12 @@ The update is linked to a specific stop either through stop_sequence or stop_id, | _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ | |------------------|------------|----------------|-------------------|-------------------| -| **stop_sequence** | [uint32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Conditionally required | One | Must be the same as in stop_times.txt in the corresponding GTFS feed. Either stop_sequence or stop_id must be provided within a StopTimeUpdate - both fields cannot be empty. stop_sequence is required for trips that visit the same stop_id more than once (e.g., a loop) to disambiguate which stop the prediction is for. | -| **stop_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Conditionally required | One | Must be the same as in stops.txt in the corresponding GTFS feed. Either stop_sequence or stop_id must be provided within a StopTimeUpdate - both fields cannot be empty. | +| **stop_sequence** | [uint32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Conditionally required | One | Must be the same as in stop_times.txt in the corresponding GTFS feed. Either stop_sequence or stop_id must be provided within a StopTimeUpdate - both fields cannot be empty. stop_sequence is required for trips that visit the same stop_id more than once (e.g., a loop) to disambiguate which stop the prediction is for. If `StopTimeProperties.assigned_stop_id` is populated, then `stop_sequence` must be populated. | +| **stop_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Conditionally required | One | Must be the same as in stops.txt in the corresponding GTFS feed. Either stop_sequence or stop_id must be provided within a StopTimeUpdate - both fields cannot be empty. If `StopTimeProperties.assigned_stop_id` is populated, it is preferred to omit `stop_id` and use only `stop_sequence`. If `StopTimeProperties.assigned_stop_id` and `stop_id` are populated, `stop_id` must match `assigned_stop_id`. | | **arrival** | [StopTimeEvent](#message-stoptimeevent) | Conditionally required | One | If schedule_relationship is empty or SCHEDULED, either arrival or departure must be provided within a StopTimeUpdate - both fields cannot be empty. arrival and departure may both be empty when schedule_relationship is SKIPPED. If schedule_relationship is NO_DATA, arrival and departure must be empty. | | **departure** | [StopTimeEvent](#message-stoptimeevent) | Conditionally required | One | If schedule_relationship is empty or SCHEDULED, either arrival or departure must be provided within a StopTimeUpdate - both fields cannot be empty. arrival and departure may both be empty when schedule_relationship is SKIPPED. If schedule_relationship is NO_DATA, arrival and departure must be empty. | | **schedule_relationship** | [ScheduleRelationship](#enum-schedulerelationship) | Optional | One | The default relationship is SCHEDULED. | +| **stop_time_properties** | [StopTimeProperties](#message-stoptimeproperties) | Optional | One | Realtime updates for certain properties defined within GTFS stop_times.txt
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.
. | ## _enum_ ScheduleRelationship @@ -200,6 +202,18 @@ The relation between this StopTime and the static schedule. | **NO_DATA** | No data is given for this stop. It indicates that there is no realtime information available. When set NO_DATA is propagated through subsequent stops so this is the recommended way of specifying from which stop you do not have realtime information. When NO_DATA is set neither arrival nor departure should be supplied. | | **UNSCHEDULED** | The vehicle is operating a frequency-based trip (GTFS frequencies.txt with exact_times = 0). This value should not be used for trips that are not defined in GTFS frequencies.txt, or trips in GTFS frequencies.txt with exact_times = 1. Trips containing `stop_time_updates` with `schedule_relationship: UNSCHEDULED` must also set the TripDescriptor `schedule_relationship: UNSCHEDULED`
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.
. +## _message_ StopTimeProperties + +Realtime update for certain properties defined within GTFS stop_times.txt. + +**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**_ | +|------------------|------------|----------------|-------------------|-------------------| +| **assigned_stop_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | Supports real-time stop assignments. Refers to a `stop_id` defined in the GTFS `stops.txt`.
The new `assigned_stop_id` should not result in a significantly different trip experience for the end user than the `stop_id` defined in GTFS `stop_times.txt`. In other words, the end user should not view this new `stop_id` as an "unusual change" if the new stop was presented within an app without any additional context. For example, this field is intended to be used for platform assignments by using a `stop_id` that belongs to the same station as the stop originally defined in GTFS `stop_times.txt`.
To assign a stop without providing any real-time arrival or departure predictions, populate this field and set `StopTimeUpdate.schedule_relationship = NO_DATA`.
If this field is populated, `StopTimeUpdate.stop_sequence` must be populated and `StopTimeUpdate.stop_id` should not be populated. Stop assignments should be reflected in other GTFS-realtime fields as well (e.g., `VehiclePosition.stop_id`).
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.
. | + ## _message_ TripProperties Defines updated properties of the trip @@ -226,7 +240,7 @@ Realtime positioning information for a given vehicle. | **vehicle** | [VehicleDescriptor](#message-vehicledescriptor) | Optional | One | Additional information on the vehicle that is serving this trip. Each entry should have a **unique** vehicle id. | | **position** | [Position](#message-position) | Optional | One | Current position of this vehicle. | | **current_stop_sequence** | [uint32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | The stop sequence index of the current stop. The meaning of current_stop_sequence (i.e., the stop that it refers to) is determined by current_status. If current_status is missing IN_TRANSIT_TO is assumed. | -| **stop_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | Identifies the current stop. The value must be the same as in stops.txt in the corresponding GTFS feed. | +| **stop_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | Identifies the current stop. The value must be the same as in stops.txt in the corresponding GTFS feed. If `StopTimeProperties.assigned_stop_id` is used to assign a `stop_id`, this field should also reflect the change in `stop_id`. | | **current_status** | [VehicleStopStatus](#enum-vehiclestopstatus) | Optional | One | The exact status of the vehicle with respect to the current stop. Ignored if current_stop_sequence is missing. | | **timestamp** | [uint64](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | Moment at which the vehicle's position was measured. In POSIX time (i.e., number of seconds since January 1st 1970 00:00:00 UTC). | | **congestion_level** | [CongestionLevel](#enum-congestionlevel) | Optional | One | From e60c620953b33ebd13b3d42220b8c239d5d8f58f Mon Sep 17 00:00:00 2001 From: Alexej Ababilov Date: Tue, 5 Jan 2021 09:27:10 +1100 Subject: [PATCH 20/29] Define positive and non-null number field types (#251) Define positive and non-null number field types They are already used in the table descriptions. Co-authored-by: scmcca --- gtfs/spec/en/reference.md | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/gtfs/spec/en/reference.md b/gtfs/spec/en/reference.md index d6650fc83..aa760f41e 100644 --- a/gtfs/spec/en/reference.md +++ b/gtfs/spec/en/reference.md @@ -8,9 +8,10 @@ This document defines the format and structure of the files that comprise a GTFS 1. [Term Definitions](#term-definitions) 2. [Field Types](#field-types) -3. [Dataset Files](#dataset-files) -4. [File Requirements](#file-requirements) -5. [Field Definitions](#field-definitions) +3. [Field Signs](#field-signs) +4. [Dataset Files](#dataset-files) +5. [File Requirements](#file-requirements) +6. [Field Definitions](#field-definitions) - [agency.txt](#agencytxt) - [stops.txt](#stopstxt) - [routes.txt](#routestxt) @@ -54,14 +55,22 @@ This section defines terms that are used throughout this document. - **Language Code** - An IETF BCP 47 language code. For an introduction to IETF BCP 47, refer to [http://www.rfc-editor.org/rfc/bcp/bcp47.txt](http://www.rfc-editor.org/rfc/bcp/bcp47.txt) and [http://www.w3.org/International/articles/language-tags/](http://www.w3.org/International/articles/language-tags/).
*Example: `en` for English, `en-US` for American English or `de` for German.* - **Latitude** - WGS84 latitude in decimal degrees. The value must be greater than or equal to -90.0 and less than or equal to 90.0. *
Example: `41.890169` for the Colosseum in Rome.* - **Longitude** - WGS84 longitude in decimal degrees. The value must be greater than or equal to -180.0 and less than or equal to 180.0.
*Example: `12.492269` for the Colosseum in Rome.* -- **Non-negative Float** - A floating point number greater than or equal to 0. -- **Non-negative Integer** - A integer greater than or equal to 0. +- **Float** - A floating point number. +- **Integer** - An integer. - **Phone number** - A phone number. - **Time** - Time in the HH:MM:SS format (H:MM:SS is also accepted). The time is measured from "noon minus 12h" of the service day (effectively midnight except for days on which daylight savings time changes occur). For times occurring after midnight, enter the time as a value greater than 24:00:00 in HH:MM:SS local time for the day on which the trip schedule begins.
*Example: `14:30:00` for 2:30PM or `25:35:00` for 1:35AM on the next day.* - **Text** - A string of UTF-8 characters, which is aimed to be displayed and which must therefore be human readable. - **Timezone** - TZ timezone from the [https://www.iana.org/time-zones](https://www.iana.org/time-zones). Timezone names never contain the space character but may contain an underscore. Refer to [http://en.wikipedia.org/wiki/List\_of\_tz\_zones](http://en.wikipedia.org/wiki/List\_of\_tz\_zones) for a list of valid values.
*Example: `Asia/Tokyo`, `America/Los_Angeles` or `Africa/Cairo`.* - **URL** - A fully qualified URL that includes http:// or https://, and any special characters in the URL must be correctly escaped. See the following [http://www.w3.org/Addressing/URL/4\_URI\_Recommentations.html](http://www.w3.org/Addressing/URL/4\_URI\_Recommentations.html) for a description of how to create fully qualified URL values. +## Field Signs +Signs applicable to Float or Integer field types: +* **Non-negative** - Greater than or equal to 0. +* **Non-zero** - Not equal to 0. +* **Positive** - Greater than 0. + +_Example: **Non-negative Float** - A floating point number greater than or equal to 0._ + ## Dataset Files This specification defines the following files: From 3d94a4c90949a07d89dae456032b2934af906591 Mon Sep 17 00:00:00 2001 From: Tim Millet Date: Mon, 4 Jan 2021 17:46:45 -0500 Subject: [PATCH 21/29] Clarification of stop_times.stop_id (#258) * Clarification of stop_times.stop_id - It explicitly tells that the referenced locations must be stops/platforms and have a `stops.location_type` value of `0` or empty. - Future-proof phrasing: it references only what must be done. --- gtfs/spec/en/reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gtfs/spec/en/reference.md b/gtfs/spec/en/reference.md index aa760f41e..141d7a90d 100644 --- a/gtfs/spec/en/reference.md +++ b/gtfs/spec/en/reference.md @@ -214,7 +214,7 @@ File: **Required** | `trip_id` | ID referencing `trips.trip_id` | **Required** | Identifies a trip. | | `arrival_time` | Time | **Conditionally required** | Arrival time at a specific stop for a specific trip on a route. If there are not separate times for arrival and departure at a stop, enter the same value for `arrival_time` and `departure_time`. For times occurring after midnight on the service day, enter the time as a value greater than 24:00:00 in HH:MM:SS local time for the day on which the trip schedule begins.

Scheduled stops where the vehicle strictly adheres to the specified arrival and departure times are timepoints. If this stop is not a timepoint, it is recommended to provide an estimated or interpolated time. If this is not available, arrival_time can be left empty. Further, indicate that interpolated times are provided with `timepoint`=`0`. If interpolated times are indicated with `timepoint`=`0`, then time points must be indicated with `timepoint`=`1`. Provide arrival times for all stops that are time points. An arrival time must be specified for the first and the last stop in a trip.| | `departure_time` | Time | **Conditionally required** | Departure time from a specific stop for a specific trip on a route. For times occurring after midnight on the service day, enter the time as a value greater than 24:00:00 in HH:MM:SS local time for the day on which the trip schedule begins. If there are not separate times for arrival and departure at a stop, enter the same value for `arrival_time` and `departure_time`. See the `arrival_time` description for more details about using timepoints correctly.

The `departure_time` field should specify time values whenever possible, including non-binding estimated or interpolated times between timepoints. | -| `stop_id` | ID referencing `stops.stop_id` | **Required** | Identifies the serviced stop. All stops serviced during a trip must have a record in [stop_times.txt](#stop_timestxt). Referenced locations must be stops, not stations or station entrances. A stop may be serviced multiple times in the same trip, and multiple trips and routes may service the same stop. | +| `stop_id` | ID referencing `stops.stop_id` | **Required** | Identifies the serviced stop. All stops serviced during a trip must have a record in [stop_times.txt](#stop_timestxt). Referenced locations must be stops/platforms, i.e. their `stops.location_type` value must be `0` or empty. A stop may be serviced multiple times in the same trip, and multiple trips and routes may service the same stop. | | `stop_sequence` | Non-negative integer | **Required** | Order of stops for a particular trip. The values must increase along the trip but do not need to be consecutive.
*Example: The first location on the trip could have a `stop_sequence`=`1`, the second location on the trip could have a `stop_sequence`=`23`, the third location could have a `stop_sequence`=`40`, and so on.* | | `stop_headsign` | Text | Optional | Text that appears on signage identifying the trip's destination to riders. This field overrides the default `trips.trip_headsign` when the headsign changes between stops. If the headsign is displayed for an entire trip, use `trips.trip_headsign` instead.

A `stop_headsign` value specified for one `stop_time` does not apply to subsequent `stop_time`s in the same trip. If you want to override the `trip_headsign` for multiple `stop_time`s in the same trip, the `stop_headsign` value must be repeated in each `stop_time` row. | | `pickup_type` | Enum | Optional | Indicates pickup method. Valid options are:

`0` or empty - Regularly scheduled pickup.
`1` - No pickup available.
`2` - Must phone agency to arrange pickup.
`3` - Must coordinate with driver to arrange pickup. | From 729503b09263707a219d01f85e412ab8bcaaf73a Mon Sep 17 00:00:00 2001 From: scmcca Date: Mon, 1 Feb 2021 10:59:44 -0500 Subject: [PATCH 22/29] Clarification of GTFS Realtime occupancy descriptions (#259) --- gtfs-realtime/proto/gtfs-realtime.proto | 24 ++++++++----- gtfs-realtime/spec/en/reference.md | 48 +++++++++++++------------ 2 files changed, 41 insertions(+), 31 deletions(-) diff --git a/gtfs-realtime/proto/gtfs-realtime.proto b/gtfs-realtime/proto/gtfs-realtime.proto index 730c97b96..d6ce28e29 100644 --- a/gtfs-realtime/proto/gtfs-realtime.proto +++ b/gtfs-realtime/proto/gtfs-realtime.proto @@ -425,21 +425,27 @@ message VehiclePosition { } optional CongestionLevel congestion_level = 6; - // The degree of passenger occupancy of the vehicle or carriage. This field is still - // experimental, and subject to change. It may be formally adopted in the future. + // The state of passenger occupancy for the vehicle or carriage. + // Individual producers may not publish all OccupancyStatus values. Therefore, consumers + // must not assume that the OccupancyStatus values follow a linear scale. + // Consumers should represent OccupancyStatus values as the state indicated + // and intended by the producer. Likewise, producers must use OccupancyStatus values that + // correspond to actual vehicle occupancy states. + // For describing passenger occupancy levels on a linear scale, see `occupancy_percentage`. + // This field is still experimental, and subject to change. It may be formally adopted in the future. enum OccupancyStatus { // The vehicle or carriage is considered empty by most measures, and has few or no // passengers onboard, but is still accepting passengers. EMPTY = 0; - // The vehicle or carriage has a relatively large percentage of seats available. - // What percentage of free seats out of the total seats available is to be + // The vehicle or carriage has a large number of seats available. + // The amount of free seats out of the total seats available to be // considered large enough to fall into this category is determined at the // discretion of the producer. MANY_SEATS_AVAILABLE = 1; - // The vehicle or carriage has a relatively small percentage of seats available. - // What percentage of free seats out of the total seats available is to be + // The vehicle or carriage has a relatively small number of seats available. + // The amount of free seats out of the total seats available to be // considered small enough to fall into this category is determined at the // discretion of the feed producer. FEW_SEATS_AVAILABLE = 2; @@ -470,12 +476,12 @@ message VehiclePosition { // then this field should describe the entire vehicle with all carriages accepting passengers considered. optional OccupancyStatus occupancy_status = 9; - // A percentage value representing the degree of passenger occupancy of the vehicle. + // A percentage value indicating the degree of passenger occupancy in the vehicle. // The values are represented as an integer without decimals. 0 means 0% and 100 means 100%. // The value 100 should represent the total maximum occupancy the vehicle was designed for, // including both seated and standing capacity, and current operating regulations allow. - // It is possible that the value goes over 100 if there are currently more passengers than what the vehicle was designed for. - // The precision of occupancy_percentage should be low enough that you can't track a single person boarding and alighting for privacy reasons. + // The value may exceed 100 if there are more passengers than the maximum designed capacity. + // The precision of occupancy_percentage should be low enough that individual passengers cannot be tracked boarding or alighting the vehicle. // If multi_carriage_status is populated with per-carriage occupancy_percentage, // then this field should describe the entire vehicle with all carriages accepting passengers considered. // This field is still experimental, and subject to change. It may be formally adopted in the future. diff --git a/gtfs-realtime/spec/en/reference.md b/gtfs-realtime/spec/en/reference.md index a49a21211..19b136372 100644 --- a/gtfs-realtime/spec/en/reference.md +++ b/gtfs-realtime/spec/en/reference.md @@ -59,7 +59,7 @@ Fields labeled as **experimental** are subject to change and not yet formally ad * [VehicleStopStatus](#enum-vehiclestopstatus) * [CongestionLevel](#enum-congestionlevel) * [OccupancyStatus](#enum-occupancystatus) - * [CarriageDetails](#message-CarriageDetails) + * [CarriageDetails](#message-carriagedetails) * [Alert](#message-alert) * [TimeRange](#message-timerange) * [EntitySelector](#message-entityselector) @@ -151,8 +151,8 @@ Note that the update can describe a trip that has already completed.To this end, | **vehicle** | [VehicleDescriptor](#message-vehicledescriptor) | Optional | One | Additional information on the vehicle that is serving this trip. | | **stop_time_update** | [StopTimeUpdate](#message-stoptimeupdate) | Conditionally required | Many | Updates to StopTimes for the trip (both future, i.e., predictions, and in some cases, past ones, i.e., those that already happened). The updates must be sorted by stop_sequence, and apply for all the following stops of the trip up to the next specified stop_time_update. At least one stop_time_update must be provided for the trip unless the trip.schedule_relationship is CANCELED or DUPLICATED - if the trip is canceled, no stop_time_updates need to be provided. If the trip is duplicated, stop_time_updates may be provided to indicate real-time information for the new trip. | | **timestamp** | [uint64](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | Moment at which the vehicle's real-time progress was measured. In POSIX time (i.e., the number of seconds since January 1st 1970 00:00:00 UTC). | -| **delay** | [int32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | The current schedule deviation for the trip. Delay should only be specified when the prediction is given relative to some existing schedule in GTFS.
Delay (in seconds) can be positive (meaning that the vehicle is late) or negative (meaning that the vehicle is ahead of schedule). Delay of 0 means that the vehicle is exactly on time.
Delay information in StopTimeUpdates take precedent of trip-level delay information, such that trip-level delay is only propagated until the next stop along the trip with a StopTimeUpdate delay value specified.
Feed providers are strongly encouraged to provide a TripUpdate.timestamp value indicating when the delay value was last updated, in order to evaluate the freshness of the data.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.| -| **trip_properties** | [TripProperties](#message-tripproperties) | Optional | One | Provides the updated properties for the trip.
**Caution:** this message is still **experimental**, and subject to change. It may be formally adopted in the future. | +| **delay** | [int32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | The current schedule deviation for the trip. Delay should only be specified when the prediction is given relative to some existing schedule in GTFS.
Delay (in seconds) can be positive (meaning that the vehicle is late) or negative (meaning that the vehicle is ahead of schedule). Delay of 0 means that the vehicle is exactly on time.
Delay information in StopTimeUpdates take precedent of trip-level delay information, such that trip-level delay is only propagated until the next stop along the trip with a StopTimeUpdate delay value specified.
Feed providers are strongly encouraged to provide a TripUpdate.timestamp value indicating when the delay value was last updated, in order to evaluate the freshness of the data.

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.| +| **trip_properties** | [TripProperties](#message-tripproperties) | Optional | One | Provides the updated properties for the trip.

**Caution:** this message is still **experimental**, and subject to change. It may be formally adopted in the future. | ## _message_ StopTimeEvent @@ -187,7 +187,7 @@ The update is linked to a specific stop either through stop_sequence or stop_id, | **arrival** | [StopTimeEvent](#message-stoptimeevent) | Conditionally required | One | If schedule_relationship is empty or SCHEDULED, either arrival or departure must be provided within a StopTimeUpdate - both fields cannot be empty. arrival and departure may both be empty when schedule_relationship is SKIPPED. If schedule_relationship is NO_DATA, arrival and departure must be empty. | | **departure** | [StopTimeEvent](#message-stoptimeevent) | Conditionally required | One | If schedule_relationship is empty or SCHEDULED, either arrival or departure must be provided within a StopTimeUpdate - both fields cannot be empty. arrival and departure may both be empty when schedule_relationship is SKIPPED. If schedule_relationship is NO_DATA, arrival and departure must be empty. | | **schedule_relationship** | [ScheduleRelationship](#enum-schedulerelationship) | Optional | One | The default relationship is SCHEDULED. | -| **stop_time_properties** | [StopTimeProperties](#message-stoptimeproperties) | Optional | One | Realtime updates for certain properties defined within GTFS stop_times.txt
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.
. | +| **stop_time_properties** | [StopTimeProperties](#message-stoptimeproperties) | Optional | One | Realtime updates for certain properties defined within GTFS stop_times.txt

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | ## _enum_ ScheduleRelationship @@ -200,7 +200,7 @@ The relation between this StopTime and the static schedule. | **SCHEDULED** | The vehicle is proceeding in accordance with its static schedule of stops, although not necessarily according to the times of the schedule. This is the **default** behavior. At least one of arrival and departure must be provided. Frequency-based trips (GTFS frequencies.txt with exact_times = 0) should not have a SCHEDULED value and should use UNSCHEDULED instead. | | **SKIPPED** | The stop is skipped, i.e., the vehicle will not stop at this stop. Arrival and departure are optional. When set `SKIPPED` is not propagated to subsequent stops in the same trip (i.e., the vehicle will stop at subsequent stops in the trip unless those stops also have a `stop_time_update` with `schedule_relationship: SKIPPED`). Delay from a previous stop in the trip *does* propagate over the `SKIPPED` stop. In other words, if a `stop_time_update` with an `arrival` or `departure` prediction is not set for a stop after the `SKIPPED` stop, the prediction upstream of the `SKIPPED` stop will be propagated to the stop after the `SKIPPED` stop and subsequent stops in the trip until a `stop_time_update` for a subsequent stop is provided. | | **NO_DATA** | No data is given for this stop. It indicates that there is no realtime information available. When set NO_DATA is propagated through subsequent stops so this is the recommended way of specifying from which stop you do not have realtime information. When NO_DATA is set neither arrival nor departure should be supplied. | -| **UNSCHEDULED** | The vehicle is operating a frequency-based trip (GTFS frequencies.txt with exact_times = 0). This value should not be used for trips that are not defined in GTFS frequencies.txt, or trips in GTFS frequencies.txt with exact_times = 1. Trips containing `stop_time_updates` with `schedule_relationship: UNSCHEDULED` must also set the TripDescriptor `schedule_relationship: UNSCHEDULED`
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.
. +| **UNSCHEDULED** | The vehicle is operating a frequency-based trip (GTFS frequencies.txt with exact_times = 0). This value should not be used for trips that are not defined in GTFS frequencies.txt, or trips in GTFS frequencies.txt with exact_times = 1. Trips containing `stop_time_updates` with `schedule_relationship: UNSCHEDULED` must also set the TripDescriptor `schedule_relationship: UNSCHEDULED`

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. ## _message_ StopTimeProperties @@ -212,7 +212,7 @@ Realtime update for certain properties defined within GTFS stop_times.txt. | _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ | |------------------|------------|----------------|-------------------|-------------------| -| **assigned_stop_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | Supports real-time stop assignments. Refers to a `stop_id` defined in the GTFS `stops.txt`.
The new `assigned_stop_id` should not result in a significantly different trip experience for the end user than the `stop_id` defined in GTFS `stop_times.txt`. In other words, the end user should not view this new `stop_id` as an "unusual change" if the new stop was presented within an app without any additional context. For example, this field is intended to be used for platform assignments by using a `stop_id` that belongs to the same station as the stop originally defined in GTFS `stop_times.txt`.
To assign a stop without providing any real-time arrival or departure predictions, populate this field and set `StopTimeUpdate.schedule_relationship = NO_DATA`.
If this field is populated, `StopTimeUpdate.stop_sequence` must be populated and `StopTimeUpdate.stop_id` should not be populated. Stop assignments should be reflected in other GTFS-realtime fields as well (e.g., `VehiclePosition.stop_id`).
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.
. | +| **assigned_stop_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | Supports real-time stop assignments. Refers to a `stop_id` defined in the GTFS `stops.txt`.
The new `assigned_stop_id` should not result in a significantly different trip experience for the end user than the `stop_id` defined in GTFS `stop_times.txt`. In other words, the end user should not view this new `stop_id` as an "unusual change" if the new stop was presented within an app without any additional context. For example, this field is intended to be used for platform assignments by using a `stop_id` that belongs to the same station as the stop originally defined in GTFS `stop_times.txt`.
To assign a stop without providing any real-time arrival or departure predictions, populate this field and set `StopTimeUpdate.schedule_relationship = NO_DATA`.
If this field is populated, `StopTimeUpdate.stop_sequence` must be populated and `StopTimeUpdate.stop_id` should not be populated. Stop assignments should be reflected in other GTFS-realtime fields as well (e.g., `VehiclePosition.stop_id`).

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | ## _message_ TripProperties @@ -224,9 +224,9 @@ Defines updated properties of the trip | _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ | |------------------|------------|----------------|-------------------|-------------------| -| **trip_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Conditionally required | One | Defines the identifier of a new trip that is a duplicate of an existing trip defined in (CSV) GTFS trips.txt but will start at a different service date and/or time (defined using `TripProperties.start_date` and `TripProperties.start_time`). See definition of `trips.trip_id` in (CSV) GTFS. Its value must be different than the ones used in the (CSV) GTFS. This field is required if `schedule_relationship` is `DUPLICATED`, otherwise this field must not be populated and will be ignored by consumers.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | -| **start_date** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Conditionally required | One | Service date on which the duplicated trip will be run. Must be provided in YYYYMMDD format. This field is required if `schedule_relationship` is `DUPLICATED`, otherwise this field must not be populated and will be ignored by consumers.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | -| **start_time** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Conditionally required | One | Defines the departure start time of the trip when it’s duplicated. See definition of `stop_times.departure_time` in (CSV) GTFS. Scheduled arrival and departure times for the duplicated trip are calculated based on the offset between the original trip `departure_time` and this field. For example, if a GTFS trip has stop A with a `departure_time` of `10:00:00` and stop B with `departure_time` of `10:01:00`, and this field is populated with the value of `10:30:00`, stop B on the duplicated trip will have a scheduled `departure_time` of `10:31:00`. Real-time prediction `delay` values are applied to this calculated schedule time to determine the predicted time. For example, if a departure `delay` of `30` is provided for stop B, then the predicted departure time is `10:31:30`. Real-time prediction `time` values do not have any offset applied to them and indicate the predicted time as provided. For example, if a departure `time` representing 10:31:30 is provided for stop B, then the predicted departure time is `10:31:30`.This field is required if `schedule_relationship` is `DUPLICATED`, otherwise this field must not be populated and will be ignored by consumers.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | +| **trip_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Conditionally required | One | Defines the identifier of a new trip that is a duplicate of an existing trip defined in (CSV) GTFS trips.txt but will start at a different service date and/or time (defined using `TripProperties.start_date` and `TripProperties.start_time`). See definition of `trips.trip_id` in (CSV) GTFS. Its value must be different than the ones used in the (CSV) GTFS. This field is required if `schedule_relationship` is `DUPLICATED`, otherwise this field must not be populated and will be ignored by consumers.

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | +| **start_date** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Conditionally required | One | Service date on which the duplicated trip will be run. Must be provided in YYYYMMDD format. This field is required if `schedule_relationship` is `DUPLICATED`, otherwise this field must not be populated and will be ignored by consumers.

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | +| **start_time** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Conditionally required | One | Defines the departure start time of the trip when it’s duplicated. See definition of `stop_times.departure_time` in (CSV) GTFS. Scheduled arrival and departure times for the duplicated trip are calculated based on the offset between the original trip `departure_time` and this field. For example, if a GTFS trip has stop A with a `departure_time` of `10:00:00` and stop B with `departure_time` of `10:01:00`, and this field is populated with the value of `10:30:00`, stop B on the duplicated trip will have a scheduled `departure_time` of `10:31:00`. Real-time prediction `delay` values are applied to this calculated schedule time to determine the predicted time. For example, if a departure `delay` of `30` is provided for stop B, then the predicted departure time is `10:31:30`. Real-time prediction `time` values do not have any offset applied to them and indicate the predicted time as provided. For example, if a departure `time` representing 10:31:30 is provided for stop B, then the predicted departure time is `10:31:30`.This field is required if `schedule_relationship` is `DUPLICATED`, otherwise this field must not be populated and will be ignored by consumers.

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | ## _message_ VehiclePosition @@ -244,9 +244,9 @@ Realtime positioning information for a given vehicle. | **current_status** | [VehicleStopStatus](#enum-vehiclestopstatus) | Optional | One | The exact status of the vehicle with respect to the current stop. Ignored if current_stop_sequence is missing. | | **timestamp** | [uint64](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | Moment at which the vehicle's position was measured. In POSIX time (i.e., number of seconds since January 1st 1970 00:00:00 UTC). | | **congestion_level** | [CongestionLevel](#enum-congestionlevel) | Optional | One | -| **occupancy_status** | [OccupancyStatus](#enum-occupancystatus) | _Optional_ | One | The degree of passenger occupancy of the vehicle or carriage. If multi_carriage_details is populated with per-carriage OccupancyStatus, then this field should describe the entire vehicle with all carriages accepting passengers considered.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.| -| **occupancy_percentage** | [uint32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | A percentage value representing the degree of passenger occupancy of the vehicle. The value 100 should represent total the maximum occupancy the vehicle was designed for, including both seating and standing capacity, and current operating regulations allow. It's not impossible that the value goes over 100 if there are currently more passenger than the vehicle was designed for. The precision of occupancy_percentage should be low enough that you can't track a single person boarding and alighting for privacy reasons. If multi_carriage_details is populated with per-carriage occupancy_percentage, then this field should describe the entire vehicle with all carriages accepting passengers considered.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | -| **multi_carriage_details** | [CarriageDetails](#message-CarriageDetails) | Optional | Many | Details of the multiple carriages of this given vehicle. The first occurrence represents the first carriage of the vehicle, **given the current direction of travel**. The number of occurrences of the multi_carriage_details field represents the number of carriages of the vehicle. It also includes non boardable carriages, like engines, maintenance carriages, etc… as they provide valuable information to passengers about where to stand on a platform.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | +| **occupancy_status** | [OccupancyStatus](#enum-occupancystatus) | _Optional_ | One | The state of passenger occupancy for the vehicle or carriage. If multi_carriage_details is populated with per-carriage OccupancyStatus, then this field should describe the entire vehicle with all carriages accepting passengers considered.

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.| +| **occupancy_percentage** | [uint32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | A percentage value indicating the degree of passenger occupancy in the vehicle. The value 100 should represent the total maximum occupancy the vehicle was designed for, including both seating and standing capacity, and current operating regulations allow. The value may exceed 100 if there are more passengers than the maximum designed capacity. The precision of occupancy_percentage should be low enough that individual passengers cannot be tracked boarding or alighting the vehicle. If multi_carriage_details is populated with per-carriage occupancy_percentage, then this field should describe the entire vehicle with all carriages accepting passengers considered.

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | +| **multi_carriage_details** | [CarriageDetails](#message-CarriageDetails) | Optional | Many | Details of the multiple carriages of this given vehicle. The first occurrence represents the first carriage of the vehicle, **given the current direction of travel**. The number of occurrences of the multi_carriage_details field represents the number of carriages of the vehicle. It also includes non boardable carriages, like engines, maintenance carriages, etc… as they provide valuable information to passengers about where to stand on a platform.

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | ## _enum_ VehicleStopStatus @@ -275,7 +275,11 @@ Congestion level that is affecting this vehicle. ## _enum OccupancyStatus_ -The degree of passenger occupancy for the vehicle or carriage. +The state of passenger occupancy for the vehicle or carriage. + +Individual producers may not publish all OccupancyStatus values. Therefore, consumers must not assume that the OccupancyStatus values follow a linear scale. Consumers should represent OccupancyStatus values as the state indicated and intended by the producer. Likewise, producers must use OccupancyStatus values that correspond to actual vehicle occupancy states. + +For describing passenger occupancy levels on a linear scale, see `occupancy_percentage`. **Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. @@ -284,8 +288,8 @@ The degree of passenger occupancy for the vehicle or carriage. | _**Value**_ | _**Comment**_ | |-------------|---------------| | _**EMPTY**_ | _The vehicle is considered empty by most measures, and has few or no passengers onboard, but is still accepting passengers._ | -| _**MANY_SEATS_AVAILABLE**_ | _The vehicle or carriage has a large percentage of seats available. What percentage of free seats out of the total seats available is to be considered large enough to fall into this category is determined at the discretion of the producer._ | -| _**FEW_SEATS_AVAILABLE**_ | _The vehicle or carriage has a small percentage of seats available. What percentage of free seats out of the total seats available is to be considered small enough to fall into this category is determined at the discretion of the producer._ | +| _**MANY_SEATS_AVAILABLE**_ | _The vehicle or carriage has a large number of seats available. The amount of free seats out of the total seats available to be considered large enough to fall into this category is determined at the discretion of the producer._ | +| _**FEW_SEATS_AVAILABLE**_ | _The vehicle or carriage has a small number of seats available. The amount of free seats out of the total seats available to be considered small enough to fall into this category is determined at the discretion of the producer._ | | _**STANDING_ROOM_ONLY**_ | _The vehicle or carriage can currently accommodate only standing passengers._ | | _**CRUSHED_STANDING_ROOM_ONLY**_ | _The vehicle or carriage can currently accommodate only standing passengers and has limited space for them._ | | _**FULL**_ | _The vehicle is considered full by most measures, but may still be allowing passengers to board._ | @@ -296,7 +300,7 @@ The degree of passenger occupancy for the vehicle or carriage. ## _message_ CarriageDetails -Carriage specific details, used for vehicles composed of several carriages +Carriage specific details, used for vehicles composed of several carriages. **Caution:** this message is still **experimental**, and subject to change. It may be formally adopted in the future. @@ -304,11 +308,11 @@ Carriage specific details, used for vehicles composed of several carriages | _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ | |------------------|------------|----------------|-------------------|-------------------| -| **id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | Identification of the carriage. Should be unique per vehicle.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | +| **id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | Identification of the carriage. Should be unique per vehicle.

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | | **label** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | User visible label that may be shown to the passenger to help identify the carriage. Example: "7712", "Car ABC-32", etc...
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | -| **occupancy_status** | [OccupancyStatus](#enum-occupancystatus) | Optional | One | Occupancy status for this given carriage, in this vehicle. Default is set to `NO_DATA_AVAILABLE`.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.| -| **occupancy_percentage** | [int32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | Occupancy percentage for this given carriage, in this vehicle. Follows the same rules as "VehiclePosition.occupancy_percentage". Use -1 in case data is not available for this given carriage.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | -| **carriage_sequence** | [uint32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Required | One | Identifies the order of this carriage with respect to the other carriages in the vehicle's list of CarriageStatus. The first carriage in the direction of travel must have a value of 1. The second value corresponds to the second carriage in the direction of travel and must have a value of 2, and so forth. For example, the first carriage in the direction of travel has a value of 1. If the second carriage in the direction of travel has a value of 3, consumers will discard data for all carriages (i.e., the multi_carriage_details field). Carriages without data must be represented with a valid carriage_sequence number and the fields without data should be omitted (alternately, those fields could also be included and set to the "no data" values).
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | +| **occupancy_status** | [OccupancyStatus](#enum-occupancystatus) | Optional | One | Occupancy status for this given carriage, in this vehicle. Default is set to `NO_DATA_AVAILABLE`.

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.| +| **occupancy_percentage** | [int32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | Occupancy percentage for this given carriage, in this vehicle. Follows the same rules as "VehiclePosition.occupancy_percentage". Use -1 in case data is not available for this given carriage.

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | +| **carriage_sequence** | [uint32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Required | One | Identifies the order of this carriage with respect to the other carriages in the vehicle's list of CarriageStatus. The first carriage in the direction of travel must have a value of 1. The second value corresponds to the second carriage in the direction of travel and must have a value of 2, and so forth. For example, the first carriage in the direction of travel has a value of 1. If the second carriage in the direction of travel has a value of 3, consumers will discard data for all carriages (i.e., the multi_carriage_details field). Carriages without data must be represented with a valid carriage_sequence number and the fields without data should be omitted (alternately, those fields could also be included and set to the "no data" values).

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | ## _message_ Alert @@ -432,7 +436,7 @@ TripDescriptor.route_id cannot be used within an Alert EntitySelector to specify |------------------|------------|----------------|-------------------|-------------------| | **trip_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Conditionally required | One | The trip_id from the GTFS feed that this selector refers to. For non frequency-based trips (trips not defined in GTFS frequencies.txt), this field is enough to uniquely identify the trip. For frequency-based trips defined in GTFS frequencies.txt, trip_id, start_time, and start_date are all required. For scheduled-based trips (trips not defined in GTFS frequencies.txt), trip_id can only be omitted if the trip can be uniquely identified by a combination of route_id, direction_id, start_time, and start_date, and all those fields are provided. When schedule_relationship is DUPLICATED within a TripUpdate, the trip_id identifies the trip from static GTFS to be duplicated. When schedule_relationship is DUPLICATED within a VehiclePosition, the trip_id identifies the new duplicate trip and must contain the value for the corresponding TripUpdate.TripProperties.trip_id. | | **route_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Conditionally required | One | The route_id from the GTFS that this selector refers to. If trip_id is omitted, route_id, direction_id, start_time, and schedule_relationship=SCHEDULED must all be set to identify a trip instance. TripDescriptor.route_id should not be used within an Alert EntitySelector to specify a route-wide alert that affects all trips for a route - use EntitySelector.route_id instead. | -| **direction_id** | [uint32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Conditionally required | One | The direction_id from the GTFS feed trips.txt file, indicating the direction of travel for trips this selector refers to. If trip_id is omitted, direction_id must be provided.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.
| +| **direction_id** | [uint32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Conditionally required | One | The direction_id from the GTFS feed trips.txt file, indicating the direction of travel for trips this selector refers to. If trip_id is omitted, direction_id must be provided.

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.
| | **start_time** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Conditionally required | One | The initially scheduled start time of this trip instance. When the trip_id corresponds to a non-frequency-based trip, this field should either be omitted or be equal to the value in the GTFS feed. When the trip_id correponds to a frequency-based trip defined in GTFS frequencies.txt, start_time is required and must be specified for trip updates and vehicle positions. If the trip corresponds to exact_times=1 GTFS record, then start_time must be some multiple (including zero) of headway_secs later than frequencies.txt start_time for the corresponding time period. If the trip corresponds to exact_times=0, then its start_time may be arbitrary, and is initially expected to be the first departure of the trip. Once established, the start_time of this frequency-based exact_times=0 trip should be considered immutable, even if the first departure time changes -- that time change may instead be reflected in a StopTimeUpdate. If trip_id is omitted, start_time must be provided. Format and semantics of the field is same as that of GTFS/frequencies.txt/start_time, e.g., 11:15:35 or 25:15:35. | | **start_date** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Conditionally required | One | The start date of this trip instance in YYYYMMDD format. For scheduled trips (trips not defined in GTFS frequencies.txt), this field must be provided to disambiguate trips that are so late as to collide with a scheduled trip on a next day. For example, for a train that departs 8:00 and 20:00 every day, and is 12 hours late, there would be two distinct trips on the same time. This field can be provided but is not mandatory for schedules in which such collisions are impossible - for example, a service running on hourly schedule where a vehicle that is one hour late is not considered to be related to schedule anymore. This field is required for frequency-based trips defined in GTFS frequencies.txt. If trip_id is omitted, start_date must be provided. | | **schedule_relationship** | [ScheduleRelationship](#enum-schedulerelationship-1) | Optional | One | The relation between this trip and the static schedule. If TripDescriptor is provided in an Alert `EntitySelector`, the `schedule_relationship` field is ignored by consumers when identifying the matching trip instance. @@ -476,7 +480,7 @@ At least one specifier must be given - all fields in an EntitySelector cannot be | **agency_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Conditionally required | One | The agency_id from the GTFS feed that this selector refers to. | **route_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Conditionally required | One | The route_id from the GTFS that this selector refers to. If direction_id is provided, route_id must also be provided. | **route_type** | [int32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Conditionally required | One | The route_type from the GTFS that this selector refers to. -| **direction_id** | [uint32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Conditionally required | One | The direction_id from the GTFS feed trips.txt file, used to select all trips in one direction for a route, specified by route_id. If direction_id is provided, route_id must also be provided.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.
| +| **direction_id** | [uint32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Conditionally required | One | The direction_id from the GTFS feed trips.txt file, used to select all trips in one direction for a route, specified by route_id. If direction_id is provided, route_id must also be provided.

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.
| | **trip** | [TripDescriptor](#message-tripdescriptor) | Conditionally required | One | The trip instance from the GTFS that this selector refers to. This TripDescriptor must resolve to a single trip instance in the GTFS data (e.g., a producer cannot provide only a trip_id for exact_times=0 trips). If the ScheduleRelationship field is populated within this TripDescriptor it will be ignored by consumers when attempting to identify the GTFS trip. | **stop_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Conditionally required | One | The stop_id from the GTFS feed that this selector refers to. From 6e5663dba57a3b0bc1ab32e083ece80e1a404f27 Mon Sep 17 00:00:00 2001 From: scmcca Date: Wed, 3 Feb 2021 10:52:34 -0500 Subject: [PATCH 23/29] Add CrowdLevel --- gtfs-realtime/proto/gtfs-realtime.proto | 26 +++++++++++++++++++++++-- gtfs-realtime/spec/en/reference.md | 25 +++++++++++++++++++++--- 2 files changed, 46 insertions(+), 5 deletions(-) diff --git a/gtfs-realtime/proto/gtfs-realtime.proto b/gtfs-realtime/proto/gtfs-realtime.proto index d6ce28e29..ea11d17dc 100644 --- a/gtfs-realtime/proto/gtfs-realtime.proto +++ b/gtfs-realtime/proto/gtfs-realtime.proto @@ -476,6 +476,24 @@ message VehiclePosition { // then this field should describe the entire vehicle with all carriages accepting passengers considered. optional OccupancyStatus occupancy_status = 9; + // The passenger crowd level for the vehicle or carriage. + // This field is still experimental, and subject to change. It may be formally adopted in the future. + // If multi_carriage_details is populated with per-carriage CrowdLevel, + // then this field should describe the entire vehicle with all carriages accepting passengers considered. + enum CrowdLevel { + // The vehicle of carriage does not have any crowd level data available at that time. + NO_DATA_AVAILABLE = 0; + + // The vehicle or carriage is not considered crowded by most measures, having few or no passengers onboard. + NOT_CROWDED = 1; + + // The vehicle or carriage has some crowding by most measures, having some passengers onboard. + SOME_CROWDING = 2; + + // The vehicle or carriage is considered crowded by most measures, having many passengers onboard and limited space. + CROWDED = 3; + } + // A percentage value indicating the degree of passenger occupancy in the vehicle. // The values are represented as an integer without decimals. 0 means 0% and 100 means 100%. // The value 100 should represent the total maximum occupancy the vehicle was designed for, @@ -503,11 +521,15 @@ message VehiclePosition { // This message/field is still experimental, and subject to change. It may be formally adopted in the future. optional OccupancyStatus occupancy_status = 3 [default = NO_DATA_AVAILABLE]; + // The passenger crowd level for this given carriage, in this vehicle. + // This message/field is still experimental, and subject to change. It may be formally adopted in the future. + optional CrowdLevel crowd_level = 4 [default = NO_DATA_AVAILABLE]; + // Occupancy percentage for this given carriage, in this vehicle. // Follows the same rules as "VehiclePosition.occupancy_percentage" // -1 in case data is not available for this given carriage (as protobuf defaults to 0 otherwise) // This message/field is still experimental, and subject to change. It may be formally adopted in the future. - optional int32 occupancy_percentage = 4 [default = -1]; + optional int32 occupancy_percentage = 5 [default = -1]; // Identifies the order of this carriage with respect to the other // carriages in the vehicle's list of CarriageDetails. @@ -520,7 +542,7 @@ message VehiclePosition { // Carriages without data must be represented with a valid carriage_sequence number and the fields // without data should be omitted (alternately, those fields could also be included and set to the "no data" values). // This message/field is still experimental, and subject to change. It may be formally adopted in the future. - optional uint32 carriage_sequence = 5; + optional uint32 carriage_sequence = 6; // The extensions namespace allows 3rd-party developers to extend the // GTFS Realtime Specification in order to add and evaluate new features and diff --git a/gtfs-realtime/spec/en/reference.md b/gtfs-realtime/spec/en/reference.md index 19b136372..6ce0ddf2e 100644 --- a/gtfs-realtime/spec/en/reference.md +++ b/gtfs-realtime/spec/en/reference.md @@ -59,6 +59,7 @@ Fields labeled as **experimental** are subject to change and not yet formally ad * [VehicleStopStatus](#enum-vehiclestopstatus) * [CongestionLevel](#enum-congestionlevel) * [OccupancyStatus](#enum-occupancystatus) + * [CrowdLevel](#enum-crowdlevel) * [CarriageDetails](#message-carriagedetails) * [Alert](#message-alert) * [TimeRange](#message-timerange) @@ -244,7 +245,8 @@ Realtime positioning information for a given vehicle. | **current_status** | [VehicleStopStatus](#enum-vehiclestopstatus) | Optional | One | The exact status of the vehicle with respect to the current stop. Ignored if current_stop_sequence is missing. | | **timestamp** | [uint64](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | Moment at which the vehicle's position was measured. In POSIX time (i.e., number of seconds since January 1st 1970 00:00:00 UTC). | | **congestion_level** | [CongestionLevel](#enum-congestionlevel) | Optional | One | -| **occupancy_status** | [OccupancyStatus](#enum-occupancystatus) | _Optional_ | One | The state of passenger occupancy for the vehicle or carriage. If multi_carriage_details is populated with per-carriage OccupancyStatus, then this field should describe the entire vehicle with all carriages accepting passengers considered.

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.| +| **occupancy_status** | [OccupancyStatus](#enum-occupancystatus) | Optional | One | The state of passenger occupancy for the vehicle or carriage. If multi_carriage_details is populated with per-carriage OccupancyStatus, then this field should describe the entire vehicle with all carriages accepting passengers considered.

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.| +| **crowd_level** | [CrowdLevel](#enum-crowdlevel) | Optional | One | The passenger crowd level for the vehicle or carriage. If multi_carriage_details is populated with per-carriage CrowdLevel, then this field should describe the entire vehicle with all carriages accepting passengers considered.

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.| | **occupancy_percentage** | [uint32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | A percentage value indicating the degree of passenger occupancy in the vehicle. The value 100 should represent the total maximum occupancy the vehicle was designed for, including both seating and standing capacity, and current operating regulations allow. The value may exceed 100 if there are more passengers than the maximum designed capacity. The precision of occupancy_percentage should be low enough that individual passengers cannot be tracked boarding or alighting the vehicle. If multi_carriage_details is populated with per-carriage occupancy_percentage, then this field should describe the entire vehicle with all carriages accepting passengers considered.

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | | **multi_carriage_details** | [CarriageDetails](#message-CarriageDetails) | Optional | Many | Details of the multiple carriages of this given vehicle. The first occurrence represents the first carriage of the vehicle, **given the current direction of travel**. The number of occurrences of the multi_carriage_details field represents the number of carriages of the vehicle. It also includes non boardable carriages, like engines, maintenance carriages, etc… as they provide valuable information to passengers about where to stand on a platform.

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | @@ -273,13 +275,15 @@ Congestion level that is affecting this vehicle. | **CONGESTION** | | **SEVERE_CONGESTION** | -## _enum OccupancyStatus_ +## _enum_ OccupancyStatus The state of passenger occupancy for the vehicle or carriage. Individual producers may not publish all OccupancyStatus values. Therefore, consumers must not assume that the OccupancyStatus values follow a linear scale. Consumers should represent OccupancyStatus values as the state indicated and intended by the producer. Likewise, producers must use OccupancyStatus values that correspond to actual vehicle occupancy states. -For describing passenger occupancy levels on a linear scale, see `occupancy_percentage`. +To describe passenger crowd levels on an ordinal scale, see [CrowdLevel](#enum-crowdlevel). + +To describe passenger occupancy levels on a linear scale, see `occupancy_percentage`. **Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. @@ -297,6 +301,20 @@ For describing passenger occupancy levels on a linear scale, see `occupancy_perc | _**NO_DATA_AVAILABLE**_ | _The vehicle or carriage doesn't have any occupancy data available at that time._ | | _**NOT_BOARDABLE**_ | _The vehicle or carriage is not boardable and never accepts passengers. Useful for special vehicles or carriages (engine, maintenance carriage, etc…)._ | +## _enum_ CrowdLevel + +The passenger crowd level for the vehicle or carriage. CrowdLevel enum values must be interpreted on an ordinal scale in increasing order from _**NOT_CROWDED**_ to _**CROWDED**_. + +To describe the in-vehicle occupancy state, see [OccupancyStatus](#enum-occupancystatus). + +**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. + +| _**Value**_ | _**Comment**_ | +|-------------|---------------| +| _**NOT_CROWDED**_ | _The vehicle or carriage is not considered crowded by most measures, having few or no passengers onboard._ | +| _**SOME_CROWDING**_ | _The vehicle or carriage has some crowding by most measures, having some passengers onboard._ | +| _**CROWDED**_ | _The vehicle or carriage is considered crowded by most measures, having many passengers onboard and limited space._ | +| _**NO_DATA_AVAILABLE**_ | The vehicle of carriage does not have any crowd level data available at that time. | ## _message_ CarriageDetails @@ -311,6 +329,7 @@ Carriage specific details, used for vehicles composed of several carriages. | **id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | Identification of the carriage. Should be unique per vehicle.

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | | **label** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | User visible label that may be shown to the passenger to help identify the carriage. Example: "7712", "Car ABC-32", etc...
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | | **occupancy_status** | [OccupancyStatus](#enum-occupancystatus) | Optional | One | Occupancy status for this given carriage, in this vehicle. Default is set to `NO_DATA_AVAILABLE`.

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.| +| **crowd_level** | [CrowdLevel](#enum-crowdlevel) | Optional | One | The passenger crowd level for this given carriage, in this vehicle.

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | | **occupancy_percentage** | [int32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | Occupancy percentage for this given carriage, in this vehicle. Follows the same rules as "VehiclePosition.occupancy_percentage". Use -1 in case data is not available for this given carriage.

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | | **carriage_sequence** | [uint32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Required | One | Identifies the order of this carriage with respect to the other carriages in the vehicle's list of CarriageStatus. The first carriage in the direction of travel must have a value of 1. The second value corresponds to the second carriage in the direction of travel and must have a value of 2, and so forth. For example, the first carriage in the direction of travel has a value of 1. If the second carriage in the direction of travel has a value of 3, consumers will discard data for all carriages (i.e., the multi_carriage_details field). Carriages without data must be represented with a valid carriage_sequence number and the fields without data should be omitted (alternately, those fields could also be included and set to the "no data" values).

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | From a42933735151ca96cf2304ae464d833f6049b5b5 Mon Sep 17 00:00:00 2001 From: scmcca Date: Wed, 3 Feb 2021 10:55:41 -0500 Subject: [PATCH 24/29] style --- gtfs-realtime/spec/en/reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gtfs-realtime/spec/en/reference.md b/gtfs-realtime/spec/en/reference.md index 6ce0ddf2e..8cec75eec 100644 --- a/gtfs-realtime/spec/en/reference.md +++ b/gtfs-realtime/spec/en/reference.md @@ -314,7 +314,7 @@ To describe the in-vehicle occupancy state, see [OccupancyStatus](#enum-occupanc | _**NOT_CROWDED**_ | _The vehicle or carriage is not considered crowded by most measures, having few or no passengers onboard._ | | _**SOME_CROWDING**_ | _The vehicle or carriage has some crowding by most measures, having some passengers onboard._ | | _**CROWDED**_ | _The vehicle or carriage is considered crowded by most measures, having many passengers onboard and limited space._ | -| _**NO_DATA_AVAILABLE**_ | The vehicle of carriage does not have any crowd level data available at that time. | +| _**NO_DATA_AVAILABLE**_ | _The vehicle of carriage does not have any crowd level data available at that time._ | ## _message_ CarriageDetails From e96617fe799c907c869dc067a4f9efca6f6f7d0b Mon Sep 17 00:00:00 2001 From: scmcca Date: Thu, 4 Feb 2021 16:46:27 -0500 Subject: [PATCH 25/29] Updates from review - Reverted .proto field value assignments change - Clarified ordinal usage of CrowdLevel - Clarified CrowdLevel as subject to current allowed operating regulations (i.e., social distancing) - Examples for simultaneous use of OccupancyStatus and CrowdLevel - Corrected type --- gtfs-realtime/proto/gtfs-realtime.proto | 14 +++++++------- gtfs-realtime/spec/en/reference.md | 16 ++++++++++------ 2 files changed, 17 insertions(+), 13 deletions(-) diff --git a/gtfs-realtime/proto/gtfs-realtime.proto b/gtfs-realtime/proto/gtfs-realtime.proto index ea11d17dc..a22359518 100644 --- a/gtfs-realtime/proto/gtfs-realtime.proto +++ b/gtfs-realtime/proto/gtfs-realtime.proto @@ -481,7 +481,7 @@ message VehiclePosition { // If multi_carriage_details is populated with per-carriage CrowdLevel, // then this field should describe the entire vehicle with all carriages accepting passengers considered. enum CrowdLevel { - // The vehicle of carriage does not have any crowd level data available at that time. + // The vehicle or carriage does not have any crowd level data available at that time. NO_DATA_AVAILABLE = 0; // The vehicle or carriage is not considered crowded by most measures, having few or no passengers onboard. @@ -521,15 +521,11 @@ message VehiclePosition { // This message/field is still experimental, and subject to change. It may be formally adopted in the future. optional OccupancyStatus occupancy_status = 3 [default = NO_DATA_AVAILABLE]; - // The passenger crowd level for this given carriage, in this vehicle. - // This message/field is still experimental, and subject to change. It may be formally adopted in the future. - optional CrowdLevel crowd_level = 4 [default = NO_DATA_AVAILABLE]; - // Occupancy percentage for this given carriage, in this vehicle. // Follows the same rules as "VehiclePosition.occupancy_percentage" // -1 in case data is not available for this given carriage (as protobuf defaults to 0 otherwise) // This message/field is still experimental, and subject to change. It may be formally adopted in the future. - optional int32 occupancy_percentage = 5 [default = -1]; + optional int32 occupancy_percentage = 4 [default = -1]; // Identifies the order of this carriage with respect to the other // carriages in the vehicle's list of CarriageDetails. @@ -542,7 +538,11 @@ message VehiclePosition { // Carriages without data must be represented with a valid carriage_sequence number and the fields // without data should be omitted (alternately, those fields could also be included and set to the "no data" values). // This message/field is still experimental, and subject to change. It may be formally adopted in the future. - optional uint32 carriage_sequence = 6; + optional uint32 carriage_sequence = 5; + + // The passenger crowd level for this given carriage, in this vehicle. + // This message/field is still experimental, and subject to change. It may be formally adopted in the future. + optional CrowdLevel crowd_level = 6 [default = NO_DATA_AVAILABLE]; // The extensions namespace allows 3rd-party developers to extend the // GTFS Realtime Specification in order to add and evaluate new features and diff --git a/gtfs-realtime/spec/en/reference.md b/gtfs-realtime/spec/en/reference.md index 8cec75eec..d1ab20f22 100644 --- a/gtfs-realtime/spec/en/reference.md +++ b/gtfs-realtime/spec/en/reference.md @@ -283,6 +283,8 @@ Individual producers may not publish all OccupancyStatus values. Therefore, cons To describe passenger crowd levels on an ordinal scale, see [CrowdLevel](#enum-crowdlevel). +Both OccupancyStatus and CrowdLevel may be used side-by-side, but must respectively indicate true conditions. For example, a vehicle may have _**FEW_SEATS_AVAILABLE**_ and _**SOME_CROWDING**_, have _**STANDING_ROOM_ONLY**_ and be _**CROWDED**_, or is _**NOT_ACCEPTING_PASSENGERS**_ and is _**CROWDED**_. + To describe passenger occupancy levels on a linear scale, see `occupancy_percentage`. **Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. @@ -303,18 +305,20 @@ To describe passenger occupancy levels on a linear scale, see `occupancy_percent ## _enum_ CrowdLevel -The passenger crowd level for the vehicle or carriage. CrowdLevel enum values must be interpreted on an ordinal scale in increasing order from _**NOT_CROWDED**_ to _**CROWDED**_. +The passenger crowd level for the vehicle or carriage. CrowdLevel enum values must be interpreted on an ordinal scale in increasing order from _**NOT_CROWDED**_ to _**CROWDED**_. In other words, producers must represent the lowest crowdedness level with _**NOT_CROWDED**_, the medium crowdedness level with _**SOME_CROWDING**_, and the highest crowdedness level with _**CROWDED**_. + +To describe in-vehicle occupancy states, see [OccupancyStatus](#enum-occupancystatus). -To describe the in-vehicle occupancy state, see [OccupancyStatus](#enum-occupancystatus). +Both OccupancyStatus and CrowdLevel may be used side-by-side, but must respectively indicate true conditions. For example, a vehicle may have _**FEW_SEATS_AVAILABLE**_ and _**SOME_CROWDING**_, have _**STANDING_ROOM_ONLY**_ and be _**CROWDED**_, or is _**NOT_ACCEPTING_PASSENGERS**_ and is _**CROWDED**_. **Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | _**Value**_ | _**Comment**_ | |-------------|---------------| -| _**NOT_CROWDED**_ | _The vehicle or carriage is not considered crowded by most measures, having few or no passengers onboard._ | -| _**SOME_CROWDING**_ | _The vehicle or carriage has some crowding by most measures, having some passengers onboard._ | -| _**CROWDED**_ | _The vehicle or carriage is considered crowded by most measures, having many passengers onboard and limited space._ | -| _**NO_DATA_AVAILABLE**_ | _The vehicle of carriage does not have any crowd level data available at that time._ | +| _**NOT_CROWDED**_ | _The vehicle or carriage is not considered crowded by most measures, having few or no passengers onboard, or as otherwise defined by current operating regulations._ | +| _**SOME_CROWDING**_ | _The vehicle or carriage has some crowding by most measures, having some passengers onboard, or as otherwise defined by current operating regulations._ | +| _**CROWDED**_ | _The vehicle or carriage is considered crowded by most measures, having many passengers onboard and limited space, or as otherwise defined be current operating regulations._ | +| _**NO_DATA_AVAILABLE**_ | _The vehicle or carriage does not have any crowd level data available at that time._ | ## _message_ CarriageDetails From f612ddc73d3e8e0c7363551812a032b539ccb141 Mon Sep 17 00:00:00 2001 From: scmcca Date: Tue, 9 Feb 2021 09:44:10 -0500 Subject: [PATCH 26/29] Fix value of CrowdLevel in VehiclePosition Move to backward-compatible value --- gtfs-realtime/proto/gtfs-realtime.proto | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/gtfs-realtime/proto/gtfs-realtime.proto b/gtfs-realtime/proto/gtfs-realtime.proto index a22359518..bda4a4742 100644 --- a/gtfs-realtime/proto/gtfs-realtime.proto +++ b/gtfs-realtime/proto/gtfs-realtime.proto @@ -476,6 +476,17 @@ message VehiclePosition { // then this field should describe the entire vehicle with all carriages accepting passengers considered. optional OccupancyStatus occupancy_status = 9; + // A percentage value indicating the degree of passenger occupancy in the vehicle. + // The values are represented as an integer without decimals. 0 means 0% and 100 means 100%. + // The value 100 should represent the total maximum occupancy the vehicle was designed for, + // including both seated and standing capacity, and current operating regulations allow. + // The value may exceed 100 if there are more passengers than the maximum designed capacity. + // The precision of occupancy_percentage should be low enough that individual passengers cannot be tracked boarding or alighting the vehicle. + // If multi_carriage_status is populated with per-carriage occupancy_percentage, + // then this field should describe the entire vehicle with all carriages accepting passengers considered. + // This field is still experimental, and subject to change. It may be formally adopted in the future. + optional uint32 occupancy_percentage = 10; + // The passenger crowd level for the vehicle or carriage. // This field is still experimental, and subject to change. It may be formally adopted in the future. // If multi_carriage_details is populated with per-carriage CrowdLevel, @@ -493,17 +504,7 @@ message VehiclePosition { // The vehicle or carriage is considered crowded by most measures, having many passengers onboard and limited space. CROWDED = 3; } - - // A percentage value indicating the degree of passenger occupancy in the vehicle. - // The values are represented as an integer without decimals. 0 means 0% and 100 means 100%. - // The value 100 should represent the total maximum occupancy the vehicle was designed for, - // including both seated and standing capacity, and current operating regulations allow. - // The value may exceed 100 if there are more passengers than the maximum designed capacity. - // The precision of occupancy_percentage should be low enough that individual passengers cannot be tracked boarding or alighting the vehicle. - // If multi_carriage_status is populated with per-carriage occupancy_percentage, - // then this field should describe the entire vehicle with all carriages accepting passengers considered. - // This field is still experimental, and subject to change. It may be formally adopted in the future. - optional uint32 occupancy_percentage = 10; + optional CrowdLevel crowd_level = 11; // Carriage specific details, used for vehicles composed of several carriages // This message/field is still experimental, and subject to change. It may be formally adopted in the future. From 94f849e7e3f3cdc5b6e8208fa0de3f178f57e6c7 Mon Sep 17 00:00:00 2001 From: scmcca Date: Wed, 10 Feb 2021 19:01:06 -0500 Subject: [PATCH 27/29] Fix NO_DATA value --- gtfs-realtime/proto/gtfs-realtime.proto | 4 ++-- gtfs-realtime/spec/en/reference.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/gtfs-realtime/proto/gtfs-realtime.proto b/gtfs-realtime/proto/gtfs-realtime.proto index bda4a4742..c265919e3 100644 --- a/gtfs-realtime/proto/gtfs-realtime.proto +++ b/gtfs-realtime/proto/gtfs-realtime.proto @@ -493,7 +493,7 @@ message VehiclePosition { // then this field should describe the entire vehicle with all carriages accepting passengers considered. enum CrowdLevel { // The vehicle or carriage does not have any crowd level data available at that time. - NO_DATA_AVAILABLE = 0; + NO_DATA = 0; // The vehicle or carriage is not considered crowded by most measures, having few or no passengers onboard. NOT_CROWDED = 1; @@ -543,7 +543,7 @@ message VehiclePosition { // The passenger crowd level for this given carriage, in this vehicle. // This message/field is still experimental, and subject to change. It may be formally adopted in the future. - optional CrowdLevel crowd_level = 6 [default = NO_DATA_AVAILABLE]; + optional CrowdLevel crowd_level = 6 [default = NO_DATA]; // The extensions namespace allows 3rd-party developers to extend the // GTFS Realtime Specification in order to add and evaluate new features and diff --git a/gtfs-realtime/spec/en/reference.md b/gtfs-realtime/spec/en/reference.md index d1ab20f22..aaf0910d3 100644 --- a/gtfs-realtime/spec/en/reference.md +++ b/gtfs-realtime/spec/en/reference.md @@ -318,7 +318,7 @@ Both OccupancyStatus and CrowdLevel may be used side-by-side, but must respectiv | _**NOT_CROWDED**_ | _The vehicle or carriage is not considered crowded by most measures, having few or no passengers onboard, or as otherwise defined by current operating regulations._ | | _**SOME_CROWDING**_ | _The vehicle or carriage has some crowding by most measures, having some passengers onboard, or as otherwise defined by current operating regulations._ | | _**CROWDED**_ | _The vehicle or carriage is considered crowded by most measures, having many passengers onboard and limited space, or as otherwise defined be current operating regulations._ | -| _**NO_DATA_AVAILABLE**_ | _The vehicle or carriage does not have any crowd level data available at that time._ | +| _**NO_DATA**_ | _The vehicle or carriage does not have any crowd level data available at that time._ | ## _message_ CarriageDetails From c79bf379221779586b8226bb2f35fbf3cade929f Mon Sep 17 00:00:00 2001 From: scmcca Date: Thu, 11 Feb 2021 10:13:22 -0500 Subject: [PATCH 28/29] Fix field number --- gtfs-realtime/proto/gtfs-realtime.proto | 38 ++++++++++++------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/gtfs-realtime/proto/gtfs-realtime.proto b/gtfs-realtime/proto/gtfs-realtime.proto index c265919e3..5f18ad649 100644 --- a/gtfs-realtime/proto/gtfs-realtime.proto +++ b/gtfs-realtime/proto/gtfs-realtime.proto @@ -486,25 +486,6 @@ message VehiclePosition { // then this field should describe the entire vehicle with all carriages accepting passengers considered. // This field is still experimental, and subject to change. It may be formally adopted in the future. optional uint32 occupancy_percentage = 10; - - // The passenger crowd level for the vehicle or carriage. - // This field is still experimental, and subject to change. It may be formally adopted in the future. - // If multi_carriage_details is populated with per-carriage CrowdLevel, - // then this field should describe the entire vehicle with all carriages accepting passengers considered. - enum CrowdLevel { - // The vehicle or carriage does not have any crowd level data available at that time. - NO_DATA = 0; - - // The vehicle or carriage is not considered crowded by most measures, having few or no passengers onboard. - NOT_CROWDED = 1; - - // The vehicle or carriage has some crowding by most measures, having some passengers onboard. - SOME_CROWDING = 2; - - // The vehicle or carriage is considered crowded by most measures, having many passengers onboard and limited space. - CROWDED = 3; - } - optional CrowdLevel crowd_level = 11; // Carriage specific details, used for vehicles composed of several carriages // This message/field is still experimental, and subject to change. It may be formally adopted in the future. @@ -565,6 +546,25 @@ message VehiclePosition { // This message/field is still experimental, and subject to change. It may be formally adopted in the future. repeated CarriageDetails multi_carriage_details = 11; + // The passenger crowd level for the vehicle or carriage. + // This field is still experimental, and subject to change. It may be formally adopted in the future. + // If multi_carriage_details is populated with per-carriage CrowdLevel, + // then this field should describe the entire vehicle with all carriages accepting passengers considered. + enum CrowdLevel { + // The vehicle or carriage does not have any crowd level data available at that time. + NO_DATA = 0; + + // The vehicle or carriage is not considered crowded by most measures, having few or no passengers onboard. + NOT_CROWDED = 1; + + // The vehicle or carriage has some crowding by most measures, having some passengers onboard. + SOME_CROWDING = 2; + + // The vehicle or carriage is considered crowded by most measures, having many passengers onboard and limited space. + CROWDED = 3; + } + optional CrowdLevel crowd_level = 12; + // 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. From 802b6771463cf1d6726de0a5982126568a3d9849 Mon Sep 17 00:00:00 2001 From: scmcca Date: Thu, 11 Feb 2021 11:43:06 -0500 Subject: [PATCH 29/29] review - Added missing default value - Style and grammar --- gtfs-realtime/proto/gtfs-realtime.proto | 6 ++--- gtfs-realtime/spec/en/reference.md | 32 ++++++++++++------------- 2 files changed, 19 insertions(+), 19 deletions(-) diff --git a/gtfs-realtime/proto/gtfs-realtime.proto b/gtfs-realtime/proto/gtfs-realtime.proto index 5f18ad649..5d7a0cb2b 100644 --- a/gtfs-realtime/proto/gtfs-realtime.proto +++ b/gtfs-realtime/proto/gtfs-realtime.proto @@ -464,7 +464,7 @@ message VehiclePosition { // The vehicle or carriage is not accepting passengers, but usually accepts passengers for boarding. NOT_ACCEPTING_PASSENGERS = 6; - // The vehicle or carriage doesn't have any occupancy data available at that time. + // The vehicle or carriage does not have any occupancy data available at this time. NO_DATA_AVAILABLE = 7; // The vehicle or carriage is not boardable and never accepts passengers. @@ -551,7 +551,7 @@ message VehiclePosition { // If multi_carriage_details is populated with per-carriage CrowdLevel, // then this field should describe the entire vehicle with all carriages accepting passengers considered. enum CrowdLevel { - // The vehicle or carriage does not have any crowd level data available at that time. + // The vehicle or carriage does not have any crowd level data available at this time. NO_DATA = 0; // The vehicle or carriage is not considered crowded by most measures, having few or no passengers onboard. @@ -563,7 +563,7 @@ message VehiclePosition { // The vehicle or carriage is considered crowded by most measures, having many passengers onboard and limited space. CROWDED = 3; } - optional CrowdLevel crowd_level = 12; + optional CrowdLevel crowd_level = 12 [default = NO_DATA]; // The extensions namespace allows 3rd-party developers to extend the // GTFS Realtime Specification in order to add and evaluate new features and diff --git a/gtfs-realtime/spec/en/reference.md b/gtfs-realtime/spec/en/reference.md index aaf0910d3..8be7683bd 100644 --- a/gtfs-realtime/spec/en/reference.md +++ b/gtfs-realtime/spec/en/reference.md @@ -283,7 +283,7 @@ Individual producers may not publish all OccupancyStatus values. Therefore, cons To describe passenger crowd levels on an ordinal scale, see [CrowdLevel](#enum-crowdlevel). -Both OccupancyStatus and CrowdLevel may be used side-by-side, but must respectively indicate true conditions. For example, a vehicle may have _**FEW_SEATS_AVAILABLE**_ and _**SOME_CROWDING**_, have _**STANDING_ROOM_ONLY**_ and be _**CROWDED**_, or is _**NOT_ACCEPTING_PASSENGERS**_ and is _**CROWDED**_. +Both OccupancyStatus and CrowdLevel may be used side-by-side, but must respectively indicate true conditions. For example, a vehicle may have **FEW_SEATS_AVAILABLE** and **SOME_CROWDING**, have **STANDING_ROOM_ONLY** and be **CROWDED**, or is **NOT_ACCEPTING_PASSENGERS** and is **CROWDED**. To describe passenger occupancy levels on a linear scale, see `occupancy_percentage`. @@ -293,32 +293,32 @@ To describe passenger occupancy levels on a linear scale, see `occupancy_percent | _**Value**_ | _**Comment**_ | |-------------|---------------| -| _**EMPTY**_ | _The vehicle is considered empty by most measures, and has few or no passengers onboard, but is still accepting passengers._ | -| _**MANY_SEATS_AVAILABLE**_ | _The vehicle or carriage has a large number of seats available. The amount of free seats out of the total seats available to be considered large enough to fall into this category is determined at the discretion of the producer._ | -| _**FEW_SEATS_AVAILABLE**_ | _The vehicle or carriage has a small number of seats available. The amount of free seats out of the total seats available to be considered small enough to fall into this category is determined at the discretion of the producer._ | -| _**STANDING_ROOM_ONLY**_ | _The vehicle or carriage can currently accommodate only standing passengers._ | -| _**CRUSHED_STANDING_ROOM_ONLY**_ | _The vehicle or carriage can currently accommodate only standing passengers and has limited space for them._ | -| _**FULL**_ | _The vehicle is considered full by most measures, but may still be allowing passengers to board._ | -| _**NOT_ACCEPTING_PASSENGERS**_ | _The vehicle or carriage is not accepting passengers. The vehicle or carriage usually accepts passengers for boarding._ | -| _**NO_DATA_AVAILABLE**_ | _The vehicle or carriage doesn't have any occupancy data available at that time._ | -| _**NOT_BOARDABLE**_ | _The vehicle or carriage is not boardable and never accepts passengers. Useful for special vehicles or carriages (engine, maintenance carriage, etc…)._ | +| **EMPTY** | The vehicle is considered empty by most measures, and has few or no passengers onboard, but is still accepting passengers. | +| **MANY_SEATS_AVAILABLE** | The vehicle or carriage has a large number of seats available. The amount of free seats out of the total seats available to be considered large enough to fall into this category is determined at the discretion of the producer. | +| **FEW_SEATS_AVAILABLE** | The vehicle or carriage has a small number of seats available. The amount of free seats out of the total seats available to be considered small enough to fall into this category is determined at the discretion of the producer. | +| **STANDING_ROOM_ONLY** | The vehicle or carriage can currently accommodate only standing passengers. | +| **CRUSHED_STANDING_ROOM_ONLY** | The vehicle or carriage can currently accommodate only standing passengers and has limited space for them. | +| **FULL**_ | The vehicle is considered full by most measures, but may still be allowing passengers to board. | +| **NOT_ACCEPTING_PASSENGERS** | The vehicle or carriage is not accepting passengers. The vehicle or carriage usually accepts passengers for boarding. | +| **NO_DATA_AVAILABLE** | The vehicle or carriage does not have any occupancy data available at this time. | +| **NOT_BOARDABLE** | The vehicle or carriage is not boardable and never accepts passengers. Useful for special vehicles or carriages (engine, maintenance carriage, etc…). | ## _enum_ CrowdLevel -The passenger crowd level for the vehicle or carriage. CrowdLevel enum values must be interpreted on an ordinal scale in increasing order from _**NOT_CROWDED**_ to _**CROWDED**_. In other words, producers must represent the lowest crowdedness level with _**NOT_CROWDED**_, the medium crowdedness level with _**SOME_CROWDING**_, and the highest crowdedness level with _**CROWDED**_. +The passenger crowd level for the vehicle or carriage. CrowdLevel enum values must be interpreted on an ordinal scale in increasing order from **NOT_CROWDED** to **CROWDED**. In other words, producers must represent the lowest crowdedness level with **NOT_CROWDED**, the medium crowdedness level with **SOME_CROWDING**, and the highest crowdedness level with **CROWDED**. To describe in-vehicle occupancy states, see [OccupancyStatus](#enum-occupancystatus). -Both OccupancyStatus and CrowdLevel may be used side-by-side, but must respectively indicate true conditions. For example, a vehicle may have _**FEW_SEATS_AVAILABLE**_ and _**SOME_CROWDING**_, have _**STANDING_ROOM_ONLY**_ and be _**CROWDED**_, or is _**NOT_ACCEPTING_PASSENGERS**_ and is _**CROWDED**_. +Both OccupancyStatus and CrowdLevel may be used side-by-side, but must respectively indicate true conditions. For example, a vehicle may have **FEW_SEATS_AVAILABLE** and **SOME_CROWDING**, have **STANDING_ROOM_ONLY** and be **CROWDED**, or is **NOT_ACCEPTING_PASSENGERS** and is **CROWDED**. **Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | _**Value**_ | _**Comment**_ | |-------------|---------------| -| _**NOT_CROWDED**_ | _The vehicle or carriage is not considered crowded by most measures, having few or no passengers onboard, or as otherwise defined by current operating regulations._ | -| _**SOME_CROWDING**_ | _The vehicle or carriage has some crowding by most measures, having some passengers onboard, or as otherwise defined by current operating regulations._ | -| _**CROWDED**_ | _The vehicle or carriage is considered crowded by most measures, having many passengers onboard and limited space, or as otherwise defined be current operating regulations._ | -| _**NO_DATA**_ | _The vehicle or carriage does not have any crowd level data available at that time._ | +| **NOT_CROWDED** | The vehicle or carriage is not considered crowded by most measures, having few or no passengers onboard, or as otherwise defined by current operating regulations. | +| **SOME_CROWDING** | The vehicle or carriage has some crowding by most measures, having some passengers onboard, or as otherwise defined by current operating regulations. | +| **CROWDED** | The vehicle or carriage is considered crowded by most measures, having many passengers onboard and limited space, or as otherwise defined be current operating regulations. | +| **NO_DATA** | The vehicle or carriage does not have any crowd level data available at this time. | ## _message_ CarriageDetails