3.0 for review and comment

Hi all,

We’ve reached a point where we’d like the broader community to review the updated standard before we progress with the full release.

A full list of changes can be found within the changelog.

We’d appreciate it if the technical community could take a look and feedback on:

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.



1 Like

Hi Dan. Thanks so much for pushing this forward. Looks like you all have done great work.

A few questions:

  • Can you explain what the “full release” will entail? Does that mean there is more documentation forthcoming or simply that it will be announced, etc?
  • Is there a single JSON Schema file available for the standard?
  • Is there a Tabular Data Package?
  • Will there be a Swagger interface for the API?


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.

1 Like

Thanks for the reply.

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!


Based on your feedback, we added this page:


The schema reference page now also has a tab where you can see the schemas for each entity eg.


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.

1 Like

These are fantastic changes. Really suits my needs. Thanks so much.

One more thing: with the ERD diagrams, can you:

  • include a note about how they were generated and, if it was with code, link to the code used
  • include a link to download the ERD images

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:


  • Email
  • Type (the service itself / 3rd party data source)


  • Name
  • Type (Volunteer/Staff)

Atticus Rains
Hunger Free America

1 Like

Hi Atticus,

Thanks for this. I’ve invited you to the workgroup meeting incase you still want to come along.