Upgrading our specifications: A proposal for HSDS 2.0

[UPDATE: the proposed upgrade has been approved! Review notes from our Assembly call here, and see video for the call here, and embedded at the bottom of this post.]

We’re excited to share an approved upgrade to the Human Services Data Specification, authored by our technical partners, the Open Data Services Cooperative.

Take a look at the new version in our Github repository, and see the complete changelog here.

We still want to hear from you! You can leave comments in the Issues queue – or on our documentation site, where you can also comment by first creating an account on hypothes.is (a website annotation service) and then sharing your feedback directly on the web pages.

Below, we provide more context on the primary changes that have now been approved.

It’s 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. These implementations have provided valuable feedback, and generated a range of proposals for new features. This upgrade will not address every single issue that has been raised; we’ve merely prioritized a set of specific needs that have emerged as common across implementations – especially those issues that are important in this particular moment of heightened urgency and instability caused by the pandemic and economic crisis.

The primary sets of proposed changes fall under three issue areas:

See the history of discussion about each of these issues at the links above, and read more detail about our proposed methodology in the section below.

Taxonomies and other categorical schema

Classification (i.e. sorting types of services, and sometimes people, into distinct categories) is a major challenge in the process of resource referral. On one hand, it’s important to be precise in categorization of services in this vast and diverse landscape — as such precision helps facilitate both complex service delivery as well as research, analysis, and evaluation. On the other hand, specifically-delineated categories can seem like unintelligible jargon for regular users (i.e. “behavioral health counseling outpatient treatment” versus “addiction therapy”). Given this challenge, among others, we recognize the legitimacy of many different taxonomies that exist in the world, often overlapping each other even while having distinct purposes, and we do not prescribe any particular taxonomy as a formal part of HSDS.

In HSDS v2.0, we are proposing a more specific process of including any service taxonomy – and other relevant sets of types of things – as a component of standardized open resource data. The new proposal is outlined here.

This approach supports either ’embedded’ taxonomies (included within the dataset) or ‘external’ taxonomies (in which taxonomy codes are linked to external sources of categorical data).

The proposal also enables categorical schema to be applied to other elements (like Locations, Organizations, Access Methods, Eligibility criteria) as discussed in this thread. We designed this proposal to ensure that communities can have flexibility in categorizing their resource data, and more to the point, can work together in situations when multiple vocabularies might need to be applied to the same resource data for use in different contexts.


We’ve heard often that people struggle to represent information about resources that don’t have a regular weekly schedule. In some cases events might happen monthly or bimonthly (i.e. the first Thursday of the month, etc) and in other cases events might only happen once or a few times at all. In this proposal, we’re adopting a set of conventions already established by iCal’s RRULE, an existing data standard for scheduling information.

This upgrade will make it possible to describe:

  • A service that opens and closes multiple times per day
  • A service whose provision is relative to the start or end of the month (eg “first Friday”)
  • A service that’s only provided for a fixed period of time (eg over winter)
  • And many other combinations.

Custom fields and adaptive application

HSDS has a small number of required fields, and a much larger set of fields that are recommender or optional – but we haven’t (and, indeed, couldn’t have) specified every possible type of information that people might need to find and use any given resource. We encourage communities to use HSDS as a tool that establishes a baseline set of agreed-upon terms, and to build upon that baseline.

In HSDS 2.0, we provide specific guidance for how implementers can establish customized fields – by documenting specific types of information that have been created for their own purpose. This approach also encourages our community to document such emergent patterns, to facilitate ongoing interoperability while informing the future development of the spec. (Today’s custom fields may become next year’s formal addition to HSDS 2.1 or 3.0.)

We’ve also provided a framework for creating ‘simplified’ implementations of HSDS that convert the many-tables approach of the core standard into a many-columns approach that’s more applicable for use cases where there’s extensive manual data entry


HSDS 2.0 also put forth some minor bug fixes that aren’t substantive enough to outline here, but we encourage anyone interested in more details to review the documentation and our Github threads. And please join us in our Google group or Slack channel to discuss.

Our thanks to the Local Government Association, Porism, and the UK Ministry of Housing and Local Government, for the encouragement and resources that make this upgrade cycle possible.

Here is the video recording of our call to approve these changes:


2 responses to “Upgrading our specifications: A proposal for HSDS 2.0”

  1. […] the highlights: we’ve upgraded our resource data standards; supported a range of pilot projects that are developing new methods of collecting, exchanging, and […]

  2. […] that the Open Referral Initiative has upgraded to version 2 of the Human Service Data Specification (HSDS), we’re commencing a subsequent upgrade to version 2 of our Human Service Data API protocols […]

Leave a Reply

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