From 8d8fdfc2b542c9c89fc32440e93a9f16a4852b83 Mon Sep 17 00:00:00 2001 From: Eric Ouyang Date: Mon, 22 Mar 2021 17:54:56 -0700 Subject: [PATCH 1/7] Add Shapes to GTFS-RT --- gtfs-realtime/proto/gtfs-realtime.proto | 66 ++++++++++++++++++++++++- gtfs-realtime/spec/en/reference.md | 40 +++++++++++++-- 2 files changed, 101 insertions(+), 5 deletions(-) diff --git a/gtfs-realtime/proto/gtfs-realtime.proto b/gtfs-realtime/proto/gtfs-realtime.proto index d6ce28e29..78ea7775e 100644 --- a/gtfs-realtime/proto/gtfs-realtime.proto +++ b/gtfs-realtime/proto/gtfs-realtime.proto @@ -103,6 +103,7 @@ message FeedEntity { optional TripUpdate trip_update = 3; optional VehiclePosition vehicle = 4; optional Alert alert = 5; + optional Shape shape = 6; // The extensions namespace allows 3rd-party developers to extend the // GTFS Realtime Specification in order to add and evaluate new features and @@ -327,7 +328,8 @@ message TripUpdate { // formally adopted in the future. optional int32 delay = 5; - // Defines updated properties of the trip + // Defines updated properties of the trip, such as a new shape_id when there is a detour. Or defines the + // trip_id, start_date, and start_time of a DUPLICATED 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 @@ -354,6 +356,13 @@ 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; + // Specifies the new shape of the vehicle travel path when the trip shape differs from the shape specified in + // (CSV) GTFS. See definition of trips.shape_id in (CSV) GTFS. This can refer to a shape defined in the + // (CSV) GTFS in shapes.txt or a Shape the (protobuf) real-time feed. The order of stops (stop sequences) for this + // trip must remain the same as (CSV) GTFS. Stops that are a part of the original trip but will no longer be made, + // such as when a detour occurs, should be marked as schedule_relationship=SKIPPED. + // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future. + optional string shape_id = 4; // The extensions namespace allows 3rd-party developers to extend the // GTFS Realtime Specification in order to add and evaluate new features @@ -883,3 +892,58 @@ message TranslatedString { // The following extension IDs are reserved for private use by any organization. extensions 9000 to 9999; } + + +// Describes the physical path that a vehicle takes when it's not part of the (CSV) GTFS, +// such as for a detour. Shapes belong to Trips, and consist of a sequence of shape points. +// Tracing the points in order provides the path of the vehicle. Shapes do not need to intercept +// the location of Stops exactly, but all Stops on a trip should lie within a small distance of +// the shape for that trip, i.e. close to straight line segments connecting the shape points +// NOTE: This message is still experimental, and subject to change. It may be formally adopted in the future. +message Shape { + // Identifier of the shape. Must be different than any shape_id defined in the (CSV) GTFS. + // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future. + required string shape_id = 1; + + // Points in the shape. A shape must contain at least two shape points. ShapePoints must be ordered by shape_pt_sequence. + // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future. + repeated ShapePoint shape_point = 2; + + // 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; +} + +// A shape for a trip that has been updated. +// NOTE: This message is still experimental, and subject to change. It may be formally adopted in the future. +message ShapePoint { + // Latitude of a shape point. See definition of shapes.shape_pt_lat in (CSV) GTFS. + // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future. + required float shape_pt_lat = 1; + + // Longitude of a shape point. See definition of shapes.shape_pt_lon in (CSV) GTFS. + // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future. + required float shape_pt_lon = 2; + + // Actual distance traveled along the shape from the first shape point to the point specified in this record. + // See definition of shapes.shape_dist_traveled in (CSV) GTFS. + // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future. + optional float shape_dist_traveled = 3; + + // Sequence in which the shape points connect to form the shape. Values must increase along the trip but do not need to be consecutive. + // See definition of shapes.shape_pt_sequence in (CSV) GTFS. + // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future. + required uint32 shape_pt_sequence = 4; + + // The extensions namespace allows 3rd-party developers to extend the + // GTFS Realtime Specification in order to add and evaluate new features and + // modifications to the spec. + extensions 1000 to 1999; + + // The following extension IDs are reserved for private use by any organization. + extensions 9000 to 9999; +} diff --git a/gtfs-realtime/spec/en/reference.md b/gtfs-realtime/spec/en/reference.md index 19b136372..5dab22930 100644 --- a/gtfs-realtime/spec/en/reference.md +++ b/gtfs-realtime/spec/en/reference.md @@ -112,7 +112,7 @@ Determines whether the current fetch is incremental. ## _message_ FeedEntity -A definition (or update) of an entity in the transit feed. If the entity is not being deleted, exactly one of 'trip_update', 'vehicle' and 'alert' fields should be populated. +A definition (or update) of an entity in the transit feed. If the entity is not being deleted, exactly one of 'trip_update', 'vehicle', 'alert' and 'shape' fields should be populated. #### Fields @@ -120,9 +120,11 @@ A definition (or update) of an entity in the transit feed. If the entity is not |------------------|------------|----------------|-------------------|-------------------| | **id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Required | One | Feed-unique identifier for this entity. The ids are used only to provide incrementality support. The actual entities referenced by the feed must be specified by explicit selectors (see EntitySelector below for more info). | | **is_deleted** | [bool](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | Whether this entity is to be deleted. Should be provided only for feeds with Incrementality of DIFFERENTIAL - this field should NOT be provided for feeds with Incrementality of FULL_DATASET. | -| **trip_update** | [TripUpdate](#message-tripupdate) | Conditionally required | One | Data about the realtime departure delays of a trip. At least one of the fields trip_update, vehicle, or alert must be provided - all these fields cannot be empty. | -| **vehicle** | [VehiclePosition](#message-vehicleposition) | Conditionally required | One | Data about the realtime position of a vehicle. At least one of the fields trip_update, vehicle, or alert must be provided - all these fields cannot be empty. | -| **alert** | [Alert](#message-alert) | Conditionally required | One | Data about the realtime alert. At least one of the fields trip_update, vehicle, or alert must be provided - all these fields cannot be empty. | +| **trip_update** | [TripUpdate](#message-tripupdate) | Conditionally required | One | Data about the realtime departure delays of a trip. At least one of the fields trip_update, vehicle, alert, or shape must be provided - all these fields cannot be empty. | +| **vehicle** | [VehiclePosition](#message-vehicleposition) | Conditionally required | One | Data about the realtime position of a vehicle. At least one of the fields trip_update, vehicle, alert, or shape must be provided - all these fields cannot be empty. | +| **alert** | [Alert](#message-alert) | Conditionally required | One | Data about the realtime alert. At least one of the fields trip_update, vehicle, alert, or shape must be provided - all these fields cannot be empty. | +| **shape** | [Shape](#message-shape) | Conditionally required | One | Data about the realtime added shapes, such as for a detour. At least one of the fields trip_update, vehicle, alert, or shape must be provided - all these fields cannot be empty. | + ## _message_ TripUpdate @@ -227,6 +229,7 @@ Defines updated properties of the trip | **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. | +| **shape_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | Specifies the shape of the vehicle travel path for this trip when it differs from the original. Refers to a shape defined in the (CSV) GTFS or a new shape entity in a real-time feed. See definition of `trips.shape_id` in (CSV) GTFS.

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | ## _message_ VehiclePosition @@ -504,3 +507,32 @@ A localized string mapped to a language. |------------------|------------|----------------|-------------------|-------------------| | **text** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Required | One | A UTF-8 string containing the message. | | **language** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Conditionally required | One | BCP-47 language code. Can be omitted if the language is unknown or if no internationalization is done at all for the feed. At most one translation is allowed to have an unspecified language tag - if there is more than one translation, the language must be provided. | + +## _message_ Shape + +Describes the physical path that a vehicle takes when it's not part of the (CSV) GTFS, such as for a detour. Shapes belong to Trips, and consist of a sequence of shape points. Tracing the points in order provides the path of the vehicle. Shapes do not need to intercept the location of Stops exactly, but all Stops on a trip should lie within a small distance of the shape for that trip, i.e. close to straight line segments connecting the shape points + +**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**_ | +|------------------|------------|----------------|-------------------|-------------------| +| **shape_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Required | One | Identifier of the shape. Must be different than any `shape_id` defined in the (CSV) GTFS.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | +| **shape_point** | [ShapePoint](#message-shapepoint) | Required | Many | Points in the shape. A shape must contain at least two shape points. ShapePoints must be ordered by shape_pt_sequence.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | + +## _message_ ShapePoint + +A shape for a trip that has been updated. + +**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**_ | +|------------------|------------|----------------|-------------------|-------------------| +| **shape_pt_lat** | [float](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Required | One | Latitude of a shape point. See definition of `shapes.shape_pt_lat` in (CSV) GTFS.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | +| **shape_pt_lon** | [float](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Required | One | Longitude of a shape point. See definition of `shapes.shape_pt_lon` in (CSV) GTFS.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | + | **shape_dist_traveled** | [float](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Conditionally required | One | See definition of `shapes.shape_dist_traveled` in (CSV) GTFS.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | + | **shape_pt_sequence** | [int32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Required | One | See definition of `shapes.shape_pt_sequence` in (CSV) GTFS. +
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | From 9f17895eb9b1bddca64a054cf0e5aad7f0caef64 Mon Sep 17 00:00:00 2001 From: ericouyang Date: Fri, 9 Jul 2021 15:15:58 -0400 Subject: [PATCH 2/7] Change to using encoded polylines --- gtfs-realtime/proto/gtfs-realtime.proto | 39 +++++-------------------- 1 file changed, 8 insertions(+), 31 deletions(-) diff --git a/gtfs-realtime/proto/gtfs-realtime.proto b/gtfs-realtime/proto/gtfs-realtime.proto index 78ea7775e..ab8812586 100644 --- a/gtfs-realtime/proto/gtfs-realtime.proto +++ b/gtfs-realtime/proto/gtfs-realtime.proto @@ -904,40 +904,17 @@ message Shape { // Identifier of the shape. Must be different than any shape_id defined in the (CSV) GTFS. // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future. required string shape_id = 1; - - // Points in the shape. A shape must contain at least two shape points. ShapePoints must be ordered by shape_pt_sequence. - // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future. - repeated ShapePoint shape_point = 2; - - // 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; -} - -// A shape for a trip that has been updated. -// NOTE: This message is still experimental, and subject to change. It may be formally adopted in the future. -message ShapePoint { - // Latitude of a shape point. See definition of shapes.shape_pt_lat in (CSV) GTFS. + + // Encoded polyline representation of the shape. This polyline must contain at least two points. + // The distance between points can be optionally specified, like in (CSV) GTFS, through dist_traveled + // For more information about encoded polylines, see https://developers.google.com/maps/documentation/utilities/polylinealgorithm // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future. - required float shape_pt_lat = 1; - - // Longitude of a shape point. See definition of shapes.shape_pt_lon in (CSV) GTFS. - // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future. - required float shape_pt_lon = 2; - - // Actual distance traveled along the shape from the first shape point to the point specified in this record. + required string encoded_polyline = 2; + + // Optional list of actual cumulative distances traveled along the shape to each point in encoded_polyline // See definition of shapes.shape_dist_traveled in (CSV) GTFS. // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future. - optional float shape_dist_traveled = 3; - - // Sequence in which the shape points connect to form the shape. Values must increase along the trip but do not need to be consecutive. - // See definition of shapes.shape_pt_sequence in (CSV) GTFS. - // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future. - required uint32 shape_pt_sequence = 4; + repeated float dist_traveled = 3; // The extensions namespace allows 3rd-party developers to extend the // GTFS Realtime Specification in order to add and evaluate new features and From eec0f8908c666da8de6856a20081176f396e78d5 Mon Sep 17 00:00:00 2001 From: Eric Ouyang Date: Mon, 16 Aug 2021 19:16:39 -0400 Subject: [PATCH 3/7] Remove dist_traveled --- gtfs-realtime/proto/gtfs-realtime.proto | 6 ------ 1 file changed, 6 deletions(-) diff --git a/gtfs-realtime/proto/gtfs-realtime.proto b/gtfs-realtime/proto/gtfs-realtime.proto index ab8812586..d3d30236b 100644 --- a/gtfs-realtime/proto/gtfs-realtime.proto +++ b/gtfs-realtime/proto/gtfs-realtime.proto @@ -906,15 +906,9 @@ message Shape { required string shape_id = 1; // Encoded polyline representation of the shape. This polyline must contain at least two points. - // The distance between points can be optionally specified, like in (CSV) GTFS, through dist_traveled // For more information about encoded polylines, see https://developers.google.com/maps/documentation/utilities/polylinealgorithm // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future. required string encoded_polyline = 2; - - // Optional list of actual cumulative distances traveled along the shape to each point in encoded_polyline - // See definition of shapes.shape_dist_traveled in (CSV) GTFS. - // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future. - repeated float dist_traveled = 3; // The extensions namespace allows 3rd-party developers to extend the // GTFS Realtime Specification in order to add and evaluate new features and From dd1decc7d41539ebaec43e738e229df3225e95e0 Mon Sep 17 00:00:00 2001 From: Eric Ouyang Date: Mon, 16 Aug 2021 19:18:46 -0400 Subject: [PATCH 4/7] Update reference --- gtfs-realtime/spec/en/reference.md | 20 ++------------------ 1 file changed, 2 insertions(+), 18 deletions(-) diff --git a/gtfs-realtime/spec/en/reference.md b/gtfs-realtime/spec/en/reference.md index 5dab22930..a9ec0b64e 100644 --- a/gtfs-realtime/spec/en/reference.md +++ b/gtfs-realtime/spec/en/reference.md @@ -510,7 +510,7 @@ A localized string mapped to a language. ## _message_ Shape -Describes the physical path that a vehicle takes when it's not part of the (CSV) GTFS, such as for a detour. Shapes belong to Trips, and consist of a sequence of shape points. Tracing the points in order provides the path of the vehicle. Shapes do not need to intercept the location of Stops exactly, but all Stops on a trip should lie within a small distance of the shape for that trip, i.e. close to straight line segments connecting the shape points +Describes the physical path that a vehicle takes when the shape is not part of the (CSV) GTFS, such as for an ad-hoc detour. Shapes belong to Trips and consist of an encoded polyline for more efficient transmission. Shapes do not need to intercept the location of Stops exactly, but all Stops on a trip should lie within a small distance of the shape for that trip, i.e. close to straight line segments connecting the shape points **Caution:** this message is still **experimental**, and subject to change. It may be formally adopted in the future.
. @@ -519,20 +519,4 @@ Describes the physical path that a vehicle takes when it's not part of the (CSV) | _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ | |------------------|------------|----------------|-------------------|-------------------| | **shape_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Required | One | Identifier of the shape. Must be different than any `shape_id` defined in the (CSV) GTFS.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | -| **shape_point** | [ShapePoint](#message-shapepoint) | Required | Many | Points in the shape. A shape must contain at least two shape points. ShapePoints must be ordered by shape_pt_sequence.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | - -## _message_ ShapePoint - -A shape for a trip that has been updated. - -**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**_ | -|------------------|------------|----------------|-------------------|-------------------| -| **shape_pt_lat** | [float](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Required | One | Latitude of a shape point. See definition of `shapes.shape_pt_lat` in (CSV) GTFS.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | -| **shape_pt_lon** | [float](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Required | One | Longitude of a shape point. See definition of `shapes.shape_pt_lon` in (CSV) GTFS.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | - | **shape_dist_traveled** | [float](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Conditionally required | One | See definition of `shapes.shape_dist_traveled` in (CSV) GTFS.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | - | **shape_pt_sequence** | [int32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Required | One | See definition of `shapes.shape_pt_sequence` in (CSV) GTFS. -
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | +| **encoded_polyline** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Required | One | Encoded polyline representation of the shape. This polyline must contain at least two points.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | From 513192f5d2e443499480a5827a0fddd5cfb9b504 Mon Sep 17 00:00:00 2001 From: ericouyang Date: Tue, 17 Aug 2021 18:16:54 -0400 Subject: [PATCH 5/7] Update reference.md --- 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 a9ec0b64e..557cc9101 100644 --- a/gtfs-realtime/spec/en/reference.md +++ b/gtfs-realtime/spec/en/reference.md @@ -519,4 +519,4 @@ Describes the physical path that a vehicle takes when the shape is not part of t | _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ | |------------------|------------|----------------|-------------------|-------------------| | **shape_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Required | One | Identifier of the shape. Must be different than any `shape_id` defined in the (CSV) GTFS.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | -| **encoded_polyline** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Required | One | Encoded polyline representation of the shape. This polyline must contain at least two points.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | +| **encoded_polyline** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Required | One | Encoded polyline representation of the shape. This polyline must contain at least two points. For more information about encoded polylines, see https://developers.google.com/maps/documentation/utilities/polylinealgorithm
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | From 603d4bfbcfb431bd706d7a446996fcd829745af8 Mon Sep 17 00:00:00 2001 From: ericouyang Date: Thu, 19 Aug 2021 09:32:16 -0400 Subject: [PATCH 6/7] Clarify TripProperties.shape_id --- gtfs-realtime/proto/gtfs-realtime.proto | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/gtfs-realtime/proto/gtfs-realtime.proto b/gtfs-realtime/proto/gtfs-realtime.proto index d3d30236b..6a11f8016 100644 --- a/gtfs-realtime/proto/gtfs-realtime.proto +++ b/gtfs-realtime/proto/gtfs-realtime.proto @@ -356,13 +356,15 @@ 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; - // Specifies the new shape of the vehicle travel path when the trip shape differs from the shape specified in - // (CSV) GTFS. See definition of trips.shape_id in (CSV) GTFS. This can refer to a shape defined in the - // (CSV) GTFS in shapes.txt or a Shape the (protobuf) real-time feed. The order of stops (stop sequences) for this - // trip must remain the same as (CSV) GTFS. Stops that are a part of the original trip but will no longer be made, - // such as when a detour occurs, should be marked as schedule_relationship=SKIPPED. - // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future. - optional string shape_id = 4; + // Specifies the shape of the vehicle travel path when the trip shape differs from the shape specified in + // (CSV) GTFS or to specify it in real-time when it's not provided by (CSV) GTFS, such as a vehicle that takes differing + // paths based on rider demand. See definition of trips.shape_id in (CSV) GTFS. If a shape is neither defined in (CSV) GTFS + // nor in real-time, the shape is considered unknown. This field can refer to a shape defined in the (CSV) GTFS in shapes.txt + // or a Shape in the (protobuf) real-time feed. The order of stops (stop sequences) for this trip must remain the same as + // (CSV) GTFS. Stops that are a part of the original trip but will no longer be made, such as when a detour occurs, should + // be marked as schedule_relationship=SKIPPED. + // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future. + optional string shape_id = 4; // The extensions namespace allows 3rd-party developers to extend the // GTFS Realtime Specification in order to add and evaluate new features From 3206e363170c22f8e80d4b2e92df786fa5c2899a Mon Sep 17 00:00:00 2001 From: Eric Ouyang Date: Wed, 25 Aug 2021 15:14:33 -0700 Subject: [PATCH 7/7] Address PR comments --- gtfs-realtime/proto/gtfs-realtime.proto | 10 ++++++++-- gtfs-realtime/spec/en/reference.md | 6 +++--- 2 files changed, 11 insertions(+), 5 deletions(-) diff --git a/gtfs-realtime/proto/gtfs-realtime.proto b/gtfs-realtime/proto/gtfs-realtime.proto index 6a11f8016..ede2af533 100644 --- a/gtfs-realtime/proto/gtfs-realtime.proto +++ b/gtfs-realtime/proto/gtfs-realtime.proto @@ -103,6 +103,8 @@ message FeedEntity { optional TripUpdate trip_update = 3; optional VehiclePosition vehicle = 4; optional Alert alert = 5; + + // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future. optional Shape shape = 6; // The extensions namespace allows 3rd-party developers to extend the @@ -904,13 +906,17 @@ message TranslatedString { // NOTE: This message is still experimental, and subject to change. It may be formally adopted in the future. message Shape { // Identifier of the shape. Must be different than any shape_id defined in the (CSV) GTFS. + // This field is required as per reference.md, but needs to be specified here optional because "Required is Forever" + // See https://developers.google.com/protocol-buffers/docs/proto#specifying_field_rules // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future. - required string shape_id = 1; + optional string shape_id = 1; // Encoded polyline representation of the shape. This polyline must contain at least two points. // For more information about encoded polylines, see https://developers.google.com/maps/documentation/utilities/polylinealgorithm + // This field is required as per reference.md, but needs to be specified here optional because "Required is Forever" + // See https://developers.google.com/protocol-buffers/docs/proto#specifying_field_rules // NOTE: This field is still experimental, and subject to change. It may be formally adopted in the future. - required string encoded_polyline = 2; + optional string encoded_polyline = 2; // 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 557cc9101..c27aac93a 100644 --- a/gtfs-realtime/spec/en/reference.md +++ b/gtfs-realtime/spec/en/reference.md @@ -123,7 +123,7 @@ A definition (or update) of an entity in the transit feed. If the entity is not | **trip_update** | [TripUpdate](#message-tripupdate) | Conditionally required | One | Data about the realtime departure delays of a trip. At least one of the fields trip_update, vehicle, alert, or shape must be provided - all these fields cannot be empty. | | **vehicle** | [VehiclePosition](#message-vehicleposition) | Conditionally required | One | Data about the realtime position of a vehicle. At least one of the fields trip_update, vehicle, alert, or shape must be provided - all these fields cannot be empty. | | **alert** | [Alert](#message-alert) | Conditionally required | One | Data about the realtime alert. At least one of the fields trip_update, vehicle, alert, or shape must be provided - all these fields cannot be empty. | -| **shape** | [Shape](#message-shape) | Conditionally required | One | Data about the realtime added shapes, such as for a detour. At least one of the fields trip_update, vehicle, alert, or shape must be provided - all these fields cannot be empty. | +| **shape** | [Shape](#message-shape) | Conditionally required | One | Data about the realtime added shapes, such as for a detour. At least one of the fields trip_update, vehicle, alert, or shape must be provided - all these fields cannot be empty.

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | ## _message_ TripUpdate @@ -518,5 +518,5 @@ Describes the physical path that a vehicle takes when the shape is not part of t | _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ | |------------------|------------|----------------|-------------------|-------------------| -| **shape_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Required | One | Identifier of the shape. Must be different than any `shape_id` defined in the (CSV) GTFS.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | -| **encoded_polyline** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Required | One | Encoded polyline representation of the shape. This polyline must contain at least two points. For more information about encoded polylines, see https://developers.google.com/maps/documentation/utilities/polylinealgorithm
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | +| **shape_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Required | One | Identifier of the shape. Must be different than any `shape_id` defined in the (CSV) GTFS.

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | +| **encoded_polyline** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Required | One | Encoded polyline representation of the shape. This polyline must contain at least two points. For more information about encoded polylines, see https://developers.google.com/maps/documentation/utilities/polylinealgorithm

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. |