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!

3 thoughts on “Upgrade: the Human Services Data Specification version 1.1

Leave a Reply

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