Allow defining new `Shape` for trips with `TripUpdate.TripDescriptor.schedule_relationship=REPLACEMENT`

[VillePihlava]

Describe the problem

When using TripUpdate.TripDescriptor.schedule_relationship=REPLACEMENT, a new stop sequence must be given in TripUpdate.stop_time_update. However, the current wording of TripUpdate.TripProperties.shape_id states:

transit/gtfs-realtime/spec/en/reference.md

Line 267 in 474750a

| **shape_id** | [string](https://protobuf.dev/programming-guides/proto2/#scalar) | Optional | One | Specifies the identifier of 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. <br>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 same (protobuf) real-time feed. The order of stops (stop sequences) for this trip must remain the same as (CSV) GTFS. If it refers to a `Shape` entity in the same real-time feed, the value of this field should be the one of the `shape_id` inside the entity, and _not_ the `id` of `FeedEntity`.<br>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 or more details can be provided via a `TripModifications` message.<br><br>**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. |

The order of stops (stop sequences) for this trip must remain the same as (CSV) GTFS.

Would it make sense to have the possibility of defining a new shape for trips with changed stop sequences?

Use cases

A trip has its stop sequence replaced and now the old shape does not fit the new stops. Updating the shape would improve the end user experience.

Proposed solution

Change the wording from

The order of stops (stop sequences) for this trip must remain the same as (CSV) GTFS.

to this

The order of stops (stop sequences) for this trip must remain the same as (CSV) GTFS, unless schedule_relationship is REPLACEMENT, in which case shape_id may instead describe the vehicle path for the new stop sequence declared in TripUpdate.stop_time_update.

Additional information

I could not find a previous issue related to this. Also, should the wording include other types of trips, for example, TripUpdate.TripDescriptor.schedule_relationship=NEW?

[gcamp]

I agree with this change, and yes NEW should also be specified. I think it was just a oversight on the PR where NEW/REPLACEMENT was added

[VillePihlava]

Would this wording be ok?

-     The order of stops (stop sequences) for this trip must remain the same as (CSV) GTFS.
+     The shape must follow the order of stops (stop sequences) defined for the trip. For trips based on (CSV) GTFS,
+     this is the scheduled stop order, taking into account real-time modifications such as skipped stops.
+     For trips with `TripDescriptor.schedule_relationship` equal to `NEW` or `REPLACEMENT`,
+     the shape must follow the stop order defined by the trip's `StopTimeUpdate`s.

[leonardehrenfried]

For trips based on (CSV) GTFS, this is the scheduled stop order, taking into account real-time modifications such as skipped stops.

I'm not sure I can follow this sentence - isn't it contradictory? Could you rephrase it a bit?

[VillePihlava]

For trips based on (CSV) GTFS, this is the scheduled stop order, taking into account real-time modifications such as skipped stops.

I'm not sure I can follow this sentence - isn't it contradictory? Could you rephrase it a bit?

Essentially, it tries to cover what I assume was the old use case.

Maybe the wording can be simplified to something like this:

-     The order of stops (stop sequences) for this trip must remain the same as (CSV) GTFS.
+     The shape must follow the order of stops (stop sequences) defined for the trip,
+     while reflecting real-time modifications such as skipped stops.
+     For trips with `TripDescriptor.schedule_relationship` equal to `NEW` or `REPLACEMENT`,
+     the shape must follow the stop order defined by the trip's `StopTimeUpdate`s.

[leonardehrenfried]

I like this better.