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. It is used to validate the structure and format of HSDS data. Schema files for each object in HSDS are also available as JSON schema from the HSDS GitHub repository.

HSDS data can also 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
email	string (email)	The contact e-mail address for the organization.	False	False
website	string (uri)	The URL (website address) of the organization.	False	False
tax_status	string	DEPRECATED: Government assigned tax designation for tax-exempt organizations.	False	False
tax_id	string	DEPRECATED: A government issued identifier used for the purpose of tax administration.	False	False
year_incorporated	number (%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
logo	string	A URL to an image associated with the organization which can be presented alongside its name.	False	False
uri	string (uri)	A persistent identifier to uniquely identify the organization such as those provided by Open Corporates or some other relevant URI provider. This is not for listing the website of the organization: that can be done through the website field of the Organization.	False	False
parent_organization_id	string	The identifier of the organization’s parent 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 (uuid)	The identifier for the program. Each program must have a unique identifier.	True	True
organization_id	string	The identifier for the organization which the program belongs to. Each program must belong to a single organization, and the identifier for that organization should be given here.	True	True
name	string	The name of the program	True	False
alternate_name	string	If the program has an alternative name it can be given here	False	False
description	string	A brief and clear summary of the program	True	False

service

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

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

Field Name	Type (Format)	Description	Required?	Unique?
id	string (uuid)	The identifier for the service. 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	If the service has an alternative or commonly used other name, it can be given here.	False	False
description	string	A description of the service.	False	False
url	string (uri)	URL of the service	False	False
email	string (email)	An email address which can be used by WHOM? to contact the service provider.	False	False
status	string	The current status of the service which can be active, inactive, defunct, or temporarily closed.	True	False
interpretation_services	string	A description of any interpretation services available for accessing this service.	False	False
application_process	string	A description of the steps needed to access this service.	False	False
fees_description	string	Details of any charges for service users to access this service.	False	False
wait_time	string	DEPRECATED: Time a client may expect to wait before receiving a service.	False	False
fees	string	DEPRECATED: 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
eligibility_description	string	A description of the type of person for whom this service is intended.	False	False
minimum_age	number	The minimum age of a person required to meet this eligibility requirement.	False	False
maximum_age	number	The maximum age of a person required to meet this eligibility requirement.	False	False
assured_date	date	The date that the information about the service was last checked	False	False
assurer_email	string (email)	The contact e-mail address for the person or organization which last assured the service.	False	False
licenses	string	DEPRECATED: 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
alert	string	Notice of any short term alerts concerning the service. e.g.	False	False

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	attribute
path	attributes.csv
format	csv
mediatype	text/csv

Field Name	Type (Format)	Description	Required?	Unique?
id	string (uuid)	The identifier of the service_attribute entry. Each service_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
taxonomy_term_id	string	The identifier of this taxonomy term from the taxonomy table.	True	False
link_type	string	A code taken from an enumerated open codelist to indicate what the taxonomy term describes e.g. the service eligibility or intended audience.	False	False
link_entity	string	The table of the link_id	True	False
value	string	The value (if any) of an attribute	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	service_at_location.csv
format	csv
mediatype	text/csv

Field Name	Type (Format)	Description	Required?	Unique?
id	string (uuid)	The identifier of the entry. 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 (uuid)	The identifier of the location. Each location must have a unique identifier.	True	True
location_type	string	The type of location, which may be either physical, postal, or virtual.	True	False
url	string (uri)	If location_type is virtual, then this field represents the URL of a virtual location.	False	False
organization_id	string	The organization identifier for a location. 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 organization 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	If the location has an alternative name then it may be given here.	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
external_identifier	string	A third party identifier for a location which can be drawn from other services e.g. UK UPRN or what3words.	False	False
external_identifier_type	string	The scheme used for the location’s external_identifier e.g. UK UPRN or what3words.	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 (uuid)	The id for a phone number. 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 organization 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
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

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 (uuid)	The identifier for the contact. 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
location_id	string	The identifier for the location_id when the location of the contact is relevant.	False	False
name	string	The name of the contact.	False	False
title	string	The job title of the contact.	False	False
department	string	The department that the contact is a part of.	False	False
email	string (email)	The email address of the contact.	False	False

address

Physical or postal address

name	address
path	addresses.csv
format	csv
mediatype	text/csv

Field Name	Type (Format)	Description	Required?	Unique?
id	string (uuid)	The id of the postal address. 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 name of the person or entity whose attention should be sought at the location. These are often included as a “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	A second (additional) 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
address_type	string	The type of address which may be physical, postal, or virtual.	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 (uuid)	The identifier for the schedule. 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. It must be in the ISO 8601 format of YYYY-MM-DD	False	False
valid_to	date	The last date on which the schedule information is valid. It must be in the ISO 8601 format of YYYY-MM-DD	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	string	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	A 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
schedule_link	string (uri)	URL of a link for the scheule which may show each individual session and may provide a booking facility	False	False
attending_type	string	A clear description of how to attend this service	False	False
notes	string	Human readable notes on the schedule	False	False

funding

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

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

Field Name	Type (Format)	Description	Required?	Unique?
id	string (uuid)	The identifier for the funding. 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

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 (uuid)	The identifier for the service area. 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
name	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
extent	string	A definition of the polygon defining the area, in geojson.	False	False
extent_type	string	The format of the extent field populated from an enum of “geojson”, “topojson”, “kml”,and (for legacy systems or early state during transformation) “text”	False	False
uri	string	A URI which acts as a persistent identifier to identifiy an area	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 (uuid)	The identifier for the document. 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	A clear description of the document required to apply for or receive the service e.g. “A Government-issued ID” or “EU Passport”.	False	False
uri	string (uri)	Web link to document.	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 (uuid)	The identifier for the language. Each langauge 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
phone_id	string	The identifier of the phone for which the entry describes the languages in which phone is availible in.	False	False
name	string	Languages, other than English, in which the service is delivered. Languages are listed as ISO639-1 codes.	False	False
code	string	The ISO 639-1 or ISO 639-3 code for the language e.g. en, es	False	False
note	string	A clear description of any additional context or services provided for this language e.g. an occasional translation service	False	False

accessibility

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

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

Field Name	Type (Format)	Description	Required?	Unique?
id	string (uuid)	The identifier for this accessibility information. 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
description	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
url	string (uri)	URL of a page giving more information about the accessibility of the location	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 (uuid)	The identifier for this taxonomy term. Each taxonomy term must have a unique identifier, within the scope of the dataset.	True	True
code	string	The term identfier as used in the taxonomy. This and the taxonomy_id combined define the term	False	True
name	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
taxonomy_id	string	The identifier of the taxonomy containing the term	False	False
term_uri	string (uri)	URI of the term	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 (uuid)	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	False
resource_type	string	The type of entity being referenced	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 (uuid)	Each entry must have a unique identifier	True	True
name	string		False	False
language	string		False	False
character_set	string		False	False

cost_option

The cost option table contains the costs of a service at certain points in time. This is an LGA Extension table. This table provides a structured version of the text information contained in the ‘fees’ field of the ‘service’ table.

name	cost_option
path	cost_options.csv
format	csv
mediatype	text/csv

Field Name	Type (Format)	Description	Required?	Unique?
id	string (uuid)	Each entry must have a unique identifier	True	True
service_id	string	The identifier of the services for which the entry describes the cost	True	False
valid_from	date	When this price is valid from	False	False
valid_to	date	When this price is valid to	False	False
option	string	Conditions associated with the cost option. Application Profile Notes: e.g.For the over 60’s 1st session	False	False
currency	string	3 letter currency code	False	False
amount	number	The cost of the option, expresssed as an amount in a currency (expected to be GBP by Open Referral UK).	False	False
amount_description	string	Specific details qualifying the cost amount, e.g. ‘per session’	False	False

organization_identifier

Identifiers for an organization such as: company registration number, charity number, tax registration number. This helps uniquely identify and de-duplicate data

name	organization_identifier
path	organization_identifiers.csv
format	csv
mediatype	text/csv

Field Name	Type (Format)	Description	Required?	Unique?
id	string (uuid)	Each entry must have a unique identifier	True	True
organization_id	string	Each program must belong to a single organization. The identifier of the organization should be given here.	True	False
identifier_scheme	string	Scheme according to http://org-id.guide/.	False	False
identifier_type	string	The type of identifier (company, charity, tax number, etc)	True	False
identifier	string	The third-party identifier	True	False

taxonomy

Taxonomies from which taxonomy terms are taken

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

Field Name	Type (Format)	Description	Required?	Unique?
id	string (uuid)	Each entry must have a unique identifier	True	True
name	string	The name of the taxonomy from which terms are sourced.	True	False
description	string	Description of the taxonomy.	True	False
uri	string (uri)	The URI of the taxonomy.	False	False
version	string	The taxonomy’s version.	False	False