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