OpenAPI: Provide json with vehicle state machine

[kevinnio]

Hi, there. I'm working on writing a validator to make sure a vehicle goes from state to state through valid events and I was wondering if it would be helpful to include a .json file in the repo with an object that could be used to validate transitions. Something like this:

{
  "previous_state": {
    "new_state": ["valid_event_1", "valid_event_2", ...],
    ...
  },
  "non_operational": {
    "removed": ["maintenance_pick_up", "rebalance_pick_up", ...],
    "available": ["battery_charged", "maintenance", ...],
    "unknown": ["comms_lost", "missing", "unspecified"],
  },
}

I think it would help people building validators to have a file like this as a single source of truth in the repo.

[schnuerle]

For 2.0 we are thinking of moving to Open API. See #281. We are working on CDS first but welcome help with this from the community who want to work on it when we get started! I think state transitions could be included.

[marie-x]

I don't think OpenAPI would be able to handle the state machine. Also, we support receiving out-of-order events, so that's incompatible with having this validation in the API itself.

Having a little JSON blob like this as part of the spec is do-able though.

[schnuerle]

Do you think it could handle valid state transitions, just not the whole state machine? Thinking about it now I may agree with you it might not be possible. Asking @thekaveman for thoughts.

[thekaveman]

Following up on this issue:

The plan for the OpenAPI work is to represent what a valid event looks like, apart from any of it's related (previous) events -- since we can't represent a chain of requests/responses in OpenAPI, and as @marie-x notes, events may come out of order anyway.

So, like the 1.x JSON Schemas do, we'll be able to represent valid combinations of (new) vehicle_state and the event_types that can possibly take the vehicle to that state, according to the state machine of each mode.

E.g. for micromobility, for the reserved state, the valid event types to get to that state are:

• comms_restored
• located
• reservation_start
• unspecified

Which in the JSON (yaml) schema will look like

properties:
  vehicle_state:
     const: reserved
  event_types:
     items:
       enum:
          - comms_restored
          - located
          - reservation_start
          - unspecified