Consider using JSON Schema

[ian-r-rose]

The mobility spec already provides some nice narrative description of the inputs and outputs for the REST API. However, there is still some room for ambiguity, and it would be useful to be able to test providers/agencies against regressions and compliance with the spec.

One commonly-used approach to this problem is to use a JSON schema. This allows you to describe JSON data structures in a well-typed fashion. This allows for

• validation
• regression testing
• a source of truth for the spec to guard against different interpretations of the narrative.
• Easier tracking of spec versions

For instance, a schema for the response body of the /deregister-vehicle might look something like:

{
  "properties": {
    "unique_id": {
      "type": "string"
    },
    "device_id": {
      "type": "string"
    },
    "reason_code": {
      "type": "string",
      "enum": ["rebalancing", "maintenance"]
    }
  },
  "type": "object",
  "additionalProperties": false
}

High-quality JSON-schema validators should exist in most web-friendly languages.

[thekaveman]

I think this is a great idea.

I will start putting together a PR for provider using JSON-schema so we can explore this idea further.

[hunterowens]

Agreed. We call out using JSON API (which includes JSON Schema) in the provider spec currently but the implementation is not there yet.

For Agency I believe we should enforce as well. @toddapetersen

[thekaveman]

I started putting something together over here: https://github.com/CityofSantaMonica/mobility-data-specification/blob/json-schema/provider/schema.json

Take a look at let me know if this seems like the right direction. I generated this using some sample data I cooked up and the tool at https://www.jsonschema.net/

[ian-r-rose]

@thekaveman that's awesome. Can you open a PR to allow for commenting?

[hunterowens]

This would be a breaking change, tagging as a 0.2.0 milestone.

[hunterowens]

#53 is merged. closing.