Improve Transmodel Leg query

[t2gran]

Is your feature request related to a problem? Please describe.

THIS ISSUE IS JUST A SUMMARY OF MY INVESTIGATION ON THIS TOPIC FOR NOW - THIS IS NOT READY TO BE IMPLEMENTED, WE NEED TO DISCUSS IT FUTHER.

The current leg query fails for replaced and canceled ServiceJourneies. It also mixes information about one leg with meta-data, making the Leg less reusable.

Current API

type Leg {
  // Leg info
  fromPlace.., toPlace.., aimedStartTime:.., aimedEndTime.., expectedEndTime.., expectedStartTime..,
  directDuration.., distance.., duration.., elevationProfile.., generalizedCost.., intermediateQuays: [Quay!]!
  interchangeFrom..,   interchangeTo..,
  steps: [PathGuidance]!

  // convenience fields - from SJ/DSJ
  authority.., bikeRentalNetworks.., bookingArrangements .., 
  generalizedCost.., line.., mode.., line.., mode.., rentedBike.., ride.., transportSubmode.., walkingBike..,

  // Either SJ & date
  serviceDate: Date
  serviceJourney: ServiceJourney

  // or DSJ
  datedServiceJourney: DatedServiceJourney

  // Realtime info
  realtime: Boolean!
  fromEstimatedCall: EstimatedCall @timingData
  toEstimatedCall: EstimatedCall @timingData
  intermediateEstimatedCalls: [EstimatedCall!]! @timingData
  serviceJourneyEstimatedCalls: [EstimatedCall!]! @timingData
  situations: [PtSituationElement!]!

  nextLegs(filter: AlternativeLegsFilter = noFilter, next: Int = 1): [Leg!]
  previousLegs(filter: AlternativeLegsFilter = noFilter, previous: Int = 1): [Leg!]

}

enum AlternativeLegsFilter { noFilter, sameAuthority, sameLine,  sameMode, sameSubmode }

type Query {
  leg(id: ID!): Leg @timingData
  ...
}

Leg id

The transit leg id contains "for now":

• DatedServiceJourney(TripOnDate) or ServiceJourney(Trip) id
• OperatingDay (serviceDate)
• Board/Alight
  • stopPositionInPattern
  • Qauy ID

Note! We do not want to expose this fields, because we might chage it and also other Leg types have different identifier fields. For example a StreetLeg or OnDemand Leg where we might need other information to recreate the leg. The main purpose of the API is to be able to recreate the exact same leg.

There are several problems with the existing API.

1. The current leg ID does not work if there are even small changes to the stop pattern.
2. When a leg is unavailable then there is no meta-information available. This information would be useful to find alternatives. At the end of the isse, is a list of logged situations where this happens.
3. In cases where the DatedServiceJourney is replaced, we should be able to provide an alternative or a list of alternatives.
4. In cases where the DatedServiceJourney is canceled, we should at least be able to provide information that tells it is canceled.
5. A Leg is often replaced by multiple legs. Many buses is needed to replace one train, and very often this is only part of the whole stop pattern replaced. There is no type in OTP or in Transmodel API to represent part of a Itinerary/TripPattern. In trip planning a SequenceOfLegs is not needed, but for ticketing, producing timetables and replacing a Leg a SequenceOfLegs would be nice.

Goal / high level use-case

• Persist and refetch a Leg, for example used in a ticket. The leg id need to be valid for weeks.
• Detect changes to the leg like delays and take action like finding alternatives.
• Show other alternatives for the leg (next/previous leg feature). This is not the main topic in this issue but related. Providing timetable data for a railway segment. List all possible options visiting stop A, B and C. Limited transfers should be allowed, like guranteed transfers, transfers within a station, same Line but multiple ServiceJourneies and replaced DataServiceJourneies.

Refetch information about a leg in a TripPattern. For example checking that there is no delays. A Leg ID should be valid from the time a journey is planned until it happens.

Describe the solution you'd like

We need to work more on this, but here is some ideas

type StopPosition {
	stopPositionInPattern : int
	stop : StopLocation
}

// Unsure if we want to expose this
type TransitLegReference {
  id : String
  operatingDay : Date
  datedServiceJourney : DatedServiceJourney?
  serviceJourney : ServiceJourney
  from: StopPosition
	to: StopPosition
}

type DSJ {
  ...
  replacementFor' : DSJ[]
  replacedBy : DSJ[]
}

type LegConnection {
  // leg exist
  leg : Leg
	// or
	replacedBy : TripPattern[]
	ref : LegReference
}

leg(legId) : Leg
legTransitRef(legId) : TransitLegReference
legConnection(legId) : LegConnecion

Describe alternatives you've considered

Additional context

To list log events where todays leg query fails you may filter on org.opentripplanner.model.plan.legreference.ScheduledTransitLegReference.

These are some off the log messages we get at Entur:

• Transit leg reference with modified stop id within the same station: The referenced stop at position 0 with id 'RB:NSR:Quay:554' does not match the stop id 'RB:NSR:Quay:566' in trip null and service date 2025-02-10
• Invalid transit leg reference: the trip 'null' does not run on service date 2025-04-25
• Invalid transit leg reference: trip 'RB:INN:ServiceJourney:111_1_11' not found
• Invalid transit leg reference: boarding stop 44 or alighting stop 99 is out of range in trip 'RB:INN:ServiceJourney:110_1_26' and service date 2025-02-10 (95 stops in trip pattern)

(The logging can be improved - tripId is used in the )