Agency schema

[ian-r-rose]

Fixes #169. Partial fix for #168.

I have tried to hew as closely as I could to the description in the README, with a couple of exceptions for things I thought were mistakes or unclear:

• Should reason_code in the update vehicle status API instead be the same as event_type_reason from the status_change API? It seemed to me that it should from the narrative description.
• I have gone ahead and changed several of the points to be MDS_Feature_Points as suggested in [agency] Consider using GEOJSON features #168.
• vehicle_type and propulsion_type seemed out of sync with the provider API. I updated them.

These schema are as yet not very well tested, and I am not aware of any synthetic data to put them through the works. Do you have anything you could point me towards @hunterowens or @thekaveman?
Finally, I notice that the spec does not include version fields in them, as is the case for provider. Should we consider adding that?

I have not added schema for any of the agency response types at the moment.

[ian-r-rose]

Ooh, I see this will conflict with #161. Happy to deal with those conflicts however you see fit.

[hunterowens]

We'll have to rebase and redo this after #194

Let's hold off on doing this until #195 #196 and #197 are done.

[marie-x]

Still waiting on #197, yes?

[hunterowens]

@karcass yes, and #203 if we go that route.

[hunterowens]

that being said, I don't think it would be a bad idea to get JSON schema definitions of the expected return values for an Agency API for now. We can ignore the /service_areas endpoint.

[marie-x]

Agreed, let me put a schema on the agency to-do list. It should be super simple. Register just reads back the vehicle it got, and /event and /telemetry basically just say "got it, thanks!" :)

[hunterowens]

hmm yeah.

perhaps it is a good idea to have valid schema definitions for both the inputs and outputs for an Agency API. Ie, what is valid to submit / and recieve.

To utilize the common datatype, you can see how we generate the official schemas in generate_schema/generate_provider_schema.py @ian-r-rose may be able to provide additional direction.

[marie-x]

I will likely require some guidance to be efficient / effective.

[hunterowens]

@karcass quick question - you guys did swagger / openAPI specs for the reference implementation, or I am not remembering that correctly.

[marie-x]

@hunterowens I'm evaluating options. Swagger seems like it's more suited for start-with-swagger (code generation etc.) rather than bolt-on-afterwards, and I didn't start with it. I am tentatively leaning towards using apidoc to extract my JavaDoc-style comments in the ref impl into doc files. Do you strongly favor swagger, is apidoc (or similar) acceptable?

[toddapetersen]

Closing this as the PR is no longer inline with the latest version of Agency spec. We will revisit the issue (#169 ) to generate a schema once the Agency sandbox evaluation period has wrapped up.

[hunterowens]

@toddapetersen I'd prefer to keep this open, as getting a formally definition of the schema, rather than a written version, is pretty critical.

[marie-x]

@hunterowens we will open a separate PR for that. This PR is out of date. We left the issue open for tracking.

[ian-r-rose]

I'm happy to update this once you feel like outstanding changes to the agency spec have been resolved (#197, #203, perhaps others?). Do you have any comments on my questions above, especially regarding status_change?

We may also want to migrate to openapi, as suggested above, though my inclination is to do things one-at-a-time.

[marie-x]

@ian-r-rose If you're offering to do part of my job for me, I graciously accept! I didn't think it was fair for us to rejigger everything and have you keep chasing a moving target.

Yes, agency has deliberately reframed event_type and event_type_reason as state and event_type. I apologize for the confusion, and I'm not sure how to fully reconcile agency and provider (and at present, perfect alignment is not a hard requirement). In the context of the agency API, we (various E&A folks, coding the first agency implementation) reached the conclusion that a state-machine representation of edges (events) and nodes (states) was closer to the ground-truth of what we were trying to capture. So, that's where we're at.

Happy to answer any additional questions.

[marie-x]

@ian-r-rose do you plan to update this PR?

[ian-r-rose]

Closing in favor of #238