Smart Data Models’ Candidates repository now includes a new candidate standard from Open Referral: hsds, with 5 candidate models for directories of health, human and social services: the organizations, services, programs and locations of a community resource directory. The Human Services Data Specification is published under CC-BY-SA 4.0, so these derived models are shared under the same licence. Like every candidate, each model comes with a JSON Schema, an NGSI-LD @context and all four example serializations (NGSI-v2 and NGSI-LD, key-values and normalized), each validated against its schema.
About the Human Services Data Specification
Open Referral develops the Human Services Data Specification (HSDS), also known as “the Open Referral format”: an exchange format for publishing directory information about human services (food assistance, job training, child care, counselling…) as open data. Governments, information-and-referral providers and community organizations use it to share who offers which service, where, when, for whom and at what cost. The candidate is based on HSDS 3.3.1, the latest release, which defines its objects as JSON Schemas.
The models
| Model | HSDS object | What it describes | Attributes |
|---|---|---|---|
Organization |
organization | An organization that delivers services, with funding, identifiers and phones | 24 |
Service |
service | A service: status, eligibility, fees, application process, operating hours, service areas, languages, costs, required documents | 38 |
Location |
location | A physical, postal or virtual place where services are delivered, with addresses and accessibility | 25 |
ServiceAtLocation |
service_at_location | A service as delivered at one location, with location-specific contacts and schedules | 15 |
Program |
program | A group of related services run by one organization | 11 |
One consistent example directory
The examples are synthetic, and say so. They are adapted from HSDS’s own example data: the fictitious Example Organization Inc. runs the Community Mental Health Support program, whose Community Counselling service is delivered at the MyCity Civic Center. Personal names were removed, phone numbers come from the UK range reserved for drama, and the coordinates are illustrative.
Translation notes
- HSDS names, verbatim. Every field keeps its HSDS snake_case name (
eligibility_description,organization_id,service_at_locations…). Entity types use the HSDS documentation headings in PascalCase. The only rename isid→hsdsId. - Linked entities. The links between organizations, programs, services, locations and services-at-location are NGSI-LD Relationships.
- Nested where HSDS nests. Phones, contacts, schedules, addresses, accessibility, languages, funding, costs, service areas, attributes and taxonomy terms keep their full HSDS structure.
- Ready for geo-queries. Locations and services-at-location get an NGSI-LD
location(GeoJSON point) built from HSDS’s own latitude and longitude. It is the only addition to the HSDS content. - Current fields only. Fields that HSDS has deprecated (including
service.schedules, replaced in 3.3 byoperating_hoursandevents) are left out. - Licence. HSDS is CC-BY-SA 4.0: “Human Services Data Specification: an Open Referral resource”. The candidate models are shared alike.
Try it, and tell us what’s missing
These are Candidates: first, carefully sourced translations that are not yet official Smart Data Models subjects. Before that step, the main open question is overlap: Organization with dataModel.Organization and other organization models, Service with the public services of dataModel.CPSV-AP, and Location with dataModel.PointOfInterest. Natural next steps are taxonomy terms as shared entities and a mapping to CPSV-AP.
Browse the models, open an issue, or send a PR:
👉 https://github.com/smart-data-models/Candidates/tree/master/standards/hsds


