Last year, Open Referral introduced Version 1.0 of the Human Services Data Specification — an open data exchange format designed to make it easier for different organizations to share standardized information about the health, human, and social services available to people in need. Since then, a broad range of organizations have used the HSDS to make resource directory data easier to find and use in new ways in their communities.
We’ve received a lot of great feedback along the way, and we’re now ready to put this learning into action — by improving the HSDS itself, and making it easier for people and organizations to use.
This upgrade cycle has already begun: the Open Data Services Cooperative (read their introduction here) has recently taken a series of steps to make it easier to understand, comment upon, and work with the HSDS.
Introducing our new documentation
First of all, Open Referral now has our very own Github organization, which hosts our data specification and associated materials. You can check us out here.
(For those of you who are unfamiliar with Github, here is a helpful video from our friends at OpenOakland about how to use it to discuss issues!)
We’ve also made it easier to navigate our documentation. Previous iterations of our spec were published in both Google Docs and Github, we’ve now deprecated our Google Docs version and consolidated the documentation in one Github repository. Our Github account now hosts the ‘single source of truth’ for the HSDS.
However, Github can be intimidating to newcomers, and we want to ensure that this content is accessible to everyone. So by adopting the great ReadTheDocs service, Docs.OpenReferral.Org now automatically displays the contents of our HSDS Github repository. Read through the documentation here: openreferral.readthedocs.io
You can comment directly on Docs.OpenReferral.Org by creating a Hypothes.is account (see image below); we will engage with your comments there, and generate ‘Issues’ based on your feedback.
If you want to follow along with all issues, you can ‘watch’ (i.e. get notifications about) the repository for the Human Services Data Specification here.
Note that the HSDS repository has several new components: we’ve updated the README, and added a Contributor’s Guide and an FAQ. We’ve included a Creative Commons license (more on that in a future post). And we’ve also added a sample dataset, so that you can see an example of HSDS in action. All of these documents are subject to change over time, and your feedback is welcome.
Towards HSDS v1.1 — and beyond
It’s now time to begin the next round of upgrades for the Human Services Data Specification.
We invite you to participate in a ‘Request for Comment’ period for Version 1.1 of the HSDS. Through the end of the year, we’ll solicit your feedback in our Issues queue, via comments added directly on our documentation site, and in our Google Group.
In January, the Open Data Services Coop team will offer proposals that address actionable issues. The release of version 1.1 is scheduled for February. In March, we aim to share a roadmap to version 2.0, along with procedural proposals for the next cycle.
It’s important to note that this v1.1 upgrade cycle will have a deliberately narrow scope.
First, we’ll consider a set of proposed enhancements and revisions to the HSDS documentation, with the objective of making it easier to read, comprehend, and navigate. (These improvements are already underway.)
Second, we’ll consider a limited set of proposed changes to our schema. These will comprise fairly minor revisions and additions. My proposed criteria for changes include:
i) the change clarifies something that was unclear in HSDS 1.0;
ii) the change makes things easier for database administrators, and/or service providers and help seekers;
iii) the change does not cause significant incompatibility with existing implementations in our pilot projects.
Third, we’ll identify a set of issues that aren’t ‘minor’ and won’t be addressed in this upgrade, but will be placed for consideration on a ‘roadmap’ to HSDS 2.0.*
Fourth, we’ll consider proposals for an updated governance process that will guide us along the path to HSDS Version 2.0.
*(In general, we are committed to seek rough consensus and flowing data. In other words: all stakeholders don’t need to agree on everything, but if a change proposal is accompanied by actual data, and stakeholders all feel like they can live with the change, then we’ll accept it. Some issues we’ll know immediately are too challenging to address now; others will fall into this category if they don’t readily meet with clear consensus.)
I’d welcome feedback on this procedural framework. In the meantime, I encourage you to start filing issues for potential future upgrades to the HSDS!
We are still in the early stages of our journey.
It’s worth taking a moment to appreciate how far we’ve come already. When Open Referral first began, we were co-sponsored by Code for America and the Ohana Project. With technical support from the Ohana team, and institutional support from CfA, our data specification received comments from scores of subject matter experts, practitioners, researchers, social workers, information scientists, web standards officials, and more.
And once it was out there in the world, we all stepped back to see what people would do with it.
Almost two years later, we have a broad set of feedback from a range of early adopters.
New partnerships are experimenting with the specification in new ways. We’re working with Open Knowledge International and the Open Data Services Cooperative, to improve our documentation and tooling. We’re working with the Alliance of Information and Referral Systems to promote open source principles and development across the sector. The path ahead is long, but we should take opportunities to celebrate when we can.
So a heartfelt thank you to everyone who has helped us get this far! Now let’s get back to work: review, revise, and reiterate!
Leave a Reply