Frequently Asked Questions


What’s the problem?

Every community faces a similar challenge: there are many different kinds of health, human, and social services that are available to people in need, yet no one way that information about them is produced and shared. Instead, many organizations independently collect community resource directory data, each structuring it in different ways — yielding redundant, fragmented silos.

As a result, it’s hard to ‘see’ all the many different parts of our safety net. Many people never discover services that could help improve their lives. Service providers spend precious time verifying data rather than helping people. And without access to this information, decision-makers struggle to evaluate community health and program effectiveness. This yields underperforming systems that fail people and communities in tragic ways.

What can we do about it?

Broadly speaking, we are currently in the midst of a technological and cultural shift towards open platforms and open data. This shift makes it easier for more people to produce and use data in new ways; to develop and redeploy new technologies at lower cost; and generally to increase the value of data, and the strengths of the networks and communities that use it.

More specifically, a tremendous opportunity recently emerged for this particular field of community resource directory data: in 2013, Schema.org proposed a ‘civic services’ schema to the World Wide Web Consortium (the W3C). This schema represents an emerging standard that can enable community resource data to be read and delivered in new ways by search engines like Google, Yahoo, Yelp, etc.

Given this opportunity to make it easier for data on civic and social services to be discovered on the web, we have a mandate to bring governments, funders, civic institutions, and technologists together around a shared goal: let’s make it as easy as possible to publish, find, trust, and use this information. That entails the establishment of interoperability between the language of the web and the field of information-and-referral systems, and the discovery of new means to sustain the production of this data as an open resource.


What do we mean by ‘open data’?

‘Open data’ is a popular term right now. It’s also ambiguous. What does it mean?

Open means ‘free,’ as in ‘free speech.’ We are all entitled to it by fundamental right.

Open means accessible. We have “open access” to things like roads and libraries — these are public goods, and anyone should be able to use them. Likewise for our computer technology: open data can be accessed not just by users of one system, but by users of an open set of systems.

Open does NOT necessarily mean ‘anything goes.’ You’ve gotta return books to the library, and in good condition too. Even on open roads, there are speed limits, and eventually there are tolls, plus construction and cleanup crews, etc. You can’t yell ‘fire’ in a crowded theater. Etc.

Open does NOT necessarily mean ‘free’ as in ‘free beer.’ For something to exist in an open state, a lot of energy and resources must go into keeping it so. Those resources must come from somewhere (and we don’t assume they will automagically crowdsource themselves).


Open data can mean many things, but at its core, open data entails:

Availability: open data must be available as a whole, presumably downloadable over the internet. The data must also be available in a convenient and modifiable form. (There can be reasonable reproduction costs associated with certain kinds of access to open data.)

Reuse and Redistribution: open data must be provided under terms that permit reuse and redistribution, including the intermixing with other datasets. There should be no discrimination against fields of endeavor or against persons or groups. The data must be machine-readable. The data can be licensed to prevent changes, and/or to ensure clear documentation of changes.


Openness entails a state of possibility.

By making data available for anyone to re-use it in new ways, we can dramatically increase its potential value.

We assert this as a given: the production of open community resource data can, will, and should happen, one way or another.

We also assert that such production should occur in such a way that its costs are sustainably carried into the future; and furthermore that the means of production should be accessible to and shaped by local stakeholders. This is, after all, data about their community’s resources.

For the purposes of Open Referral, the concept of ‘open data’ is itself open to some degree of interpretation. Essentially, we are asking: how should this data be open? (If it is to be published in bulk for free, can premium real-time access via API require a fee? If the market won’t fully cover costs of its production in this way, should the government be expected to subsidize its production, in order to ensure access and quality? Etc.)

What do we mean by ‘referral’?

Broadly speaking, people seek ‘referrals’ to resources that can help them meet their needs. Community resource data connects people to health, human, and social services from which they can receive assistance.

Some services are provided by non-profit organizations, and other civic or cultural groups. Others are provided by local, state, even federal governments. All of these entities share information about their resources in different ways.

‘Information and referral’ refers to the field in which information about services is aggregated in community resource directories, and delivered (via referral) to people seeking help.

The Alliance of Information and Referral Systems (AIRS) is an accrediting agency that certifies ‘information and referral’ providers throughout North America. AIRS promotes official standards for ‘information and referral’ services, ranging from operational standards to data standards. AIRS has consulted with the Open Referral Initiative from its inception, and members of AIRS are active in our community and working process.

What do we mean by ‘standards’?

By standards, we refer to common ways of doing things. In the case of data standards, that means an agreed-upon set of terms and relationships that define and structure information, so that it can be readily transferred between systems.

With such common agreements, it can become ever easier to leverage existing resources and technology, and to develop and adapt new technologies at lower cost and broader possible use.

Standardizing data across places and institutions also makes it easier to analyze and evaluate data, which makes it easier to understand the health of communities and the effectiveness of programs.

Furthermore, the process of developing standards helps to bring stakeholders together. By building a community among users, producers, and service providers, we can accelerate the process of learning and innovation towards our shared vision of helping people and improving the health of communities.

What do we mean by ‘open platforms’? What’s an API?

A platform is a broad term that could mean a lot of different things — here we use ‘platform’ to refer to a system that makes its data available both to users and to external systems (which can be ‘built upon’ the platform).

For example, you can get a forecast from the National Weather Service by going to Weather.Gov. But the NWS also offers ‘a web service,’ otherwise known as an ‘Application Programming Interface’, or API. An API enables the data in one information system to be automatically accessible by other information systems. The NWS API enables developers to build applications that connect to the Weather.gov ‘platform’ in order to seamlessly provide public weather data to skiiers, photographers, rainbow chasers, etc.

Platforms enable their data to be accessed and used in all kinds of ways, many of which could not be provided by those who operate the platform themselves.

By ‘open platform,’ we specifically mean three things:

  • An open platform enables its data to be both accessed directly by users and also published in open formats
  • An open platform is powered by technology that is freely available through open licenses
  • An open platform is a system in which interoperability and integration are the primary design objectives


Why are open data standards and open platforms important?

With increasing adoption of open platforms sharing a standard format, we anticipate:

Decreased cost of data production (as data produced once can circulate through many systems)

Improved quality of data (as more use generates more user feedback)

Improved findability of data through web search and an ecosystem of tools and applications; Decreased cost and improved quality of new and redeployed tools (websites, applications, etc).

Improved quality of referral services (as patterns of resource allocation shift from maintaining data to delivering data)

Meaningful use of resource data for research purposes, such as community health assessment, and policy-making and resource allocation.

Healthier people and more resilient communities.

Can’t you just get organizations to update their information themselves?

While various systems (including the Ohana API) do enable organizations to submit updates for their own information, there are a number of factors that limit the effectiveness of organizations as reliable sources of information about their own services.

Organizations might not designate the responsibility for managing all of this information to any single person. A single organization might offer many services through various programs at multiple locations. And these are often stressed environments with limited technical capacity and overburdened staff.  It can be hard for organizations to keep track of all of their own services!

Organizations sometimes submit information about services that is vague or not entirely accurate. When updating their own records, organizations’ staff sometimes submit information that is composed to promote their organization in general, yet not precisely describe the information about services that is needed. This tends to yield information that is not useful to someone who is looking for a service.

Organizations are asked to update their information so many times in so many different community resource directories that they get confused or frustrated.

Keeping this information up to date just isn’t a high priority when organizations already have more clients coming through its doors than they can handle.

As a result, we assume that organizations’ self-reported updates should be considered one input among many in the effort to produce and maintain accurate data about services.

Why don’t government or funders require this data as a condition of funding?

Government and funders do require various kinds of data about their grantees, but it’s generally non-standardized and not specifically about services themselves.

We anticipate that, as a standard format becomes adopted and demonstrates value, governments and funders may begin mandating this information as a condition of funding. (But it doesn’t seem feasible to attempt to make that happen before a format has been demonstrated as viable and gaining adoption!)


About Open Referral

How is the Open Referral process being developed and reviewed? What is the role of the ‘Chief Organizing Officer’?

The Open Referral Initiative is an open source undertaking, which means that documentation and artifacts are freely accessible and adaptable by participants.

We approach this challenge in an agile way. Rather than try to figure everything out up front, we are instead working with stakeholders to identify specific steps that are worth taking in and of themselves that incrementally move us in the direction we want to go. We’ll do some things, learn from them, and do more things.

Through this process, we synthesize input and coordinate participation from a wide variety of participants; we give prerogative to the priorities expressed by our primary stakeholders (those who represent different types of end users: help seekers, service providers, researchers, and data administrators).

You can see our proposal for our governance model here. You can see our proposal for the process and structure of our Pilot Projects here.

Our Community Forum is the primary site of updates and occasional discussion. We also host regular Assemblies (see archived videochats here) and convene in semi-formal workshops.

The Chief Organizing Officer has the prerogative to set the Initiative’s tone and agenda, make proposals, promote voices, broker agreements and encourage creative solutions. It is essentially a facilitative position.

Shouldn’t we have a Yelp for Social Services? Why aren’t you trying to build that?

Lots of people are trying to build Yelp-type applications for social services. That’s not Open Referral’s role. There’s a range of reasons why:

First, information about human services is a lot more complex, variable, and sensitive than restaurant data – and unlike restaurateurs, many human service providers might not see the benefit of being listed in a Yelp for Social Services. This is a problem that simply doesn’t correspond with conventional supply-and-demand market dynamics that make Yelp possible.

Second, we want this information available in many channels and applications – including Yelp itself! Plus Google Places and Facebook! Yet even these wouldn’t meet the needs of every user in every situation. Resource directory data should be itself a public good, freely ‘remixable’ by anyone, not trapped within one company’s interface.

There are a range of other reasons why we don’t think this problem has one simple ‘Yelp for Social Services’ answer. Check out this talk for more insights, and email info@openreferral.org to discuss further.

How are decisions being made?

Inasmuch as this is an open source initiative, a simple rule of thumb is rough consensus and running code.

That said, because this is a complex problem (involving private and public sectors; spanning local, state, and federal boundaries, with many layers of technology that are rapidly changing) our approach to discovering solutions should also be complex. So the Open Referral Initiative entails various levels at which different kinds of decisions are being made by different kinds of participants. One way to describe this is ‘polycentricity’read more about what we mean by that here.

At its simplest, our structure includes two levels: 1) ‘pilot projects’ in which local stakeholders work together to answer the question of ‘How can we build a future in which community resource directory data is accessible, interoperable, reliable, and sustainably produced?’ and 2) a ‘Working Group’ that stewards the development of the Open Referral format that is used by the pilots, along with associated tools and materials, and the process itself.

(Each of these is more complex upon examination: the San Francisco Bay pilot has multiple county-level groups working semi-autonomously; we also have subdomain-specific working groups for particular kinds of services like legal services.)

These two levels intersect in three ways: in our Community forum, during regular Assemblies (video chats open to all participants — see an archive here), and during our semi-formal Workshops (multi-day in-person convenings — see this 2014 reportback here).

You can read more about the pilot projects here, and the working group and its governance process here. These proposals are subject to change (read here for changes made in the first cycle), as in the course of each development cycle they will be reviewed by the Working Group and interested members of the community, and subject to revision.


Who is funding the Open Referral Initiative?

There there are a number of different projects weaved together through the Open Referral Initiative — each with shared goals, but different funding sources.

The primary source of funding for the initial pilot phase was from the Knight Foundation.

In 2013, Code for America’s San Mateo fellowship formed the Ohana Project, which is an open resource directory platform that the San Mateo fellows produced for San Mateo’s Human Services Agency. (This 2013 fellowship was co-sponsored by the Philanthropic Ventures Foundation. The Ohana project was subsequently contracted for an additional year of development by San Mateo HSA.) Later that year, Ohana won the Knight Foundation’s Health Data Challenge. This Health Data Challenge funding supported the Ohana team’s work for one year, as they a) redeveloped their code into an open source directory platform which can be freely re-deployed by other communities, and b) participate in the Open Referral initiative, which will generate essential feedback to guide their redevelopment.

The Open Referral Initiative itself has been directly co-sponsored by the Ohana Project and Code for America. That co-sponsorship essentially funds the work of the ‘Chief Organizing Officer’ of Open Referral for this year.

The initiative has also raised funding for our local teams, primarily from local funders (in California, this includes Serving California, the Kapor Center, and the California Health Care Foundation; in DC, so far our funding has come from private donors).

Finally, in each of our pilot localities, we are supporting our lead stakeholders (i.e., health clinics, local I&Rs, etc) in their own fundraising efforts to build their internal capacity to participate in the project.

Email info@openreferral.org for more details.


What is the difference between Ohana and Open Referral? What is Open211?

Open Referral is both the name of this community of practice, and also the shorthand name of our format for community resource data (which is technically known as the Human Services Data Specification).

Ohana is both the name of the Code for America fellowship team that developed a ‘first draft’ of this model, and also the name of an API (Application Programming Interface) that the Ohana team developed in San Mateo county. The Ohana API was subsequently redeveloped by the Ohana team, based on feedback from the Open Referral community, to serve as a ‘reference implementation’ of the Open Referral model. [See the Ohana API on Github here.]

Open211 is a name that has been used by various groups and organizations over the years. 2-1-1 Ontario has an ‘Open211’ API (the first of its kind, to our knowledge). In 2011, a Code for America fellowship team built an Open211 app (it did not achieve adoption, but we learned valuable lessons from it). One of the first pilot projects for Open Referral is a group of organizations and technologists in DC who describe themselves as ‘DC Open211.’ But it is more of a concept than a formal affiliation.


Is Ohana or Open Referral trying to build a national database?

Nope. We recognize that this is a local problem that should entail local solutions. That’s why we’re trying to develop a viable standard that can support local communities as they seek such solutions.

Are you ‘scraping’ data?

No. The Ohana project is primarily working with data provided by the San Mateo County Human Services Agency, and developing open source software for other communities. The Open Referral initiative is working with data freely contributed by its stakeholders, which includes 2-1-1 systems across the country.

However, we also don’t find validity in claims that community resource data should be treated like private property. It is public information, and organizations that do business with it should be sustaining themselves through services that add value to it, rather than by trading it as a commodity.

We do recognize that there are some community resource directory projects out there that are scraping 2-1-1s data. (Some of these projects are non-profit, or all-volunteer, or even for-profit.) Scraping this data from websites is usually technically easy, and it’s more or less legally okay too.

We disapprove of this, mostly because it makes it harder to have constructive conversations about the real problem — which is that this data is not currently “open” for machine-readable re-use.

We also believe that if community resource directory data were openly accessible in a machine-readable format, ‘scraping’ would be pointless. Instead, people would use such data from its source, in ways that could presumably benefit the source.

That may at first seem counter-intuitive. But there are business models for open data — and we believe that information-and-referral providers will benefit by discovering and adopting them. Meanwhile, we have not seen any viable long-term strategies involving the production of resource data that is not open.


If you’re going to build a new system, who will maintain the data?

This is the ultimate question! Finding answers to it is actually our primary objective.

Please note that Open Referral is not developing one particular product.

Rather than building one new system that we try to get everyone to use, Open Referral’s objective is to enable systems (both pre-existing and emerging) to talk to each other. In other words, our stakeholders are the organizations and people who already spend resources maintaining resource data.

In the long term , our work is about making it possible to find new answers to this question. However, in the short term, our question is ‘who is currently maintaining resource directory data, and how can we help them?’

Aren’t calling centers important for people who might not use a computer, etc?

Of course they are!

We think it’s important for this information to be accessible to a whole ecosystem of services, and for the foreseeable future, calling centers will be an essential component of a healthy ecosystem. That’s why it’s important for us to develop standards and open that can be shared throughout that ecosystem, so that there are a variety of ways to meet people’s needs.

Aren’t there already standards for service directory information?

There are existing standards among certified information-and-referral systems, but these are not designed for the open exchange of data among any system.

As a result, various organizations and institutions must all independently invest in data production and technology development. This entails many missed opportunities to share infrastructure, reuse code and data, and achieve substantial cost savings.

That said, the work of developing a ‘universal data exchange schema’ does not entail starting from scratch. Rather, it entails aligning with that which already exists.

For the first phase of Open Referral, we have identified a core set of existing standards with which our format (technically known as the Human Services Data Specification) aim to be interoperable (i.e. data can be coherently translated between these formats).

Specifically, these include:

What about the issue of taxonomy?

Open Referral recognizes the existence of a diverse array of taxonomies that are used to describe types of services, organizations, and people for whom services are available. Given that such categories are inherently subjective, whereas Open Referral’s format is describing only factual data, we do not prescribe a specific taxonomy. Instead, our data format specifies a way to include any taxonomy in open data, and our API protocols offer methods for supporting multiple taxonomies for use in the same data set.

Several prominent taxonomies are prohibited from public use by intellectual property claims. This poses barriers to the accessibility of community resource data. We are committed to seek solutions that can sustainably and responsibly remove barriers to the widespread use of these important classification tools.

What makes you think you know the right solution?

Well, we don’t yet know the right solution! We’re just not going to wait around any longer for it to be figured out. This is a wicked problem that requires a lot of different people working together to learn about possible solutions. So we’re taking action.

There is one thing we do believe: the best solutions to social problems tend to emerge from the insight and creativity of those who directly experience those problems. So our prerogative is to promote the perspectives and involvement of the true stakeholders — people who have experience seeking help from services, service providers themselves, data administrators at community-based organizations, community health researchers, etc. They’re the ones who will be best able to recognize what viable solutions really look like.

As we say elsewhere in this document: “For the purposes of Open Referral, the concept of ‘open data’ is itself open to some degree of interpretation. Essentially, we are asking: how should this data be open?”


Who are the Open Referral Initiative’s ‘users’?

We’ve identified four primary types of use that are relevant to this domain. Read more here for full personas and user stories.

  • Seeking help (service users, clients, etc)
  • Providing help (service providers, i.e. anyone helping someone find information about services)
  • Administering data (anyone engaged in working with community resource data and the technical systems that use it)
  • Research (anyone trying to analyze resource data to better understand the allocation of resources in a community).

Through these distinct perspectives, we set the parameters of our research, design, and evaluation. Our format (and the associated tools) should meet all of their needs.

Obviously, ‘help seekers’ are the ultimate stakeholders, and we should consider our work first and foremost from their perspective. Aside from this premise, we do not prioritize one stakeholder’s needs above another.

However, we do have a particular tactical analysis that guides our work:

We believe that the most immediate and urgent objective is to improve the ability for all kinds of service providers to make effective referrals with accurate information. One of our core hypotheses is that if/when an ‘open system’ meets the needs of the service providers in its community, those service providers will play a critical role in maintaining the accuracy of its information.

Yet we also recognize that an increasingly common ‘use case’ is an individual searching the web themselves. Surely we want more of those self-performed searches to be effective. So, an open platform must achieve sustainability such that its information is readily findable through direct web searches.

(Of course, even given success on both of those counts, we still assume there would remain a need for trained referral specialists — especially for complex situations, edge cases, etc.)

Finally, when it comes to actually adopting and using open data standards and platforms, we recognize that the most operational type of use is data administration. In other words, our format and tools must be readily usable by anyone who updates this information and manages the technology that stores and delivers it.

As adoption of open data standards makes it easier to solve the problems of maintaining resource directory information, we anticipate that it will become a lot easier for the many different types of service providers to allocate their resources as effectively as possible toward delivering and acting upon this information.

What is a pilot project?

Open Referral is led by local pilot projects in which stakeholders take action towards establishing accessible, interoperable and reliable community resource directory data.  Pilots commit to using the Open Referral data model to exchange resource directory data among institutions — and in return, their feedback is prioritized in shaping the iteration of that model. The goals of pilot projects include demonstrating short-term value of standardized/open data exchange, while developing a plan for long-term sustainability. [Learn more.]


How can my community become a pilot project?

The formation of a pilot project probably starts with a champion who has credibility in the community and the drive to convene others around an effort to solve this problem. We expect this champion to emerge from either local government, a community anchor institution or a local referral provider.

A fully-formed pilot project should include some combination of government, community anchor, and referral provider. It should have investment, and ideally active engagement, from local funding institutions that invest in safety net services. And a pilot should establish capacity for coordination that stands among these different institutional stakeholders — enabling each organization to identify and address its own needs, while facilitating a conversation about the collective interests in the community.

Interested in getting started in your community? Reach out to info@openreferral.org

How can I help?

This is an open source initiative, by which we mean that anyone can freely participate in it and even adapt any of our content for their own purposes. There are lots of ways that you might be able to get involved. For example…

Programmers, data scientists, and other technical people…

Check out the Github repos for the Open Referral format and the Ohana API; read through our project documentation. Ask questions — if we don’t know the answers, help us figure them out!

If you live in the area of one of our pilot projects, you can be very helpful indeed. If you don’t live nearby a pilot project, you might be able to help start one yourself. Attend a local Code for America brigade, or some other civic technology network activity, and ask around to see if anyone else is already working on projects involving resource data.

Information-and-referral practitioners…

Read through our data specification, ask any questions that come to mind — and if we don’t know the answers, help us figure them out. Make suggestions for ways to improve the spec.

Even more importantly, identify your own needs: what do you want to see happen? In a world where community resource directory data could flow among systems, where would you want to see if flow? It can be quite valuable to simply scope out an actionable ‘use case’ (some specific action that would benefit some specific set of users).

“I work in health, human, and/or social services.”

You may be one of our most important kinds of participants. Our work only succeeds if it can help you better serve your clients. You can help us identify, scope, and implement a ‘use case,’ in which we facilitate an open data exchange that can improve the deliverability of your services and/or services in your community. Help us get there.

“I don’t code, I’m just a citizen and I want to help!”

There is LOTS of work to be done by people who don’t code! First, read through our documentation, and ask us questions about anything that’s unclear. Then, for example, you might start learning about how information about services gets collected in your community. Talk to the people who are already producing resource directories; see if they’re interested in finding new ways to produce and/or use this information. If so, write a summary of how they do their work and what they say that they need.

NOTE: The most significant way to help may be to find people who have some of the above experiences, and start talking with each other. Together, you might be able to form a team in your community consisting of some combination of civic technologists, service providers, with support from local government and/or funders. If that looks like it’s happening, we will help you launch a pilot Open Referral project! Contact info@openreferral.org for more information.


About the Human Service Data Specification

What is the Human Service Data Specification (HSDS)?

AKA ‘the Open Referral format,’ the HSDS is a data interchange format that enables resource directory data to be published in bulk for use by many systems. HSDS provides a common vocabulary for information about services, the organizations that provide them, and the locations where they can be accessed. 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.
[See the data specification in Github or on our Documentation Site.]

Why did we develop the Human Services Data Specification?

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). [Read our user personas here.]

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 is 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: Github or our documentation site.]

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 the HSDS? Why CSV?

With the goal of broad accessibility in mind, the initial HSDS developer Sophia Parafina chose 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.’)

For version 1.0, Parafina chose to accompany a more-complex set of CSV files with a JSON datapackage (using the Open Knowledge Foundation’s frictionless data specification) to describe the CSVs’ contents.

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 are decisions made about HSDS?

Our governance model is structured around three activities: 1) a semi-regular Assembly video call, open to all participants [see an archive of these videos here], 2) convenings of diverse stakeholders in Open Referral workshops [read the reportback here], and 3) ad hoc ‘workgroups’ consisting of leaders with a varied set of perspectives and experiences [see the workgroup archive here].

Of all the feedback received from many different contributors, we assign priority to the perspectives of the lead stakeholders of our pilot projects. This feedback is submitted to Open Referral’s deputized technical leads, who ultimately make decisions with documentation and established methods for future review.

[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:

Version 1.1 of the Human Services Data Specification was stewarded by the Open Data Services Cooperative, and published in April 2017.

If this is something that interests you, please reach out because we’d like to work with you 🙂