Overview and Model

The Human Services Data Specification (HSDS; sometimes referred to as “The Open Referral format”) is an exchange format for publishing machine-readable data about health, human, and social services: their locations, and the organizations that provide them. We define “human services” broadly, to include any organizational resource that is made available for a person in need – such as food assistance, job training, child care, etc.

The primary use case served by HSDS is the provision of human service directory information as “open data,” to be consumed by any third-party information system.

Government entities, community organizations, and people often face difficulty obtaining timely and correct data about human services. The Human Services Data Specification facilitates the open exchange and use of human service data (often known as “community resource data”) among these stakeholders. To that end, this is an interchange format designed to complement – not replace – existing storage formats currently in use.

All organizations that provide services or referrals to services, as well as entities that distribute digital human service directory information, are invited to publish their data in this format, whether they be governments at the local, regional, or national level; civic organizations; software developers; etc.

HSDS’ Model

HSDS defines a set of objects and the relationships between them, in order to model the provision of Human Services.

The nature of Human Services means that HSDS needs to provide a flexible way of modelling the services, organizations providing them, locations, and other attributes of Human Services. A location may have many services operating out of it, a single organization may be responsible for several services, a service may have multiple sources of funding, a single phone number can be used for a service, and organization, and a location.

To this end, HSDS does not have a hierarchical model with a single top-level object. HSDS instead defines a number of objects and the relationships between them. This allows systems and people to exchange and use HSDS data in a manner suited to their use-case. For example, someone may prefer an organization-oriented view whereas others may prefer a location-oriented view.

Each object in HSDS has an id property which contains a uuid as specified by RFC 4122. This enables applications to store their data in a normalized database. When exchanging or publishing the data, applications must dereference these to meet the requirements of the HSDS JSON schema.

In tabular serializations of HSDS (see Serialization & Publication Formats) the id property can act as a foreign key without the need for dereferencing.

Core objects

HSDS designates four objects as “core”. These are the objects modelling concepts which are central to supporting all of HSDS core use-cases:

organization – See Organization. Organizations that provide services.
service – See Service. The service itself, with descriptions and classifications to allow potential service users to identify services which may meet their needs.
location – See Location. Locations where services are delivered either physically or virtually (e.g. over the phone or internet).
service_at_location – See Service at Location. A link between a service and a location to capture location-specific information about services that are provided at multiple locations. This can also be used to override any default service or location information with information specific to a service at a specific location.

Additional information about organizations, locations, and services is held in separate objects. Full details are available on the Schema Reference page.

Relationships between objects

The relationships between objects in HSDS can be either one-to-one (1:1) or one-to-many (1:many). Some objects may have a relationship with a single core object, or to multiple types of core object.

The canonical source of information about the relationships between HSDS is the JSON Schemas which define each object. These are presented on the Schema Reference page. Wherever you see a property with a Type of Object, this is a 1:1 relationship between the two objects. Wherever you see a property with a Type of array[object], this is a 1:many relationship between the two objects.

The following table and diagrams are designed to provide an overview of the different relationships between objects. If there are any conflicts between this and the HSDS Schemas, then the Schemas take precedence.

Table of relationships

Object	organization	service	location	service_at_location
program	1:many
service	1:many
service_at_location		1:1	1:1
location	1:many
phone	1:many	1:many	1:many	1:many
contact	1:many	1:many		1:many
address			1:many
schedule		1:many	1:many	1:many
funding	1:many	1:many
service_area		1:many
required_document		1:many
language		1:many	1:many
accessibility			1:many
cost_option		1:many
organization_identifier	1:many

Attributes, Metadata, and Taxonomy Terms

HSDS also defines some special objects which have relationships that fall outside of the usual 1:1 and 1:many relationships defined above.

attribute – see Attribute. This can be joined to any table other than itself or metadata by using its _link_id property. It can be linked to taxonomy_term using its taxonomy_term_id property.
metadata – see Metadata. This can be joined to any table other than itself or attribute through its resource_id property.
taxonomy_term – see Taxonomy Term. This can be joined to taxonomy using its taxonomy_id property.