HSDS 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 its required or optional fields.
A collection of HSDS data can be serialized 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 metadata 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 sentence, 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 |
string (email) |
The contact e-mail address for the organization. |
False |
False |
|
url |
string (uri) |
The URL (website address) of the organization. |
False |
False |
tax_status |
string |
Government assigned tax designation 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 |
True |
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 (uri) |
URL of the service |
False |
False |
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 |
accreditations |
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 |
service_attribute¶
The services attributes table creates a link between a service and one or more classifications that describe the nature of the service provided.
name |
service_attribute |
path |
service_attributes.csv |
format |
csv |
mediatype |
text/csv |
Field Name |
Type (Format) |
Description |
Required? |
Unique? |
---|---|---|---|---|
id |
string |
Each service_attribute entry should have a unique identifier. |
True |
True |
service_id |
string |
The identifier of the service to which this taxonomy term applies. |
True |
False |
taxonomy_term_id |
string |
The identifier of this taxonomy term from the taxonomy table. |
False |
False |
other_attribute¶
The other_attributes table creates a link between entities other than service and one or more classifications that describe the entity.
name |
other_attribute |
path |
other_attributes.csv |
format |
csv |
mediatype |
text/csv |
Field Name |
Type (Format) |
Description |
Required? |
Unique? |
---|---|---|---|---|
id |
string |
Each other_attribute entry should have a unique identifier. |
True |
True |
link_id |
string |
The identifier of the entity to which this taxonomy term applies. |
True |
False |
link_type |
string |
The identifier of the entity to which this taxonomy term applies. |
True |
False |
taxonomy_term_id |
string |
The identifier of this taxonomy term from the taxonomy table. |
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 |
True |
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 |
True |
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 |
True |
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 |
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 |
True |
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 or newline 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 or newline 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 or newline 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 |
True |
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 or newline 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 or newline 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 or newline 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 |
schedule¶
The schedule table contains details of when a service or location is open. Entries are RFC 5545 RRULES.
name |
schedule |
path |
schedules.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 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 |
valid_from |
date |
The date from which the schedule information is valid. |
False |
False |
valid_to |
date |
The last date on which the schedule information is valid. |
False |
False |
dtstart |
date |
iCal - The date of the first event is the schedule. Necessary when using the ‘interval’ feature, optional otherwise. |
False |
False |
timezone |
number |
The timezone that all dates are expressed as, expressed as a UTC offset. Dates are assumed to be UTC otherwise. |
False |
False |
until |
date |
iCal - The date of the last occurence of the recurring event. |
False |
False |
count |
date |
iCal - The number of times that the event occurs. Use this instead of ‘until’, if appropriate. |
False |
False |
wkst |
date |
iCal - The day on which the week starts, eg MO. |
False |
False |
freq |
string |
iCal - How often the frequency repeats. E.g. Frequency use one of WEEKLY or MONTHLY. |
False |
False |
interval |
number |
iCal - How often the frequency repeats. E.g. Interval 2 for Frequency WEEKLY gives Fortnightly |
False |
False |
byday |
string |
iCal - Comma seperated days of the week. E.g. SU,MO,TU,WE,TH,FR,SA. Where freq is MONTHLY each part can be preceded by a positive or negative integer to represent which occurrence in a month; e.g. 2MO is the second Monday in a month. -1FR is the last Friday |
False |
False |
byweekno |
string |
iCal - Comma seperated numeric weeks of the year if freq is WEEKLY. Can be negative to represent weeks before the end of the year; e.g. -5 is the 5th to last week in a year. |
False |
False |
bymonthday |
number |
iCal - Comma separated numeric days of the month if frequency is MONTHLY. Can be negative to represent days before the end of the month; e.g. -5 is the 5th to last day in a month. |
False |
False |
byyearday |
number |
iCal - Comma separated numeric days of the month if frequency is YEARLY. Can be negative to represent days before the end of the year; e.g. -1 is the last day in a year. |
False |
False |
description |
string |
Human readable description of the availability of the service. |
False |
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 EST.) |
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 EST.) |
False |
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 |
True |
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 |
True |
service_id |
string |
The identifier of the service for which this entry describes the eligibility criteria |
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 |
True |
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 |
True |
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 |
True |
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 interpretation.
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 |
True |
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 |
True |
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_term¶
Each service can be categorized according to one or more taxonomy terms. The taxonomy_term table contains a list of taxonomy terms, their names, and, for hierarchical taxonomies, their structure.
name |
taxonomy_term |
path |
taxonomy_terms.csv |
format |
csv |
mediatype |
text/csv |
Field Name |
Type (Format) |
Description |
Required? |
Unique? |
---|---|---|---|---|
id |
string |
Each taxonomy term must have a unique identifier, within the scope of the dataset |
True |
True |
term |
string |
The taxonomy term itself. |
True |
False |
description |
string |
What the term means |
True |
False |
parent_id |
string |
If this is a child term in a hierarchical taxonomy, give the identifier of the parent category. For top-level categories, this should be left blank. |
False |
False |
taxonomy |
string |
If this is an established taxonomy, detail which taxonomy is in use. For example, AIRS or Open Eligibility. If possible, provide a URI. |
False |
False |
language |
string |
An ISO 639-1, or ISO 639-2 [language code](available at http://www.loc.gov/standards/iso639-2/php/code_list.php) to represent the language of the term. 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 |
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 |
True |
resource_id |
string |
Each service, program. location, address, or contact will have a unique identifier. |
True |
True |
resource_type |
string |
The type of entity being referenced |
True |
True |
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 |
True |
name |
string |
False |
False |
|
language |
string |
False |
False |
|
character_set |
string |
False |
False |