[UPDATE: links to our documentation have been changed to direct to our new documentation site, Docs.OpenReferral.org]
Earlier this month, we published version 1.0 of the Human Service Data Specification (HSDS). Let’s take a deeper dive into it.
What is the Human Service Data Specification (HSDS)?
The HSDS is a format for data exchange, specifically designed to enable the publication of machine-readable data about health, human, and social services that are available to people in need.
HSDS is essentially an interlingua — in other words, it’s a common language that can be used by anyone to enable community resource directories to ’talk’ to each other.
Why did we develop the HSDS?
We believe that development of an open, standardized format is a necessary step in a process of reducing the costs of producing directory data, increasing the quality of such data, and promoting its re-use in valuable ways.
We expect that adoption of HSDS will make it easier to find, use, and evaluate information about services. As a result, more people will access services and service providers will be better able to address complex needs; people will live happier and healthier lives; decision-makers will be better informed about the needs of their communities; and ultimately communities will become more resilient.
How did we develop the HSDS?
The Open Referral initiative used multiple methods of research and development to establish this data specification.
First, leaders of our pilot projects worked with stakeholders in their communities to develop a series of ‘user profiles’ that described the needs and behaviors of specific users.
Then, at our Open Referral workshop in the summer of 2014, we compiled a set of ‘user personas’ that each describe one of four broad categories of use: seeking help, providing help, analyzing data, and administering data. [Read here for the set of user personas developed through activities such as the Open Referral workshop.]
With this set of insights, we drafted an initial version of the specification that was then reviewed through several rounds of community feedback. During this time, members of our diverse network debated, clarified, and expanded the contents.
Finally, we conducted initial tests of HSDS by using it to transform resource directory databases from pilot projects around the country.
Who is the HSDS for?
The primary users of HSDS are data administrators (who are responsible for managing systems that strive to meet the needs of other users).
We define ‘data administrator’ broadly: while some data admins will be sophisticated managers of enterprise-grade referral systems, the vast majority of people who produce resource directory data are working with simpler technology such as Access, Excel, or even Word. Our goal is for HSDS to be usable by both the 2-1-1 resource data specialist and the IT volunteer who is helping out the neighborhood food pantry.
What’s in the HSDS?
First, HSDS identifies a vocabulary of terms that describe what a service is, the institution that provides it, where the service can be accessed, and how to access it. These terms are designated as ‘required,’ ‘recommended,’ and ‘optional.’ The spec provides instructions for formatting these terms, with examples.
On a more technical level, HSDS also includes a logical model that diagrams the relationships between these terms. Finally, HSDS provides guidance for structuring and packaging data so that it can be published on the web and/or exchanged between systems. [See: our documentation.]
What’s not in the HSDS?
HSDS does not attempt to describe every type of information that might be relevant to people working with resource directory data. We have attempted to maintain a strict focus on specifying only relevant factual attributes that are shared by most services. That means we excluded many kinds of information that are unique to specific kinds of services (such as the accreditation of child care providers, or the availability of beds in a shelter).
HSDS also does not specify a taxonomy of types of services and types of personal attributes that determine eligibility for various types of services. Many such taxonomies already exist, so HSDS merely provides instructions for how to overlay a taxonomy of the user’s choosing. By default, information systems that use HSDS and/or the Ohana API can use the open source Open Eligibility taxonomy. (Expect future cycles of the Open Referral initiative to take on these issues more directly; however, for now we are merely looking to learn from the different ways in which various users address these common problems.)
Finally, HSDS does not specify any information regarding how referrals actually get made (i.e. setting appointments, following up, etc) or as to feedback regarding the quality of those services. These kinds of information are critically important, but inherently so variable and context-dependent that we don’t think it’s feasible or appropriate to specify them at this point in time.
That said, this model can and should be extended! Users can expand HSDS to meet their own needs, in their own systems. Groups of stakeholders from particular subdomains can develop extended ‘profiles’ that are tailored to their situation. (A group of civil legal service providers have already begun working on precisely that.) In future iterations of the Open Referral process, these expansions will then be considered for inclusion as part of the primary model.
What is the format of HSDS?
With the goal of broad accessibility in mind, lead developer Sophia Parafina has chosen Comma-Separated Values (CSV) as the building blocks for HSDS. CSV serves as a ‘lowest common denominator’ that is simplest to use and most accessible to users with a modicum of technical abilities, as it can be edited in a simple text editor, and ingested by almost any information system. (For more reasoning behind this decision, consider Waldo Jaquith’s recent post, ‘In Praise of CSV.’)
Members of the Open Referral community have observed that they may need more structured data formats for use cases that involve complex, sensitive, and/or large-scale uses. We recognize the validity of these perspectives, and in fact we expect the HSDS model to evolve over time. Pilot projects and community members are already discussing plans to develop complementary formats (such as XML and JSON-LD) — and as these formats are field-tested and validated, they may become formal components of HSDS in future iterations.
How did all these decisions get made?
Our initial governance model was structured around three elements: 1) a semi-regular Assembly video call, open to all participants [see an archive of these videos here], 2) convenings of diverse stakeholders in our Open Referral workshop [read the reportback here], and 3) a ‘workgroup’ consisting of leaders with a varied set of perspectives and experiences [see the workgroup archive here].
This workgroup collaborated in the solicitation and synthesis of feedback, the articulation of various options, and the making of recommendations for both the technical specification and for the process itself. Of all the feedback received from many different contributors, we assigned priority to the perspectives of the lead stakeholders of our pilot projects. This feedback was submitted to the sponsors of the Open Referral initiative (the Ohana Project and Code for America), who ultimately made decisions.
[Open Referral’s initial governance model is described in more detail in this memo. You can also read more about the nature of this ‘polycentric’ approach to governance in Derek Coursen’s blog post here.]
Watch our final pre-1.0 conversation about HSDS here, or embedded below:
Deep appreciation is due to our workgroup members — Eric Jahn of Alexandria Consulting, Derek Coursen of NYU’s Wagner School of Informatics, Neil McKechnie of iCarol, and Hailey Pate, a public servant with experience in both the Code for Sacramento brigade and the national EMS data standard — thank you all for your service!
For future cycles, we have our work cut out for us. In the coming weeks, we’ll be sharing more detailed reflections and proposals for the next iteration of the Open Referral workgroup, which will directly address these issues of open source community governance. If this is something that interests you, please reach out because we’d like to work with you 🙂
What happens now?
Over the course of the coming year, our pilot projects will use HSDS to implement open data exchanges among different kinds of institutions in their communities. Through these field deployments, we’ll test many of the assumptions that have been made, and generate new insights about the needs of our various types of users.
During the course of this field-testing cycle, we don’t expect to make any significant changes to the specification. Beyond addressing minor bugs or usability issues, any proposals for significant structural changes will be held for consideration in a prospective version 2.0 (approximately a year from now). In the meantime, we’ll produce documentation and tools that can make it easier to use HSDS, while further developing our analytical framework and decision-making processes.
Along the way, we’ll form a new workgroup of leaders who will help steward the specification and articulate options for improving it. This workgroup will also consider various decision-making processes and pathways towards sustainability for our efforts. We are seeking nominations to this workgroup, especially from leaders of our pilot projects, and/or people who have on-the-ground experience with the use of community resource data. If you, or someone you trust, might make for a valuable workgroup member, we want to hear from you!
Meanwhile, our pilot projects are on the move. Currently, these primarily include the District of Columbia, the San Francisco Bay Area, Chicago Illinois, and Miami Florida. If you live and/or work in these areas and want to be involved, please reach out and we’ll connect you with local leadership.
Read more here about what makes up a pilot project. If you’re interested in implementing HSDS in your community, reach out to [email protected] discuss!
Thanks again to everyone who put time, energy, and critical thinking into the development of the data specification. Please share any questions, suggestions, and other feedback — either here in the blog post, in the Open Referral community group, or in the Open Referral Github repo.
Leave a Reply