Interoperability: Directories of health, human and social services

From Demand-Driven Open Data for HHS
Jump to: navigation, search


Resource directory information is what people need to know to access any kind of health, human, or social service (from mental health counseling to food pantries to job training programs). This data is laborious to maintain, and it is typically aggregated in fragmented and redundant silos.

As a result, it’s often difficult for people in need to know where to go to get help. It’s also difficult for service providers to address their clients’ complex needs. Finally, it’s difficult for researchers and decision-makers to understand how resources are currently allocated (and where there might be service gaps that adversely impact community health).

The publication of accurate, granular open data about services — specifically those provided by, or funded, the federal government — can make it easier for the many different kinds of referral mechanisms to deliver this information to people in need. This will improve service discovery and deliverability; save service providers and administrators time and energy; and create new possibilities for robust feedback collection, needs analysis, and program evaluation.

[Read more in this memo (Google Doc).]


The Open Referral Initiative has convened a diverse network of referral providers (from social workers to 2-1-1 call operators), civic technologists, software vendors, researchers, and more. This network has developed a data exchange format that is designed to establish interoperability among different kinds of resource directory information systems. By promoting such interoperability, we can make it easier to produce, find and use this information in various ways (whether via 2-1-1 telecenters, or web products like Purple Binder, or even simply Google).

Many resource directory datasets already exist on federal data catalogs, but they often lack relevant structured data. (For example, a dataset might have the name of an institution and the address of its facility, yet no description of the actual services that it provides, their hours of operation, application process and documents required, and other actionable information.) Open Referral’s Human Services Data Specification delineates a set of minimally-necessary, recommended, and optional data types that reflect the needs of a diverse cross-section of stakeholders in the field.


The AIRS XSD ( is an XML-based schema that delineates the relationships between information about agencies, the services they provide, and the services’ locations. The AIRS XSD is used by AIRS accredited referral providers (such as 2-1-1s, Aging and Disability Resource Centers, etc), as well as government agencies such as HUD.'s ‘civic services schema’ was proposed to the World Wide Web Consortium in 2013 and adopted by the W3C in 2014. The civic services schema is designed for publishing structured micro data about services for optimal indexing by web engines like Google, Bing, Yelp, Facebook, etc.

The Human Services Data Specification was published in March of 2015 by the Open Referral Initiative as a data exchange format. HSDS specifies sets of ‘required,’ ‘recommended,’ and ‘optional’ elements that were identified through multiple methods of research across various jurisdictions, domains, and user groups. This exchange format is designed to enable interoperability between heterogeneous resource directory information systems, whether they be AIRS-compliant I&R providers, web applications, or otherwise.


While help-seekers and service providers are the ‘end users’ of resource data, the primary users of raw resource data are *resource database administrators* (people who populate the directory information systems with resource data). Resource database administrators might serve formal, accredit referral providers (such as conventional 2-1-1 call centers, mobile platforms such as Crisis Text Line, or emerging vendors of web-based applications such as Purple Binder), or they may be maintaining ad hoc homegrown databases within community anchor institutions. In any case, they share a need for accurate, granular, and easily-’remixable’ resource directory data, so that they can more effectively refer their users to services that can meet those clients' needs.

At a minimum, end users need to know the name of an organization, a description of the services that it provides, the location(s) at which these services can be accessed.

We also strongly recommend that datasets also include the schedule of the services (with designated fields for holiday schedules), description of the service’s accessibility for people with disabilities, the application process to access the service, the eligibility requirements for the service, any fees associated with the service, interpretation services available in tandem with the service, transportation options available for the location, and any contact information relevant to the service, organization, and/or location.

These resource data administrators want the data elements above to be properly serialized, so that data about contact information, locations, etc can be properly associated with organizations, the services they provide, and/or the locations at which they are accessed. For the purpose of clarity around service provision, we also recommend the inclusion of a name and description of the program with which a service is associated.

Resource data admins will also benefit from metadata about the resource data — including its provenance, the date and type of last actions, the previous value and replacement value. Furthermore users will want the ability to ‘flag’ information that is found to be out-of-date or otherwise incorrect. Finally, assigning unique identifiers (i.e. UUIDs) to each service is a tremendously valuable role that the government is ideally positioned to play.

Additional types of information — valuable yet not always necessary — along with formatting guidelines, and a logical model, can be found in the Human Service Data Specification’s documentation.

Specific user stories for people seeking services and the service providers who help them include: Crisis Text Line's table of user stories