Upgrade: the Human Services Data Specification version 1.1

by Tim Davies of the Open Data Services Cooperative

After two years of testing, feedback, and deliberation across the Open Referral initiative, we’ve just upgraded the Human Services Data Specification to version 1.1.

Check HSDS v1.1 out here. If you have questions or feedback, you can comment there directly on the site or discuss the changes in our Github issue tracker; you can also join the conversation in the Open Referral Google Group.

For this upgrade, the Open Data Services Cooperative worked primarily in tandem with the Miami Open211 project. Miami served as our key pilot site, in which we tested version 1.0 and staged our improvements for v1.1. We also facilitated a series of conversations with participants across the Open Referral initiative (see video recordings here and here), and solicited feedback from the 1.0 release earlier this year, to identify modifications that would improve the usability and fidelity of the HSDS.

In Version 1.1, we’ve clarified some of the complexity in the relationships between organizations, the services that they provide, and the locations at which those services are accessed. HSDS v1.1 also reflects updates in the datapackage specification that we use to bundle the data in a machine-readable tabular file. Alongside schema updates, we have updated the HSDS documentation, and provided a revised sample data package to guide adopters.

A complete changelog of updates to the schema is available here.

Some of the key updates include:

(1) A clarification to the HSDS logical model, making clear the relationship between various elements, including more specific instructions about how users should interpret the foreign keys that link the various tables that make up a HSDS package. Among other changes, we’ve ensured that services and locations are linked by a ‘service-at-location’ table, removing ambiguity about this relationship.

(2) We’ve improved the validation of URIs and e-mail addresses.

(3) We’ve added clearer support for taxonomies, with a table specifically for service classification schema.

(4) We’ve brought a number of additional fields to the schema from the vocabulary, so that the schema now allows services to be associated with representation of fees, interpretation options, accreditations and licenses.


We’ve also discussed a set of issues that won’t be addressed in this fix, but are on our roadmap for the next iteration.

First, the issue of specifying detailed ‘service area’ Information’. It is clear that there is a need to accurately represent the geographic region served by a service, but we did not reach a firm consensus on whether HSDS should specify a particular geographic taxonomy or pattern for describing geographies, or whether this decision should be left to individual implementers. However, our discussions did move us towards a clear understanding of two use-cases that should be addressed: disambiguation (e.g. Manchester, NH, USA vs. Manchester, UK), and containment (e.g. a service only available in the Emeryville part of postcode 94608). We’ve provided instructions for dealing with each, and encourage implementers to test various methods with the possibility of making proposals for a more specific decision in version 2.0

Also, while we have improved the ability to align taxonomic metadata with HSDS-formatted data, we have stopped short of proposing use of common taxonomies. This is an issue that may be addressed more directly in version 2.0

This release of HSDS also clarifies the relationship of HSDS and Ohana. Although HSDS and Ohana developed in parallel, HSDS has a broader audience of implementers, and does not enforce some of the restrictions baked into the current Ohana implementation. We’ve documented the differences that may require data transformation before HSDS can be imported into Ohana platforms, and have shared draft transformation scripts (developed through the Miami Open 211 pilot) to support this conversation.

There are also a number of open issues about aligning with some recent changes in the data package specification, and the need to continue to explore mapping against other specifications.


The next chapter of development for the HSDS will be picked up through the OpenAPI specification project, under the leadership of Kin Lane, who will use our work on the schema as a reference point in the development of standardized API protocols. We at the Open Data Services Cooperative will continue to advise this process and field proposals for minor tweaks that may be relevant to the schema itself.

Many thanks to all those who participated in this process along the way, including: Joaquin Infante, Grace Morales, Marcella Cruz, and Melquiades Jorge at Miami’s 2-1-1; Katherine Lambacher of CIOC; Neil McKechnie of iCarol; Moncef Belyamani of the Ohana Project; Dan Fowler of Open Knowledge International; David Santucci of Gnaritas; and many others!


4 responses to “Upgrade: the Human Services Data Specification version 1.1”

  1. […] resource directory data into ‘open data’ (usable by anyone, in any system) via the Human Services Data Specification.* We then deployed this open data into an instance of Ohana, Code for America’s open source […]

  2. […] technology to help resource directory providers share data through interoperability, including both improvements of the Human Service Data Specification (our resource directory data exchange schema) and the introduction of the Human Service Data API […]

  3. […] been several years since we upgraded HSDS to version 1.1, and in that time HSDS 1.1 been implemented in a wide variety of contexts for a range of use cases. […]

  4. […] where HSDS 1.1 ended up (more on that here), our OpenAPI specification is informed by a range of actual API implementations from across the […]

Leave a Reply

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