Improve JSON Schema for event types and reasons

[thekaveman]

The spec defines these enums in somewhat of a hierarchy, e.g. each event_type_reason applies only to a specific event_type.

However the current schemas don't enforce this hierarchy. This should be addressed going forward.

Earlier discussion here and here.

[dyakovlev]

This is a little fiddly in jsonschema, and has the additional drawback of inducing relatively poor error messages.

I think this (stripped-down) example might work:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "sample conditional validation of a status change event",

  "type": "object",
  "required": ["event_type", "event_type_reason"],

  "oneOf": [
    {
      "properties": {
        "event_type": { "type": "string", "enum": ["available"] },
        "event_type_reason": {
          "type": "string",
          "enum": ["service_start", "user_drop_off", "rebalance_drop_off", "maintenance_drop_off"]
        }
      }
    },
    {
      "properties": {
        "event_type": { "type": "string", "enum": ["reserved"] },
        "event_type_reason": {
          "type": "string",
          "enum": ["user_pick_up"]
        }
      }
    },
    {
      "properties": {
        "event_type": { "type": "string", "enum": ["unavailable"] },
        "event_type_reason": {
          "type": "string",
          "enum": ["maintenance", "low_battery"]
        }
      }
    },
    {
      "properties": {
        "event_type": { "type": "string", "enum": ["removed"] },
        "event_type_reason": {
          "type": "string",
          "enum": ["service_end", "rebalance_pick_up", "maintenance_pick_up"]
        }
      }
    }
  ]
}

(inspired by the last example in the import pane of http://jsonvalidate.com/ which sadly doesn't let you deep-link)

[thekaveman]

This is interesting, I guess the problem is all the the rest of the fields would need to be repeated inside each properties inside each oneOf item? This can be done using the generating code, but as you point out, the error messages from validation are less than helpful in that situation.

A different (and breaking) idea is to define status or something as an object field itself, with event_type and event_type_reason as sub-properties; the schema for this field can then reference a structure like what you present in the common definitions (like we do for Point).

[dyakovlev]

It's possible to still have a top-level "properties" key with normal JSON Schema stuff in it. I omitted it to keep the code block focused on what we're trying to accomplish.

Packaging status updates would make it a little easier from a validation perspective, but not necessarily from a generation or consumption one. Since validation will hopefully be automatic anyway, and this seems to work, I don't know that it's worth introducing minor but breaking changes before anyone's put any real miles on the API..