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 aservice
and alocation
to capture location-specific information about services that are provided at multiple locations. This can also be used to override any defaultservice
orlocation
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 ormetadata
by using its_link_id
property. It can be linked totaxonomy_term
using itstaxonomy_term_id
property.metadata
– see Metadata. This can be joined to any table other than itself orattribute
through itsresource_id
property.taxonomy_term
– see Taxonomy Term. This can be joined totaxonomy
using itstaxonomy_id
property.