The general structure of the updated documentation
Unless there are any major objections, we are hoping to pause for now on any further changes to the schema itself. However, as there has been less consultation around the API specification, could we please ask that this is given priority when reviewing.
Please share you views in response to this post and/or at the workgroup meeting on the 27th March.
I think what it is meant, is that it is officially released, and be what users should implement from now on.
The way we have structured it, there can not be a single jsonschema, as it is possible to query the data from many perspectives (service, org and service at location). The directory of schemas has one file per table is the only place schema edits happen. From there, all the other various schema get generated, including the datapackage.
However, if you want a single jsonschema file that is not too nested this service one is possibly the most useful and it may make sense to link to this one from the docs.
Yes, it is generated from the above: datapackage. However, we should probably link it in the docs more clearly somewhere.
Yes, at some point, hopefully soon. We went with the latest version of openapi 3.1 standard, as it had better jsonschema support. However, the swagger UI does not support it yet. It is on their roadmap to complete very soon and they have a release candidate for it.
If there is any issue with them not doing it, in a reasonable time frame, we were going to write a quick translated version of the schema to work on an older interface, but did not want to waste the time if it will be out imminently.
I do think it’s worth linking to the a single service jsonschema and tabular data package files from the docs.
In the past we discussed a single file using organization as the root/highest level because people often compare system data (and will eventually dedupe) organization by organization. I don’t think it’s critical for this to exist but it’d certainly be helpful and worth linking to from docs if you have it handy.
As for the Swagger interface, your approach makes a lot of sense.
Thanks so much for all your work on this and looking forward to the official launch!
Making a downgraded schema (to openAPI 3.0) was in the end not too difficult, so there is a now a swagger page.
This swagger page also has schemas and examples for each endpoint.
And another request: on the Swagger can you add some basic introductory information and a link back to the docs.openreferral.org site so if people find themselves there as their first stop into HSDS land they know where to get more info?
Hi all, Great work with HSDS 3.0 I am excited to implement! I couldn’t find a link to the workgroup meeting today so I have typed up my feedback instead.
Hunger Free America has a very similar use case to Ian from Digital grasps (Our Model for Place-based DoS - #5 by Ian-DigitalGaps) where we have just too much data for our small team to stay on top of it all. To manage all of the data we partner with organizations like food banks that have smaller local lists of services that they maintain. Hunger Free America aggregates the data, cleans it, and assures it before publishing. These different data sources have varying levels of data accuracy and we would like to capture whether the data came from the service itself or from a partner organization. Additionally, our assurers are a mixture of volunteers and Hunger Free America staff so we don’t necessarily want to publish the assurer’s email address. My suggestion would be to create separate tables for assurer and data source so that we can better capture the nuance of who did what and when.
Some fields that I would like to see captured that currently are not: