Introducing Version 3.0 of the Human Service Data Specifications

UPDATE: As of May 1st 2023, this upgrade is considered official! Thanks to our workgroup and all those in the community who contributed input. Read below for details.

This post is from Dan Smith, Open Data Services Cooperative‘s Partnerships Lead for Health, Social and Physical Activity Data. Welcome, Dan!

We are excited to share a proposal for version 3.0 of the Human Service Data Specifications – available now for a final two-week period of review and comment by our community. 


We have been working toward this proposal for much of the past year, in a community-led process of gathering input about emerging and outstanding needs across our expanding network of human service informatics.

Our upgrade process began in spring of 2022, when Mike Thacker of Porism and Devin Balkind of Sarapis jointly proposed a new version of HSDS that would formalise adaptations made by the Open Referral UK network, bringing these changes into the core standard. Last summer, we convened a workgroup of active adopters and community members with particular expertise to review and elaborate upon this proposal. The workgroup wrapped up this phase of work at the end of 2022, and since then I’ve helped Open Data Services Cooperative – Open Referral’s technical stewards – synthesise the workgroup’s recommendations into new specifications that now stand to become HSDS version 3.0.

We are excited to share the fruits of this process with the broader community.

How to provide feedback on HSDS 3.0

We encourage you to share feedback on version 3.0 in the following ways:

  • By commenting on this post on the Open Referral forum
  • By commenting in the specification’s Github issues queue
  • By commenting directly on the documentation page using the hypothes.is tool. (To comment directly on our documentation site, look in the top-right corner of the site – there’s a button that looks like the tip of an arrow, or an arrow bracket. Click that to open up the commenting feature. You’ll have to create an account with hypothes.is, and then you can comment away right there on our docs site in your browser.)
  • Via email to me at [email protected]
Instructions for using the hypothes.is feature to comment directly on Docs.OpenReferral.org

Use thehypothes.is feature to comment directly on Docs.OpenReferral.org – click the button on the top right of the page to open the feature. Then create an account, and start commenting!

Summary of Changes in HSDS 3.0

A summary of major changes as a result of HSDS 3.0 development cycle are as follows:

  • Data Model: A number of specific changes have been made to the data model and documentation, although the model’s fundamental architecture remains the same. (Most significantly, we have consolidated separate `address` tables into a single table, and separate `attributes` tables into a single table.) Details of these changes can be found in the documentation site’s changelog.
  • Data format: previously, the HSDS format was CSV files bundled by a JSON Data Package. Version 3.0 changes the core publishing format to JSON. We made this decision in part because JSON (using JSON Schema for validation) is a vastly more common interchange format, so we can benefit from a much greater range of tooling and expertise. For more information and context around this decision, please see this document. Please note that for implementations implementing a datapackage, the schema will still be compatible, supported and maintained.
  • API Specification: The Human Service Data API protocols (HSDA) have been redesigned – and merged into HSDS itself. In other words, HSDS is now an API-first standard, with endpoints designed around the core tables (service, location, organization, taxonomies, service_at_location). See the API reference page and Swagger ui version of the API for more details. We made this decision due to APIs becoming increasingly important to the Open Referral community, and that there are opportunities for collaboration around open-source tooling particularly around API development. In this process, the workgroup applied many lessons learned from Open Referral UK and elsewhere.

Ongoing work

Moving forward from the release of HSDS 3.0, we will build upon these changes with additional branches of work in the months ahead. Most prominently, this involves:

  • Developing methods of adapting HSDS – through extensions and/or ‘profiles’ that tailor HSDS to meet specific needs of particular communities, while maintaining compatibility across the ecosystem.
  • Developing tools to support adoption of HSDS (e.g. validators, transformers, mapping tools and preview tools).
  • Drafting a first prospective version of specifications for eligibility rule syntax, to make it easier to describe conditional logic of eligibility information in a machine-readable, portable format.

These workflows will not result in any new structural changes to the standard; rather, they will add new optional features to make HSDS more effective.

Appreciation for the leaders in our community

Many thanks to our workgroup members – Devin Balkind of Sarapis, Mike Thacker of Porism, Sarah Pottelberg of AIRS, Skyler Young of SiteSavvy, Paul Brown of PlaceCube, Ian Brown of Digital Coproduction, and Shelby Switzer of the Beeck Center – for their support in this process!

4 thoughts on “Introducing Version 3.0 of the Human Service Data Specifications

  1. Congratulations to all who did all this heavy lifting.

    As a service provider with several helplines in many markets, is there finally a single point of entry for our data which would then be shared throughout the network?

  2. Thanks, David!

    I wouldn’t say there’s a single point of entry, as the network is distributed and most organizations each maintain their own system. But you could use tools that are already available – like the Airtable template [https://openreferral.org/delivering-open-referral-solutions-with-airtable/] – to structure your data in a way that would then be machine-readable via API to 3rd party systems. So you could create a ‘single source of truth’ for your information that would be a reference for anyone who might leverage that data.

    Now that I mention it, we will have to upgrade the Airtable template to version 3.0 😉 hopefully that will come soon.

Leave a Reply

Your email address will not be published. Required fields are marked *