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.
Names and descriptions
Locations, Services and Organizations all have name
and description
field that can contain free text.
A name
and alternate_name
field should only ever include plain text, without formatting.
A description
field may include HTML elements or Markdown, with special characters escaped or encoded.
Consuming applications that expect plain-text only should strip HTML tags from these fields.
Publishers should also be aware that some applications may wish to extract a ‘short description’ from the description
field, and may do so by looking for the first full sentance, or first line-break.
Objects and fields
organization
The organization record is used to provide basic description and details about each organization delivering services. Each service should be linked to the organization responsible for its delivery. One organization may deliver many services.
name |
organization |
path |
organizations.csv |
format |
csv |
mediatype |
text/csv |
Field Name |
Type (Format) |
Description |
Required? |
Unique? |
id |
string (uuid) |
Each organization must have a unique identifier. |
True |
True |
name |
string |
The official or public name of the organization. |
True |
False |
alternate_name |
string |
Alternative or commonly used name for the organization. |
False |
False |
description |
string |
A brief summary about the organization. It can contain markup such as HTML or Markdown. |
True |
False |
email |
string (email) |
The contact e-mail address for the organization. |
False |
False |
url |
string |
The URL (website address) of the organization. |
False |
False |
tax_status |
string |
Government assigned tax designation for for tax-exempt organizations. |
False |
False |
tax_id |
string |
A government issued identifier used for the purpose of tax administration. |
False |
False |
year_incorporated |
date (%Y) |
The year in which the organization was legally formed. |
False |
False |
legal_status |
string |
The legal status defines the conditions that an organization is operating under; e.g. non-profit, private corporation or a government organization. |
False |
False |
program
Some organizations organise their services into programs. A program brings together a number of related services.
name |
program |
path |
programs.csv |
format |
csv |
mediatype |
text/csv |
Field Name |
Type (Format) |
Description |
Required? |
Unique? |
id |
string |
Each program must have a unique identifier. |
True |
True |
organization_id |
string (uuid) |
Each program must belong to a single organization. The identifier of the organization should be given here. |
True |
False |
name |
string |
The name of the program |
True |
False |
alternate_name |
string |
An alternative name for the program |
False |
False |
service
Services are provided by organizations to a range of different groups. Details on where each service is delivered are contained in the services_at_location table.
name |
service |
path |
services.csv |
format |
csv |
mediatype |
text/csv |
Field Name |
Type (Format) |
Description |
Required? |
Unique? |
id |
string |
Each service must have a unique identifier. |
True |
True |
organization_id |
string |
The identifier of the organization that provides this service. |
True |
False |
location_id |
string |
The identifier of the location where this service is delivered. |
False |
False |
program_id |
string |
The identifier of the program this service is delivered under. |
False |
False |
name |
string |
The official or public name of the service. |
True |
False |
alternate_name |
string |
Alternative or commonly used name for a service. |
False |
False |
description |
string |
A description of the service. |
False |
False |
url |
string |
URL of the service |
False |
False |
email |
string |
Email address for the service |
False |
False |
status |
string |
The current status of the service. |
True |
False |
application_process |
string |
The steps needed to access the service. |
False |
False |
wait_time |
string |
Time a client may expect to wait before receiving a service. |
False |
False |
taxonomy_ids |
string |
A comma separated list of identifiers from the taxonomy table. Advanced users may also include composite categories, using * to combine two taxonomy terms. For example: ‘Food Pantry*Immigrants,Food Pantry*Homeless’ (where ‘Food Pantry’,’Immigrants’ and ‘Homeless’ are identifiers in the taxonomy table), would indicate a food pantry service for the homeless or immigrants, but not available to other client groups. |
False |
False |
service_at_location
The services at location table creates a link between a service and a specific location.
name |
service_at_location |
path |
services_at_location.csv |
format |
csv |
mediatype |
text/csv |
Field Name |
Type (Format) |
Description |
Required? |
Unique? |
id |
string |
Each entry must have a unique identifier |
True |
True |
service_id |
string |
The identifier of the service at a given location. |
True |
False |
location_id |
string |
The identifier of the location where this service operates. |
True |
False |
url |
string |
If the service at this location has a specific URL, that can be provided here. |
False |
False |
email |
string |
If the service at this location has a specific email address, that can be provided here. |
False |
False |
location
The location tables provides details of the locations where organizations operate. Locations may be virtual, and one organization may have may locations.
name |
location |
path |
locations.csv |
format |
csv |
mediatype |
text/csv |
Field Name |
Type (Format) |
Description |
Required? |
Unique? |
id |
string |
Each location must have a unique identifier |
True |
False |
organization_id |
string |
Each location must belong to a single organization. The identifier of the organization should be given here. |
False |
False |
name |
string |
The name of the location |
False |
False |
alternate_name |
string |
An alternative name for the location |
False |
False |
description |
string |
A description of this location. |
False |
False |
transportation |
string |
A description of the access to public or private transportation to and from the location. |
False |
False |
latitude |
number |
Y coordinate of location expressed in decimal degrees in WGS84 datum. |
False |
False |
longitude |
number |
X coordinate of location expressed in decimal degrees in WGS84 datum. |
False |
False |
phone
The phone table contains details of the telephone numbers are used to contact organizations, services, and locations.
name |
phone |
path |
phones.csv |
format |
csv |
mediatype |
text/csv |
Field Name |
Type (Format) |
Description |
Required? |
Unique? |
id |
string |
Each entry must have a unique identifier |
True |
False |
location_id |
string |
The identifier of the location where this phone number is located |
False |
False |
service_id |
string |
The identifier of the service for which this is the phone number |
False |
False |
organization_id |
string |
The identifier of the organisation for which this is the phone number |
False |
False |
contact_id |
string |
The identifier of the contact for which this is the phone number |
False |
False |
number |
string |
The phone number |
True |
False |
extension |
number |
The extension of the phone number |
False |
False |
type |
string |
Whether the phone number relates to a fixed or cellular phone |
False |
False |
department |
string |
The department for which this is the phone number |
False |
False |
physical_address
The addresses table contains the physical addresses for locations
name |
physical_address |
path |
physical_addresses.csv |
format |
csv |
mediatype |
text/csv |
Field Name |
Type (Format) |
Description |
Required? |
Unique? |
id |
string |
Each physical address must have a unique identifier |
True |
False |
location_id |
string |
The identifier of the location for which this is the address |
False |
False |
attention |
string |
The person or entity whose attention should be sought at the location |
False |
False |
address_1 |
string |
The first line of the address |
True |
False |
address_2 |
string |
The second line of the address |
False |
False |
address_3 |
string |
The third line of the address |
False |
False |
address_4 |
string |
The fourth line of the address |
False |
False |
city |
string |
The city in which the address is located |
True |
False |
state_province |
string |
The state or province in which the address is located |
True |
False |
postal_code |
string |
The postal code for the address |
True |
False |
country |
string |
The country in which the address is located. This should be given as an ISO 3361-1 country code (two letter abbreviation) |
True |
False |
postal_address
The postal_address table contains the postal addresses for mail to a certain location. This may differ from the physical location.
name |
postal_address |
path |
postal_addresses.csv |
format |
csv |
mediatype |
text/csv |
Field Name |
Type (Format) |
Description |
Required? |
Unique? |
id |
string |
Each postal address must have a unique identifier |
True |
False |
location_id |
string |
The identifier of the location for which this is the postal address |
False |
False |
attention |
string |
The person or entity for whose attention mail should be marked |
False |
False |
address_1 |
string |
The first line of the address |
False |
False |
address_2 |
string |
The second line of the address |
False |
False |
address_3 |
string |
The third line of the address |
False |
False |
address_4 |
string |
The fourth line of the address |
False |
False |
city |
string |
The city in which the address is located |
False |
False |
state_province |
string |
The state or province in which the address is located |
False |
False |
postal_code |
string |
The postal code for the address |
False |
False |
country |
string |
The country in which the address is located |
False |
False |
regular_schedule
The regular_schedule table contains details of when a service or location is open under normal circumstances. Each entry in the table can relate to one and only one day of the week.
name |
regular_schedule |
path |
regular_schedules.csv |
format |
csv |
mediatype |
text/csv |
Field Name |
Type (Format) |
Description |
Required? |
Unique? |
id |
string |
Each entry must have a unique identifier |
True |
False |
service_id |
string |
The identifier of the service for which this is the regular schedule |
False |
False |
location_id |
string |
The identifier of the location for which this is the regular schedule |
False |
False |
weekday |
integer |
The day of the week that this entry relates to |
True |
False |
opens_at |
time |
The time when a service or location opens. This should use HH:MM format and should include timezone information, either adding the suffix ‘Z’ when the date is in UTC, or including an offset from UTC (e.g. 09:00-05:00 for 9am East Coast Time. |
False |
False |
closes_at |
time |
The time when a service or location opens. This should use HH:MM format and should include timezone information, either adding the suffix ‘Z’ when the date is in UTC, or including an offset from UTC (e.g. 09:00-05:00 for 9am East Coast Time. |
False |
False |
holiday_schedule
The holiday_schedule table contains details of when a service or location is open during holidays. Each entry in the table describes a period of one or more days, and the operating times on those days.
name |
holiday_schedule |
path |
holiday_schedules.csv |
format |
csv |
mediatype |
text/csv |
Field Name |
Type (Format) |
Description |
Required? |
Unique? |
id |
string |
Each entry must have a unique identifier |
True |
False |
service_id |
string |
The identifier of the service for which this is the holiday schedule |
False |
False |
location_id |
string |
The identifier of the location for which this is the holiday schedule |
False |
False |
closed |
boolean |
Indicates if a service or location is closed during a public holiday |
True |
False |
opens_at |
time |
The time when a service or location opens. This should use HH:MM format and should include timezone information, either adding the suffix ‘Z’ when the date is in UTC, or including an offset from UTC (e.g. 09:00-05:00 for 9am East Coast Time. |
False |
False |
closes_at |
time |
The time when a service or location closes. This should use HH:MM format and should include timezone information, either adding the suffix ‘Z’ when the date is in UTC, or including an offset from UTC (e.g. 09:00-05:00 for 9am East Coast Time. |
False |
False |
start_date |
date |
The first day that a service or location is closed during a public or private holiday |
True |
False |
end_date |
date |
The last day that a service or location is closed during a public or private holiday |
True |
False |
funding
The funding table describes the sources of funding for a service or organisation
name |
funding |
path |
funding.csv |
format |
csv |
mediatype |
text/csv |
Field Name |
Type (Format) |
Description |
Required? |
Unique? |
id |
string |
Each entry must have a unique identifier |
True |
False |
organization_id |
string |
The identifier of the organization for which this entry describes the source of funding |
False |
False |
service_id |
string |
The identifier of the service for which this entry describes the source of funding |
False |
False |
source |
string |
Source of funds for organization or service |
False |
False |
eligibility
The eligibility tables contains details of the eligibility criteria for particular services
name |
eligibility |
path |
eligibility.csv |
format |
csv |
mediatype |
text/csv |
Field Name |
Type (Format) |
Description |
Required? |
Unique? |
id |
string |
Each entry must have a unique identifier |
True |
False |
service_id |
string |
The identifier of the service for which this entry describes the eligibility criteria |
False |
False |
eligibility |
string |
The rules or guidelines that determine who can receive the service. |
False |
False |
service_area
The service_area table contains details of the geographic area for which a service is available.
name |
service_area |
path |
service_areas.csv |
format |
csv |
mediatype |
text/csv |
Field Name |
Type (Format) |
Description |
Required? |
Unique? |
id |
string |
Each service area must have a unique identifier |
True |
False |
service_id |
string |
The identifier of the service for which this entry describes the service area |
False |
False |
service_area |
string |
The geographic area where a service is available. This is a free-text description, and so may be precise or indefinite as necessary. |
False |
False |
required_document
The required_document table contains details of any documents that are required in order to access or use services.
name |
required_document |
path |
required_documents.csv |
format |
csv |
mediatype |
text/csv |
Field Name |
Type (Format) |
Description |
Required? |
Unique? |
id |
string |
Each document must have a unique identifier |
True |
False |
service_id |
string |
The identifier of the service for which this entry describes the required document |
False |
False |
document |
string |
The document required to apply for or receive the service. e.g. ‘Government-issued ID’, ‘EU Passport’ |
False |
False |
fee
The fee table contains details of the costs of services, including those that are free
name |
fee |
path |
fees.csv |
format |
csv |
mediatype |
text/csv |
Field Name |
Type (Format) |
Description |
Required? |
Unique? |
id |
string |
Each entry must have a unique identifier |
True |
False |
service_id |
string |
The identifier of the service for which this entry describes the costs of service |
False |
False |
fee |
string |
A listing of the costs of services, including free ones |
False |
False |
payment_accepted
The payment_accepted table contains details of the methods of payment that can be used in order to pay for services
name |
payment_accepted |
path |
payments_accepted.csv |
format |
csv |
mediatype |
text/csv |
Field Name |
Type (Format) |
Description |
Required? |
Unique? |
id |
string |
Each entry must have a unique identifier |
True |
False |
service_id |
string |
The identifier of the services for which the entry describes the accepted payment methods |
False |
False |
payment |
string |
The methods of payment accepted for the service |
False |
False |
intepretation_services
The interpretation_services table contains details of the interpretation services which are available at a certain service.
name |
intepretation_services |
path |
interpretation_services.csv |
format |
csv |
mediatype |
text/csv |
Field Name |
Type (Format) |
Description |
Required? |
Unique? |
id |
string |
Each service must have a unique identifier |
True |
False |
service_id |
string |
The identifier of the services for which the entry describes the interpretation services available |
False |
False |
language |
string |
Languages, other than English, for which interpretation is available. Languages are listed as ISO639-1 codes. |
False |
False |
language
The language table contains details of the languages that are spoken at locations or services. This does not include languages which can only be used with intepretation.
name |
language |
path |
languages.csv |
format |
csv |
mediatype |
text/csv |
Field Name |
Type (Format) |
Description |
Required? |
Unique? |
id |
string |
Each language must have a unique identifier |
True |
False |
service_id |
string |
The identifier of the service for which the entry describes the languages in which services are delivered |
False |
False |
location_id |
string |
The identifier of the location for which the entry describes the languages in which services are delivered |
False |
False |
language |
string |
Languages, other than English, in which the service is delivered. Languages are listed as ISO639-1 codes. |
False |
False |
accessibility_for_disabilities
The accessibility_for_disabilities table contains details of the arrangements for access to locations for people who have disabilities
name |
accessibility_for_disabilities |
path |
accessibility_for_disabilities.csv |
format |
csv |
mediatype |
text/csv |
Field Name |
Type (Format) |
Description |
Required? |
Unique? |
id |
string |
Each entry must have a unique identifier |
True |
False |
location_id |
string |
The identifier of the location for which the entry describes the accessibility provision |
False |
False |
accessibility |
string |
Description of assistance or infrastructure that facilitate access to clients with disabilities. |
False |
False |
taxonomy
Each service can be categorized according to one or more taxonomy terms. The taxonomy table contains a list of taxonomy identifiers, their names, and, for hierarchical taxonomies, their structure.
name |
taxonomy |
path |
taxonomy.csv |
format |
csv |
mediatype |
text/csv |
Field Name |
Type (Format) |
Description |
Required? |
Unique? |
id |
string |
Each taxonomy entry must have a unique identifier. If combining multiple taxonomies with overlapping identifiers, use a prefix to distinguish them. |
True |
True |
name |
string |
The name of this taxonomy term or category. |
True |
False |
parent_id |
string |
If this is a child category in a hierarchical taxonomy, give the identifier of the parent category. For top-level categories, this should be left blank. |
False |
False |
parent_name |
string |
If this is a child category in a hierarchical taxonomy, give the name of the parent category. For top-level categories, this should be left blank. |
False |
False |