Skip to content
Switch branches/tags
Go to file
Cannot retrieve contributors at this time

Contributing to Open Referral

Welcome! Thanks for your interest in contributing to the Open Referral initiative’s projects. We are a community of practice dedicated to promoting open access to community resource directory data — and we depend on people like you to make this work.

You can get involved by:

  • Using the Human Service Data Specification as part of a tool or service that you are creating — and/or, writing an API and/or export feature so that you can publish your resource directory data into the HSDS format for others to use (see README for more detail);
  • Building on one of the existing community developed tools, such as the Ohana API;
  • Opening issues or creating pull requests to suggest improvements to the Human Services Data Specification or documentation;
  • Joining the community forum google group here or our Slack Team (invites on request) and/or reach out to chat directly! Drop a line to community co-ordinator Greg at

The legal bit

The Human Service Data Specification and documentation are licensed under a Creative Commons Attribution Share-Alike 4.0 license.

This means that:

  • If you adapt and build on HSDS or its documentation, we ask you to share your improvements back with the community under the same license;
  • When you are making contributions to the project that might contain intellectual property, we need you to get in touch to sign a contributor agreement that gives us permission to distribute your contributions as part of Open Referral

In detail: how to suggest a change or addition to our data specification or code

If you find yourself wishing for a feature that doesn't exist in the Human Service Data Specification, you are probably not alone. There are so many different needs shared by and in this early stage we’ve tried to keep things simple by only specifying the most important elements that are most commonly shared across our stakeholders’ systems. There is much more work yet to do.

Read through our documentation, and if there’s something you would like to clarify or add, open an issue in our issues queue that describes the feature you would like to see, why you need it, and how it should work.

Once filed in our queue, the issue will get discussed; as a community we will look to find ways to improve HSDS and the documentation to respond to it.

It may be a while before we revisit the spec to update it to the next version. Yet we encourage you to share your feedback, as it helps us set the agenda.

In the meantime, we encourage users to extend the spec for their own purposes — document what you’ve done, and share how it goes with us!

How a contribution gets accepted after it’s been submitted.

Changes to documentation — in particular, changes that don’t change the meaning of the data specification — are made on a rolling basis.

The HSDS specification itself is versioned through a semi-regular ‘request for comment’ process that solicits feedback and discussion of issues in advance of any official updates.