Reference

The Human Services Data Specification defines a set of objects and the relationships between them.

This page provides the canonical definition of each object and it’s required or optional fields.

A collection of HSDS data can be serialised as a Tabular Data Package consisting of csv files for each of the objects required, and a package descriptor (datapackage.json) file adapted from the current HSDS specification to include any additional fields and meta-data from the data publisher.

Names and descriptions

Locations, Services and Organizations all have name and description field that can contain free text.

A name and alternate_name field should only ever include plain text, without formatting.

A description field may include HTML elements or Markdown, with special characters escaped or encoded.

Consuming applications that expect plain-text only should strip HTML tags from these fields.

Publishers should also be aware that some applications may wish to extract a ‘short description’ from the description field, and may do so by looking for the first full sentance, or first line-break.

Objects and fields

organization

The organization record is used to provide basic description and details about each organization delivering services. Each service should be linked to the organization responsible for its delivery. One organization may deliver many services.

name	organization
path	organizations.csv
format	csv
mediatype	text/csv

Field Name	Type (Format)	Description	Required?	Unique?
id	string (uuid)	Each organization must have a unique identifier.	True	True
name	string	The official or public name of the organization.	True	False
alternate_name	string	Alternative or commonly used name for the organization.	False	False
description	string	A brief summary about the organization. It can contain markup such as HTML or Markdown.	True	False
email	string (email)	The contact e-mail address for the organization.	False	False
url	string	The URL (website address) of the organization.	False	False
tax_status	string	Government assigned tax designation for for tax-exempt organizations.	False	False
tax_id	string	A government issued identifier used for the purpose of tax administration.	False	False
year_incorporated	date (%Y)	The year in which the organization was legally formed.	False	False
legal_status	string	The legal status defines the conditions that an organization is operating under; e.g. non-profit, private corporation or a government organization.	False	False

program

Some organizations organise their services into programs. A program brings together a number of related services.

name	program
path	programs.csv
format	csv
mediatype	text/csv

Field Name	Type (Format)	Description	Required?	Unique?
id	string	Each program must have a unique identifier.	True	True
organization_id	string (uuid)	Each program must belong to a single organization. The identifier of the organization should be given here.	True	False
name	string	The name of the program	True	False
alternate_name	string	An alternative name for the program	False	False

service

Services are provided by organizations to a range of different groups. Details on where each service is delivered are contained in the services_at_location table.

name	service
path	services.csv
format	csv
mediatype	text/csv

Field Name	Type (Format)	Description	Required?	Unique?
id	string	Each service must have a unique identifier.	True	True
organization_id	string	The identifier of the organization that provides this service.	True	False
location_id	string	The identifier of the location where this service is delivered.	False	False
program_id	string	The identifier of the program this service is delivered under.	False	False
name	string	The official or public name of the service.	True	False
alternate_name	string	Alternative or commonly used name for a service.	False	False
description	string	A description of the service.	False	False
url	string	URL of the service	False	False
email	string	Email address for the service	False	False
status	string	The current status of the service.	True	False
application_process	string	The steps needed to access the service.	False	False
wait_time	string	Time a client may expect to wait before receiving a service.	False	False
taxonomy_ids	string	A comma separated list of identifiers from the taxonomy table. Advanced users may also include composite categories, using * to combine two taxonomy terms. For example: ‘Food Pantry*Immigrants,Food Pantry*Homeless’ (where ‘Food Pantry’,’Immigrants’ and ‘Homeless’ are identifiers in the taxonomy table), would indicate a food pantry service for the homeless or immigrants, but not available to other client groups.	False	False

service_at_location

The services at location table creates a link between a service and a specific location.

name	service_at_location
path	services_at_location.csv
format	csv
mediatype	text/csv

Field Name	Type (Format)	Description	Required?	Unique?
id	string	Each entry must have a unique identifier	True	True
service_id	string	The identifier of the service at a given location.	True	False
location_id	string	The identifier of the location where this service operates.	True	False
url	string	If the service at this location has a specific URL, that can be provided here.	False	False
email	string	If the service at this location has a specific email address, that can be provided here.	False	False

location

The location tables provides details of the locations where organizations operate. Locations may be virtual, and one organization may have may locations.

name	location
path	locations.csv
format	csv
mediatype	text/csv

Field Name	Type (Format)	Description	Required?	Unique?
id	string	Each location must have a unique identifier	True	False
organization_id	string	Each location must belong to a single organization. The identifier of the organization should be given here.	False	False
name	string	The name of the location	False	False
alternate_name	string	An alternative name for the location	False	False
description	string	A description of this location.	False	False
transportation	string	A description of the access to public or private transportation to and from the location.	False	False
latitude	number	Y coordinate of location expressed in decimal degrees in WGS84 datum.	False	False
longitude	number	X coordinate of location expressed in decimal degrees in WGS84 datum.	False	False

phone

The phone table contains details of the telephone numbers are used to contact organizations, services, and locations.

name	phone
path	phones.csv
format	csv
mediatype	text/csv

Field Name	Type (Format)	Description	Required?	Unique?
id	string	Each entry must have a unique identifier	True	False
location_id	string	The identifier of the location where this phone number is located	False	False
service_id	string	The identifier of the service for which this is the phone number	False	False
organization_id	string	The identifier of the organisation for which this is the phone number	False	False
contact_id	string	The identifier of the contact for which this is the phone number	False	False
number	string	The phone number	True	False
extension	number	The extension of the phone number	False	False
type	string	Whether the phone number relates to a fixed or cellular phone	False	False
department	string	The department for which this is the phone number	False	False

contact

The contact table contains details of the named contacts for services and organizations. Note that in the HSDS data package format, if an individual is the contact for multiple services, their details may be duplicated multiple times in this table, each time with a new identifier, and with the rows containing different service ids.

name	contact
path	contacts.csv
format	csv
mediatype	text/csv

Field Name	Type (Format)	Description	Required?	Unique?
id	string	Each contact must have a unique identifier	True	False
organization_id	string	The identifier of the organization for which this is a contact	False	False
service_id	string	The identifier of the service for which this is a contact	False	False
name	string	The name of the person	False	False
title	string	The job title of the person	False	False
department	string	The department that the person is part of	False	False
email	string	The email address of the person	False	False

physical_address

The addresses table contains the physical addresses for locations

name	physical_address
path	physical_addresses.csv
format	csv
mediatype	text/csv

Field Name	Type (Format)	Description	Required?	Unique?
id	string	Each physical address must have a unique identifier	True	False
location_id	string	The identifier of the location for which this is the address	False	False
attention	string	The person or entity whose attention should be sought at the location	False	False
address_1	string	The first line of the address	True	False
address_2	string	The second line of the address	False	False
address_3	string	The third line of the address	False	False
address_4	string	The fourth line of the address	False	False
city	string	The city in which the address is located	True	False
state_province	string	The state or province in which the address is located	True	False
postal_code	string	The postal code for the address	True	False
country	string	The country in which the address is located. This should be given as an ISO 3361-1 country code (two letter abbreviation)	True	False

postal_address

The postal_address table contains the postal addresses for mail to a certain location. This may differ from the physical location.

name	postal_address
path	postal_addresses.csv
format	csv
mediatype	text/csv

Field Name	Type (Format)	Description	Required?	Unique?
id	string	Each postal address must have a unique identifier	True	False
location_id	string	The identifier of the location for which this is the postal address	False	False
attention	string	The person or entity for whose attention mail should be marked	False	False
address_1	string	The first line of the address	False	False
address_2	string	The second line of the address	False	False
address_3	string	The third line of the address	False	False
address_4	string	The fourth line of the address	False	False
city	string	The city in which the address is located	False	False
state_province	string	The state or province in which the address is located	False	False
postal_code	string	The postal code for the address	False	False
country	string	The country in which the address is located	False	False

regular_schedule

The regular_schedule table contains details of when a service or location is open under normal circumstances. Each entry in the table can relate to one and only one day of the week.

name	regular_schedule
path	regular_schedules.csv
format	csv
mediatype	text/csv

Field Name	Type (Format)	Description	Required?	Unique?
id	string	Each entry must have a unique identifier	True	False
service_id	string	The identifier of the service for which this is the regular schedule	False	False
location_id	string	The identifier of the location for which this is the regular schedule	False	False
weekday	integer	The day of the week that this entry relates to	True	False
opens_at	time	The time when a service or location opens. This should use HH:MM format and should include timezone information, either adding the suffix ‘Z’ when the date is in UTC, or including an offset from UTC (e.g. 09:00-05:00 for 9am East Coast Time.	False	False
closes_at	time	The time when a service or location opens. This should use HH:MM format and should include timezone information, either adding the suffix ‘Z’ when the date is in UTC, or including an offset from UTC (e.g. 09:00-05:00 for 9am East Coast Time.	False	False

holiday_schedule

The holiday_schedule table contains details of when a service or location is open during holidays. Each entry in the table describes a period of one or more days, and the operating times on those days.

name	holiday_schedule
path	holiday_schedules.csv
format	csv
mediatype	text/csv

Field Name	Type (Format)	Description	Required?	Unique?
id	string	Each entry must have a unique identifier	True	False
service_id	string	The identifier of the service for which this is the holiday schedule	False	False
location_id	string	The identifier of the location for which this is the holiday schedule	False	False
closed	boolean	Indicates if a service or location is closed during a public holiday	True	False
opens_at	time	The time when a service or location opens. This should use HH:MM format and should include timezone information, either adding the suffix ‘Z’ when the date is in UTC, or including an offset from UTC (e.g. 09:00-05:00 for 9am East Coast Time.	False	False
closes_at	time	The time when a service or location closes. This should use HH:MM format and should include timezone information, either adding the suffix ‘Z’ when the date is in UTC, or including an offset from UTC (e.g. 09:00-05:00 for 9am East Coast Time.	False	False
start_date	date	The first day that a service or location is closed during a public or private holiday	True	False
end_date	date	The last day that a service or location is closed during a public or private holiday	True	False

funding

The funding table describes the sources of funding for a service or organisation

name	funding
path	funding.csv
format	csv
mediatype	text/csv

Field Name	Type (Format)	Description	Required?	Unique?
id	string	Each entry must have a unique identifier	True	False
organization_id	string	The identifier of the organization for which this entry describes the source of funding	False	False
service_id	string	The identifier of the service for which this entry describes the source of funding	False	False
source	string	Source of funds for organization or service	False	False

eligibility

The eligibility tables contains details of the eligibility criteria for particular services

name	eligibility
path	eligibility.csv
format	csv
mediatype	text/csv

Field Name	Type (Format)	Description	Required?	Unique?
id	string	Each entry must have a unique identifier	True	False
service_id	string	The identifier of the service for which this entry describes the eligibility criteria	False	False
eligibility	string	The rules or guidelines that determine who can receive the service.	False	False

service_area

The service_area table contains details of the geographic area for which a service is available.

name	service_area
path	service_areas.csv
format	csv
mediatype	text/csv

Field Name	Type (Format)	Description	Required?	Unique?
id	string	Each service area must have a unique identifier	True	False
service_id	string	The identifier of the service for which this entry describes the service area	False	False
service_area	string	The geographic area where a service is available. This is a free-text description, and so may be precise or indefinite as necessary.	False	False

required_document

The required_document table contains details of any documents that are required in order to access or use services.

name	required_document
path	required_documents.csv
format	csv
mediatype	text/csv

Field Name	Type (Format)	Description	Required?	Unique?
id	string	Each document must have a unique identifier	True	False
service_id	string	The identifier of the service for which this entry describes the required document	False	False
document	string	The document required to apply for or receive the service. e.g. ‘Government-issued ID’, ‘EU Passport’	False	False

fee

The fee table contains details of the costs of services, including those that are free

name	fee
path	fees.csv
format	csv
mediatype	text/csv

Field Name	Type (Format)	Description	Required?	Unique?
id	string	Each entry must have a unique identifier	True	False
service_id	string	The identifier of the service for which this entry describes the costs of service	False	False
fee	string	A listing of the costs of services, including free ones	False	False

payment_accepted

The payment_accepted table contains details of the methods of payment that can be used in order to pay for services

name	payment_accepted
path	payments_accepted.csv
format	csv
mediatype	text/csv

Field Name	Type (Format)	Description	Required?	Unique?
id	string	Each entry must have a unique identifier	True	False
service_id	string	The identifier of the services for which the entry describes the accepted payment methods	False	False
payment	string	The methods of payment accepted for the service	False	False

intepretation_services

The interpretation_services table contains details of the interpretation services which are available at a certain service.

name	intepretation_services
path	interpretation_services.csv
format	csv
mediatype	text/csv

Field Name	Type (Format)	Description	Required?	Unique?
id	string	Each service must have a unique identifier	True	False
service_id	string	The identifier of the services for which the entry describes the interpretation services available	False	False
language	string	Languages, other than English, for which interpretation is available. Languages are listed as ISO639-1 codes.	False	False

language

The language table contains details of the languages that are spoken at locations or services. This does not include languages which can only be used with intepretation.

name	language
path	languages.csv
format	csv
mediatype	text/csv

Field Name	Type (Format)	Description	Required?	Unique?
id	string	Each language must have a unique identifier	True	False
service_id	string	The identifier of the service for which the entry describes the languages in which services are delivered	False	False
location_id	string	The identifier of the location for which the entry describes the languages in which services are delivered	False	False
language	string	Languages, other than English, in which the service is delivered. Languages are listed as ISO639-1 codes.	False	False

accessibility_for_disabilities

The accessibility_for_disabilities table contains details of the arrangements for access to locations for people who have disabilities

name	accessibility_for_disabilities
path	accessibility_for_disabilities.csv
format	csv
mediatype	text/csv

Field Name	Type (Format)	Description	Required?	Unique?
id	string	Each entry must have a unique identifier	True	False
location_id	string	The identifier of the location for which the entry describes the accessibility provision	False	False
accessibility	string	Description of assistance or infrastructure that facilitate access to clients with disabilities.	False	False

taxonomy

Each service can be categorized according to one or more taxonomy terms. The taxonomy table contains a list of taxonomy identifiers, their names, and, for hierarchical taxonomies, their structure.

name	taxonomy
path	taxonomy.csv
format	csv
mediatype	text/csv

Field Name	Type (Format)	Description	Required?	Unique?
id	string	Each taxonomy entry must have a unique identifier. If combining multiple taxonomies with overlapping identifiers, use a prefix to distinguish them.	True	True
name	string	The name of this taxonomy term or category.	True	False
parent_id	string	If this is a child category in a hierarchical taxonomy, give the identifier of the parent category. For top-level categories, this should be left blank.	False	False
parent_name	string	If this is a child category in a hierarchical taxonomy, give the name of the parent category. For top-level categories, this should be left blank.	False	False

metadata

The metadata table contains a record of the changes that have been made to the data in order to maintain provenance information.

name	metadata
path	metadata.csv
format	csv
mediatype	text/csv

Field Name	Type (Format)	Description	Required?	Unique?
id	string	Each entry must have a unique identifier	True	False
resource_id	string	Each service, program. location, address, or contact will have a unique identifier. Unique ids are UUIDs.	True	False
last_action_date	datetime	The date when data was changed.	True	False
last_action_type	string	The kind of change made to the data; eg create, update, delete	True	False
field_name	string	The name of field that has been modified	True	False
previous_value	string	The previous value of a field that has been updated	True	False
replacement_value	string	The new value of a field that has been updated	True	False
updated_by	string	The name of the person who updated a value	True	False

meta_table_description

The meta_table_description table contains metadata about individual tables.

name	meta_table_description
path	meta_table_descriptions.csv
format	csv
mediatype	text/csv

Field Name	Type (Format)	Description	Required?	Unique?
id	string	Each entry must have a unique identifier	True	False
name	string		False	False
language	string		False	False
character_set	string		False	False