Invalid/Confusing Provider Updates specified in Upgrading to 1.0.0 wiki page

[billdirks]

On this wiki page MDS has provided a list of translations from 0.4.1 (event_type, event_type_reason) pairs to 1.0.0 (vehicle_state, [event_types]) pairs. This is overall very useful but there appear to be a few invalid or confusing 1.0.0 pairs.

In the following table "vehicle state events table" refers to this section of the general information specification document.

0.4.1 pair	1.0.0 pair	Reason
(removed, service_end)	(removed, [off_hours])	In 1.0.0, according to the vehicle state events table, off_hours is only valid for a transition to non_operational and not to removed. There are multiple possible alternatives. If we want to implicitly include the non_operational off_hours transition one could do (removed, [off_hours, rebalance_pick_up]).
(available, service_start)	(available, [on_hours])	This is slightly more complicated since the the pairs are valid. However, thinking about the previous states and the transition makes this mapping problematic. In 1.0, according to the vehicle state events table, on_hours is only allowed on transitions from non_operational. In 0.4.1, the only way for a vehicle to be unavailable, the non_operational equivalent, is due to a maintenance or low battery event type reason and not a service_end event type reason which can only be associated with a removed event. This mapping seems incongruous since on_hours implies an non_operational to operational transition, ie the vehicle is on the PROW and turning on for the day, while service_start implies removed (or None) to available transition.

One solution for 1.2.0 would be to allow off_hours and on_hours to be associated with more transitions. For now with 1.0 we may want to update this table.

One other transition to call out is the (reserved, user_pick_up) to (reserved, [reservation_start]). As noted in 0.4.1 Event Types table, reserved is used ambiguously. So there seems to be 2 possible mappings depending on how the operator has used reserved. One is the mapping provided here. The other, where reserved means trip start, would be to (on_trip, [reservation_start, trip_start]).

I'm happy to update the wiki but wanted to bring this topic for discussion before any changes are made.

[tonial]

:+1: I was about to create an issue with the first pair in the Upgrading-to-1.0.0 wiki page.

[schnuerle]

I will take a look at this and see if I can make the edits you suggest, then circle back. Thank you!

[schnuerle]

Issue 1 - off_hours transitions

I think the intention with the design of this in the spec (leaving the wiki guide out of it for now) is that the off_hours and on_hours events would only happen between non_operational and available. Eg., if you want to go from available to removed with off_hours, you would have to go through non_operational on purpose, even if just for a second.

Tagging @karcass and @thekaveman for their thoughts on this because they worked on this API Reconciliation effort more than anyone.

The solution then is to update the wiki guide with this corrected line, changing removed vehicle_state to unavailable:

event_type	event_type_reason	->	vehicle_state	event_type
removed	service_end	->	unavailable	off_hours

Issue 2 - Available, service_start

I don't fully follow what the issue is here. Could you try to explain it a different way?

Issue 3 - Reserved transitions

Yes that in 0.4.1 reserved is used ambiguously and there are 2 ways you could map it to 1.0 fields. For where reserved means trip start, are you suggesting that another line be added to the wiki guide to make this clear? Eg., reserved could also go to on_trip trip_start?

MDS Release 1.2.0

More of a note, but we could add states if needed for the 1.2 release, as long as they are non-breaking. Changing states seems breaking, but adding seems ok.

[schnuerle]

I will update this along with the upcoming 1.2 release. Could you review my questions above? @thekaveman and @marie-x and @avatarneil feel free to weigh in.

[schnuerle]

I fixed Issue 1 on the wiki page. For issues 2 and 3, I need some more clarity and feedback, as listed above.