trips, schedules and legs in fptf 2

[juliuste]

This issue is an attempt to bundle and advance the discussion about major changes to FPTF types in version 2, previously debated in #5, #33 and #42.

---

General consensus

There are a few points about which there seemed to be general consensus (?):

• Introduce a trip type (mentioned in this comment)
• Adapt the schedule type to fit together with the newly introduced trip type (mentioned in this comment)
• Change how we handle time information in journey and stopover to distinguish between realtime and scheduled dates (mentioned in this comment)

However, we didn't agree on any specific specification changes yet, so here's my proposal, please express your opinions!

---

schedule, trip and leg

In my original proposal to introduce a trip type, I initially intended to remove the schedule type entirely. However @derhuerst made the point that in some cases it might actually be useful to have another “aggregator“ type like schedule so that a large amount of trips could also be condensed to a smaller amount of schedules (like in GTFS, for example).

What I take from this is that we should design both types in a way that one could always generate a consistent dataset using only trips from one using schedules. This doesn't need to work vice versa however, since trips can contain additional data, e.g. realtime information, that doesn't belong to a schedule. With this in mind, I came up with the following specification(s):

trip

{
	type: 'trip', // required
	id: '12345', // unique, required
	line: '1234', // line id or object, optional
	route: '1234', // route id or object, optional
	mode: 'bus', // required if route is an id or if the trip mode differs from the route mode
	subMode: …, // reserved for future use
	stopovers: [] // required, list of stopover objects
}

One could discuss adding an optional schedule key similar to trip.route or trip.line.

schedule

schedule.starts is an object tripId -> startTime now instead of an array. This allows both to translate a schedule into a set of single trips as well as to provide updated realtime information for trips that are part of a schedule (as discussed in #43).

Also, schedule.line was added to be consistent with the other objects.

{
	type: 'schedule', // required
	id: '12345', // unique, required
	route: '1234', // route id or object, required
	line: '1234', // line id or object, optional
	mode: 'bus', // see section on modes, overrides `route`/`line` mode, e.g. for replacements services
	subMode: …, // reserved for future use
	sequence: [
		// seconds relative to departure at first station/stop
		// in 1-to-1 relation to `route` stops
		{
			arrival: -30 // optional, when the vehicle enters the route
			// The departure at the first stop must be 0.
			departure: 0 // required
		},
		{
			arrival: 50, // optional
			departure: 70 // required
		}
		{
			arrival: 120, // The arrival at the last stop is required.
			departure: 150 // optional, when the vehicle leaves the route
		}
	],
	starts: { // object trip.id -> Unix timestamp, required
		'trip1234': 1488379661, // start time of the trip
   		'trip2345': 1488379761,
		'trip3456': 1488379861,
		'trip4567': 1488379961
	}
}

We could further discuss whether to use timestamps or dates as values in the starts object, I kept the timestamps for now.

leg

I suggest that we treat leg as a separate new type, enabling applications to differentiate between trips, which are associated to the movement of an actual vehicle, meaning that the trip starts where the vehicle/line starts and ends where the line/vehicle movement ends, and legs, which depend on the movement of the passenger.

{
	type: 'leg', // required
	id: '12345', // unique, required
	trip: '1234', // trip id or object, optional
	line: '1234', // line id or object, optional
	schedule: undefined, // removed, schedules - if used - should be referenced using the trip or trip id
	// other keys of the existing journey.leg specification
	// see proposed spec changes regarding date information below
}

---

scheduled / realtime data in leg and stopover

I applied the proposal from #33 to leg and stopover, giving us the following spec changes:

leg

{
	type: 'leg', // required
	id: '12345', // unique, required
	
	// other keys mentioned above
	
	schedule: undefined // removed, see explanation above
	departure: undefined, // removed
	departureDelay: undefined, // removed
	arrival: undefined, // removed
	arrivalDelay: undefined, // removed

	scheduledDeparture: '2017-03-17T15:00:00+02:00', // ISO 8601 string (with origin timezone), required if `realtimeDeparture` is null
	realtimeDeparture: '2017-03-17T15:01:00+02:00', // ISO 8601 string (with origin timezone), required if `scheduledDeparture` is null
	scheduledArrival: '2017-03-17T15:00:00+02:00', // ISO 8601 string (with destination timezone), required if `realtimeArrival` is null
	realtimeArrival: '2017-03-17T15:01:00+02:00' // ISO 8601 string (with destination timezone), required if `scheduledArrival` is null
}

stopover

{
	type: 'stopover', // required
	// other keys defined in the stopover spec
	
	line: '1234', // line id or object, optional
	trip: '1234', // trip id or object, optional
	schedule: undefined // removed, schedules - if used - should be referenced using the trip or trip id
	
	departure: undefined, // removed
	departureDelay: undefined, // removed
	arrival: undefined, // removed
	arrivalDelay: undefined, // removed

	scheduledDeparture: '2017-03-17T15:00:00+02:00', // ISO 8601 string (with origin timezone), required if `realtimeDeparture` is null
	realtimeDeparture: '2017-03-17T15:01:00+02:00', // ISO 8601 string (with origin timezone), required if `scheduledDeparture` is null
	scheduledArrival: '2017-03-17T15:00:00+02:00', // ISO 8601 string (with destination timezone), required if `realtimeArrival` is null
	realtimeArrival: '2017-03-17T15:01:00+02:00' // ISO 8601 string (with destination timezone), required if `scheduledArrival` is null
}

---

Again, this is just a proposal based on previous discussions, so please express your opinions!

[juliuste]

Related: #27

[juliuste]

(Notification @matkoniecz @ialokim, because I can't assign you)

[ialokim]

Thanks @juliuste for pushing things towards the FPTFv2 release and for starting this discussion putting together the different ideas!

While I was thinking about the specification changes proposed above, I found it quite difficult to imagine all the object's relations. I've drawn a little schema which you can find here and which will hopefully help us to get a better overview of all the objects and fields defined in FPTF.

The schema is a first draft for FPTF v2, so it already includes your suggestions from above and the ones that I am going to add now. Changes regarding FPTF v1 should all be marked by the red color.

Feel free to edit the schema as it is made using the open source diagram website draw.io, you only have to click on the little edit icon at the bottom and post a new link in the comments.

---

I will explain my proposals for each FPTF type separately while also commenting @juliuste's ideas from above.

line

While playing a bit with FPTF, I found it a bit confusing that there is only a line.name and no line.number field. I would suggest to add the latter as a new optional field which would only contain the line number. As an example, for the metro line 1 of Paris line.number would only be 1 while line.name would be M1, and the product type "metro" should be expressed differently (refer also to the discussions regarding subMode and/or products, in my opinion at least one of it should make it in FPTF v2 as well).

route

I propose to add the two fields route.origin and route.destination which would be especially useful for the departures and arrivals at one specific station (see also the stopover type). Also, as many trips will be sharing the same route, I suggest a new array of trip objects (or rather references) as route.trips.

trip

I totally agree on adding a new trip type which is especially useful for third-party API clients and realtime data. I like your suggestion to keep the schedule type for static data, too, so I generally agree on your proposal about trip.

One could discuss adding an optional schedule key similar to trip.route or trip.line.

I don't think this would have any real use-cases; as you've mentioned schedule should be more like an compact way of expressing schedules for static data that could be processed to get trip objects, whereas trip.schedule field won't provide you more information as the trip already contains IMHO.

schedule

schedule.starts is an object tripId -> startTime now instead of an array.

This looked a bit strange to me at first, but thinking about it, I couldn't find any better solution. So I'm backing your suggestion, but would opt for using ISO-8601 date strings instead of Unix timestamps to keep it consistent with other fields like realtimeDeparture e.g.
I also agree on adding the optional schedule.line.

leg

Introducing the new type leg seems very reasonable for me but I would not include a leg.id field as it won't be very reproducible in most cases (at least I can't think of one where it would be necessary to refer to some walking leg of some API response).

On the other hand, I propose to add an optional leg.route field here too to keep things consistent. I quite like your proposals for expressing scheduled and realtime data, so no complaints about this part.

stopover

Same thing about realtime data here. But regarding the discussion in FPTI-JS#4, I think it would be best to keep stopover as the result type for arrivals and departures methods. In order to be useful for that purpose, I suggest to add the optional stopover.line, stopover.route and stopover.trip fields. Especially the corresponding line would contain the line number and the route the origin and destination (see above).

stop, station, location, region

I do not have any changes for these types.

---

I am sorry for the large comment, but I don't wanted to open a lot of different issues as most of the ideas are quite related. If you feel like there is need for a deeper discussion about one of them, feel free to open a new issue!