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 (url) 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
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) URL of the service False False
email string (email) Email address for the service False False
status string The current status of the service. True False
interpretation_services string A description of any interpretation services available for accessing this service. False 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
fees string Details of any charges for service users to access this service. False False
accrediations string Details of any accreditations. Accreditation is the formal evaluation of an organization or program against best practice standards set by an accrediting organization. False False
licenses string An organization may have a license issued by a government entity to operate legally. A list of any such licenses can be provided here. False False
taxonomy_ids string (Deprecated) A comma separated list of identifiers from the taxonomy table. This field is deprecated in favour of using the service_taxonomy table. False False

service_taxonomy

The service taxonomy creates a link between a service and one or more classifications that describe the nature of the service provided.

name service_taxonomy
path services_taxonomy.csv
format csv
mediatype text/csv
Field Name Type (Format) Description Required? Unique?
id string Each service must have a unique identifier. True True
service_id string The identifier of the service at a given location. True False
taxonomy_id string The identifier of this classification from the taxonomy table. True False
taxonomy_detail string For advanced uses, this field can indicate a constraint on this classification, using * to combine two taxonomy terms. For example: ‘Food Pantry*Homeless’ (where ‘Food Pantry’ and ‘Homeless’ are identifiers in the taxonomy table) to indicate a food pantry service for homeless clients, but not available to other client groups. In this example, there would be two entries in service_taxonomy, one with ‘Food Pantry’ and one for ‘Homeless’ in the taxonomy_id field, but both with the same ‘Food Pantry*Homeless’ value in the taxonomy_detail field. 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
description string Any additional information that should be displayed to users about the service at this specific location. False False

location

The location tables provides details of the locations where organizations operate. Locations may be virtual, and one organization may have many 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 entry should be linked to a single organization. This is the organization that is responsible for maintaining information about this location. The identifier of the organization should be given here. Details of the services the organisation delivers at this location should be provided in the services_at_location table. 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
service_at_location_id string The identifier of the ‘service at location’ table entry, when this phone number is specific to a service in a particular location. False False
number string The phone number True False
extension number The extension of the phone number False False
type string Indicates the type of phone service, drawing from the RFC6350 list of types (text (for SMS), voice, fax, cell, video, pager, textphone). False False
language string A comma separated list of ISO 639-1, or ISO 639-2 [language codes](available at http://www.loc.gov/standards/iso639-2/php/code_list.php) to represent the languages available from this phone service. The three-letter codes from ISO 639-2 provide greater accuracy when describing variants of languages, which may be relevant to particular communities. False False
description string A description providing extra information about the phone service (e.g. any special arrangements for accessing, or details of availability at particular times. False False
department string (Deprecated) The department for which this is the phone number. This field is deprecated and will be removed in a future version of HSDS. 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
service_at_location_id string The identifier of the ‘service at location’ table entry, when this contact is specific to a service in a particular location. 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 (email) 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 (Often included as ‘care of’ component of an address.) False False
address_1 string The first line(s) of the address, including office, building number and street. True False
address_2 string (Deprecated) A second (additional) line of address information. (This field is deprecated: we recommend including all address information before ‘city’ as a comma separated list in address_1. There is no guarantee that systems will read this line of address information.) False False
address_3 string (Deprecated) A third (additional) line of address information. (This field is deprecated: we recommend including all address information before ‘city’ as a comma separated list in address_1. There is no guarantee that systems will read this line of address information.) False False
address_4 string (Deprecated) The fourth (additional) line of address information. (This field is deprecated: we recommend including all address information before ‘city’ as a comma separated list in address_1. There is no guarantee that systems will read this line of address information.) False False
city string The city in which the address is located. True False
region string The region in which the address is located (optional). False 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 whose attention should be sought at the location (Often included as ‘care of’ component of an address.) False False
address_1 string The first line(s) of the address, including office, building number and street. True False
address_2 string (Deprecated) A second (additional) line of address information. (This field is deprecated: we recommend including all address information before ‘city’ as a comma separated list in address_1. There is no guarantee that systems will read this line of address information.) False False
address_3 string (Deprecated) A third (additional) line of address information. (This field is deprecated: we recommend including all address information before ‘city’ as a comma separated list in address_1. There is no guarantee that systems will read this line of address information.) False False
address_4 string (Deprecated) The fourth (additional) line of address information. (This field is deprecated: we recommend including all address information before ‘city’ as a comma separated list in address_1. There is no guarantee that systems will read this line of address information.) False False
city string The city in which the address is located. True False
region string The region in which the address is located (optional). False 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

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
service_at_location_id string The identifier of the ‘service at location’ table entry, when this schedule is specific to a service in a particular location. 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
service_at_location_id string The identifier of the ‘service at location’ table entry, when this schedule is specific to a service in a particular location. 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 in receipt of this funding. False False
service_id string The identifier of the service in receipt of this funding False False
source string A free text description of the source of funds for this 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
description string A more detailed description of this service area. Used to provide any additional information that cannot be communicated using the structured area and geometry fields. 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

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

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
details string Any further details relating to the relevant accessibility arrangements at this location. E.g. whether advance notice is required to use an accessibility facility. 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
vocabulary string If this is an established taxonomy, detail which taxonomy is in use. For example, AIRS or Open Eligibility. 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