The Human Services Data Specification (Open Referral) is an exchange format for publishing machine readable data about health, human, and social services, their locations, and the organizations that provide them. For the purposes of this specification, human services are broadly defined, ranging from food assistance to job training and health care. This exchange format is meant to complement –not replace– existing storage formats currently in use.
All organizations that provide services or referrals, as well as entities that consume or distribute digital human services information, are invited to publish their data in this format, whether they be governments at the local, state, or federal level; civic organizations, or companies.
The primary use case served by Open Referral is the provision of information about many services to a common or overlapping audience.
Government entities, community organizations, and businesses often face difficulty obtaining timely and correct data about human services. The Human Services Data Specification facilitates the open exchange and use of data and information among these stakeholders. To that end, the specification is designed to provide an interoperable format for web and application developers.
The development of Open Referral has to date been sponsored and funded by the Knight Foundation and Code for America. Learn more about Code for America’s support of data standards here.
Section 1: About the Human Services Data Specification
Human Services Data Specification Roadmap
Human Services Data Specification Data Capabilities
Section 2: Producing Compliant Data
Guidance on Mapping Fields and Values
Section 3: Document Status
Appendix A
A Controlled Vocabulary for Human Services Data
Appendix B
Appendix C
Appendix D
## Related Standards
The AIRS Standards defines expected practices within an information and referral (I&R) program and best practices to meet the needs of their community. According to AIRS Standards and Quality Indicators for Professional Information and Referral:
"The Standards address all aspects of an I&R operation. They define the information and referral process in concrete terms; establish criteria for database development; mandate support for community planning activities; incorporate a broad view of collaboration at the local, state or provincial, regional and national levels; include provisions for the socially responsible use of technology; and describe the role of information and referral services in times of disaster. “
The Resource Database Standard of the AIRS Standards is pertinent to the Human Services Data Specification. As described in the AIRS Standards and Quality Indicators publication, the Resource Database Standard:
"The Resource Database standards require that the I&R service develop, maintain, use and disseminate an accurate, up-to-date resource database that contains information about available community resources including details about the services they provide and the conditions under which services are available. The database includes resources that support the inquirer’s right to accurate, consistent, comprehensive and unbiased information and the ability of the I&R service to be a non-partisan, non-ideological and impartial information source for available nonprofit, government and for-profit services that meet the organization’s inclusion/exclusion criteria. The database is maintained by trained resource specialists."
Public Civil Services is a W3C proposal by the Google.org Social Impact team that extends the Schema.org schemas to better support the description of public civic services.
It is a new vocabulary, similar to the European Commission ISA Core Public Service vocabulary. Its purpose is to improve search engines’ understanding of these services. The schema will provide "enough information to determine the service, the area covered by the service, and relevant information for using the service."
Open Eligibility is a "simple way to categorize human services and human situations." It uses common categories for quickly finding human services for people in need, service providers and navigators. It takes a different approach than the AIRS standards by grouping similar services and repeatedly and empirically testing the categories. Open Eligibility explains their taxonomy as:
"Every provider administers at least one program. Every program provides at least one client-facing service. And every service is represented with a service tag. Our taxonomy is a categorization of those service tags."
NIEM is the National Information Exchange Model. It is an interagency initiative to create a national-level interoperable information sharing and data exchange. The NIEM project began in 2005 as a joint venture between the U.S. Department of Homeland Security (DHS) and the U.S. Department of Justice (DOJ). The NIEM uses both the Global Justice XML Data Model (GJXDM) reference model and the GJXDM XML-based framework and support infrastructure.
NIEM consists of a collection of data components organized in multiple kinds of XML Schema that are classified into broad categories. Of interest to the Human Services Data Standard are the NIEM Core Components. There are two types of NIEM Core components:
- Universal components such as Person, Date, Location etc., that are relevant and understood across all domains
- Common components such as LocationStateUSPostalServiceCode, LocationStateCanadianProvinceCode etc., that are relevant and understood across two or more domains
The schema for the core components is available from niem.gov.
## Use Cases
Help seekers (i.e. patients, clients, consumers, victims, survivors, etc.) have a need (or multiple needs) that can be addressed by services in their community. To find services, help seekers must receive accurate, relevant, and easily understandable information about services which they can access and for which they are eligible.
Help seekers may not be capable of articulating the addressable aspect of their needs. They may have limited media literacy and limited access to technology. They may not know about the existence of relevant services, let alone the ‘correct’ terms to describe those services. They may have difficulty processing and/or trusting information. They may struggle with anticipated or actual stigmatization for seeking help. Incorrect information can cost help-seekers time, money, or even conceivably lives.
Help seekers might currently look for help by searching the Internet or turning to a trusted community anchor like a library, school, or religious institution. They might talk to a service provider ("referrer") who can help identify addressable needs (through some screening process) and provide them with actionable information about services.
As a help-seeker, I want to find services that meet my needs.
A Referrer is the person who engages directly with a help-seeker (often face-to-face) and helps them find relevant and accessible services. A ‘referrer’ is usually (but not always) a professional or a volunteer who is working for an organization that itself provides as a service to its community (i.e. case manager, social worker, health worker, EMT, patient intake, librarian, teacher, etc.). Referrers are typically the primary users of resource directory information systems.
Referrers require:
- accurate information,
- the service’s relevance (is the client eligible), and
- the quality of the service.
Referrers commonly interact with help seekers using a structured workflow that includes a screening process to identify important attributes of the help-seeker’s situation. Referrers match information gathered from the help-seeker to accessible and relevant services.
As a referrer (aka service provider, etc), I want to provide relevant and accurate information about services.
A Researcher uses service directory data, in synthesis with other kinds of data, for the purpose of understanding community health, predicting future needs, identifying funding gaps, and other kinds of analysis. Such a role is often played by funders, policymakers, planners, or community leaders.
Researchers study the effectiveness of programs, which may not be specific services but rather a set of services bundled through a funding stream and around a common mission. Researchers seek accountability for the performance of the health, human, and social service system overall. They want their work to make this data useful for system-level decision-making. Researchers need reliably structured data, from across institutional and jurisdictional boundaries, that can be readily ‘mashed up’ with other kinds of data (census, funding, etc).
As a researcher, I need data in raw formats over a specific time period and meaningful context for service information so that I can perform efforts-to-outcomes and population-level analysis.
A Data Administrator is responsible for information systems that are a compilation of directories. Data administrators produce and maintain information; tasks include updating records, maintaining naming conventions, running reports, designing mechanisms for retrieval and delivery, etc. They may be responsible for reporting directly to funders and government agencies. These responsibilities are sometimes shared among several roles in an organization.
As a data administrator, I want a data maintenance process flow enabled by a simple and easy to use interface to update data quickly and efficiently.
## Design Principles
The design of Human Services Data Specification is based on five principles: simplicity, factual, fidelity, provenance, and accessibility.
The underlying model is simple, consisting of four entities and associated properties that support who, what, where and when questions. The relationships between the entities are flexible and can model the majority of use cases for human services data. The goal is to build the simplest useful thing.
The data provided in the Human Services Data Specification are factual. This means that the information is verifiable and can be reproduced across different systems and applications.
Data fidelity is important. Data reproduced and used across different information systems must retain the same meaning and be represented in a consistent way. Implementing fidelity leverages the use of existing standards such as ISO time and date formats.
The standard must include information about the provenance of the data as well as a history of changes in order to provide an authoritative source. The standard supports column level metadata for a high degree of granularity.
The data must be a machine readable and writable format that can be created, updated and deleted with a basic text editor.
## Human Services Data Specification RoadmapOpen Referral does not yet incorporate the full range of data necessary to meet domain specific use cases. Specifically, the working group intends to address the following topics.
- Acceptance of initial specification with regards to content, data type, and format
- Process for receiving, validating, and incorporating user input
- Develop a long term roadmap leading to the 1.0 release
- Develop process for creating domain specific profiles and incorporating taxonomy
- Develop process for creating wire formats
The Human Services Data Specification seeks to establish a common vocabulary among information and referral (I&R) practitioners. The vocabulary reflects the simple model of four required entities: Organizations, Locations, Services, and Metadata. An optional entity is Programs, which is available for organizations that use Programs for grouping Services. Entities have attendant properties and some properties are complex and have multiple attributes. For example addresses are comprised of several pieces of information..
The relationship between organizations as the primary entity and services and locations as subordinate entities is loosely coupled in recognition that service providers may organize the data in different ways and that human services continue to evolve. For example, some services such as virtual support groups or informational websites may not have a physical location.
## Current Human Services Data Capabilities
The specification supports:
- Provisioning the minimum amount of data needed to implement a service for search and discovery of human services provided by organizations
- Machine readable format that can be imported directly into a relational database or viewed and edited using commonly available software such as a spreadsheet or a text editor
- A common data exchange format between different information and referral systems.
To promote participation and accessibility, this Google Document serves as the working draft of the next version of Human Services Data Specification. Edits, improvements and changes should first be discussed using the Comments feature.
Subsequent to publishing version 1.0, the specification will not change for a given period of time, to be determined by the Working Group. This will allow data producers and consumers to reliably build upon the specification.
This working document--and the complementary Google Group-- will continue to serve as a forum for discussion and feedback. These conversations will inform the future evolution of the specification.
### CSV Formatting
For ease of data production, Human Services Data Specification specifies that all files are provided in a simple comma-separated value format (.csv). The CSV format described herein conforms to RFC4180. Text will used the UTF-8 character set.
### Telephone FormattingHSDS uses E.164 number formatting for phone numbers E.164 numbers can have a maximum of fifteen digits and are usually written as follows: [+][country code][subscriber number including area/region code]. Phone numbers can contain delimiters.
### Address FormattingAt the time this document was drafted, a standard addressing format has not been established. ISO 19160 is in the preliminary stages of an addressing standard but has not yet produced a standard. Based on address standards by country from the Universal Postal Union, the following format will capture the majority of addresses in use globally.
address_1
address_2
address_3
adderss_4
city/locality
state/province/region
postal code
country
Because of the variety of addressing systems, every field is composed of alphanumeric characters. The country field uses ISO-3166 alpha 2 codes.
### Description Field FormattingThe description field may include HTML or MarkDown tags.
### Guidance on Mapping Fields and ValuesSource data may or may not map directly to the HSDS. Guidelines are listed below to reduce ambiguity.
- A null value is acceptable for required fields.
- If there are no values for an entity, the corresponding CSV file can be omitted.
- A data source may have a field that can map to an HSDS field but in many cases are not populated. A null value is acceptable.
- In some cases, such as name, using the organization name for either or both location or service is acceptable. This is up to the discretion of the data producer.
- Mapping a field is at the data producer’s discretion, but it is acceptable for some entities to map to multiple entities, for example an organization, service, or location can have a contact.
- The HSDS is a baseline of data, if the the data producer’s has additional fields or entities that they wish to add, the specification can be extended to incorporate them. The data producer should provide documentation of how the specification has been extended.
### Version
This is version 0.9 of the specification.
### CopyrightHuman Services Data Specification is licensed under the CC0 license, which is the "no copyright reserved" option in the Creative Commons toolkit - it effectively means relinquishing all copyright and similar rights that you hold in a work and dedicating those rights to the public domain. To view a copy of this license, visit Creative Commons License.
### Changelog
No changes.
- Changes from comment period, workshop comments, and a running summary of comments.
- Directly references RFC4180 for CSV formatting
- Added related standards
- Aded use cases based on persona
- Reformatted the controlled vocabulary.
- Added a logical model
- Made changes from comments collected during the second RFC period
- Added Appendix C: Tabular Data Package description
- Refined logical model to conform to Boyce-Codd third normal form
- Updated datapackage.json to match logical model
- Included enumerations for entities in datapackage.json
- Added section on NIEM and relation to specification
- Made changes based on reviewer comments.
- Updated data model based on reviewer comments
- Tested logical model by importing data from iCarol database
- Exported data in HSDS format from previous tes
- Added Open Eligibility taxonomic overlay to logical model using Postgres ltree
- Tested OE taxonomy by querying the service_taxonomy to return the related service
- Provided test scripts and example data
- Added formatting specification for address, phone, description
- Changes based on public comments in v0.8 include:
- revising revising schedule entities and attributes as recommended,
- grammatical and punctuation edits,
- changing SMS attribute to a phone type
- changed language_line to interpretation_services
- Released on github as a markdown document
- Added a datapackage.json example on github
- Final version
- Changed relationship between location and service from 1:n to n:m
### A Controlled Vocabulary for Human Services Data
| Term | Description | Example | Required, Recommended or Optional |
| Accessibility for Disabilities | Description of assistance or infrastructure that facilitate access to clients with disabilities. | wheelchair | recommended |
| Accreditation | Accreditation is the formal evaluation of an organization or program against best practice standards set by an accrediting organization. | Child and Youth Development Program | optional |
| Alternate Name | Alternative or commonly used name for an organization, program, service, or location. | MSWC Pre-Natal Program | recommended |
| Application Process | The steps needed to access the service. | Call for appointment with counselor. | recommended |
| Attention | An address can have an 'Attention' label to specify the recipient. | Joshua Fisher | optional |
| City | The city where the Organization, Service or Location resides. | Redwood City | required |
| Closes At | Time when a service or location is closed | 2013-11-05T13:15:30Z | optional |
| Closed | Indicates if a service or location is closed during a public holiday | true | required |
| Contact | A person associated with an organization or service. | April Smith | recommended |
| Country | The country where the Organization, Service or Location is located. Uses ISO 3361-1 country codes (two letter abbreviations) | US | required |
| Country Code Prefix | The country code prefix of the phone. | 19 | optional |
| Last Action Date | The date when information was created,updated, or deleted | 2013-11-05T13:15:30Z | required |
| Department | The department that the contact works in. | Human Resources | optional |
| Description | A brief summary about the organization, location or service. It can contain markup such as HTML or Markdown. | Haven for Hope assists homeless individuals find housing and employment. | required |
| Required Document | Document required to apply for or receive service. | Government issued identification card | optional |
| Eligibility | Rules or guidelines that determine who can receive the service. | teen | recommended |
| Email for organization or service | [email protected] | recommended | |
| End Date | The last day that a service or location is closed during a public or private holiday | 2013-11-05T | required |
| Extension | Phone extension | 210 | optional |
| Fee | A listing of the costs of services. | free - school immunization | recommended |
| Field Name | Name of field modified | license | required |
| Funding | Source of funds for organization or service | Philanthropic Ventures | optional |
| Regular Schedule | Time and days when the service is available to the public. | 2013-11-05T13:15:30Z | optional |
| Holiday Schedule | Time and days when the service is available to the public during public holidays or other events | 2013-11-05T13:15:30Z | optional |
| Id | Each organization, address, contact, phone and metadata record has a unique identifier. | BEC0BA53-4A24-400F-8F05-A24831D54618 | required |
| Interpretation Service | AA phone translation service at a service provider. Languages are listed as ISO639-1 codes. | es | optional |
| Language | Languages, other than English, in which the service is delivered. Languages are listed as ISO639-1 codes. | es | recommended |
| Last Action Timestamp | Timestamp when data was changed. | 2013-11-05T13:15:30Z | required |
| Last Action Type | The kind of change made to the data create,update, delete | delete | required |
| Latitude | Y coordinate of location expressed in decimal degrees in WGS84 datum. | -93.35556 | recommended |
| Legal Status | The legal status defines the conditions that an organization is operating under; e.g. non-profit, private corporation or a government organization. | non-profit | optional |
| License | An organization may have a license issued by a government entity to operate legally. | food handler license | optional |
| Location Id | Each service can include a location referenced by a Location.Id | 1CB7893F-86A1-49FD-9193-87C233E2ADB2 | required |
| Longitude | X coordinate of location expressed in decimal degrees in WGS84 datum. | recommended | recommended |
| Opens At | Time when a service or location is open | 2013-11-05T13:15:30Z | optional |
| Physical Address | A physical address describes the location of a service or organization. | 1510 South Hackberry San Antonio, TX 78210 | recommended |
| Postal Address | A postal address describes where a service or organization receives mail. | 1510 South Hackberry San Antonio, TX 78210 | recommended |
| Payment Accepted | The kind of payment accepted for a service. | Medicare | recommended |
| Name | The official or public name of the organization, service, program, location, or contact | Haven for Hope | required |
| Replacement Value | The replacement value | Happy House | required |
| Organization Id | The organization.Id is the unique identifier for an organization | BEC0BA53-4A24-400F-8F05-A24831D54618 | required |
| Contact Id | contact.Id is the unique identifier for a contact | 388BD194-5731-4D66-B8FC-F48A84DDD1FC | optional |
| Phone | The phone number used to contact an organization, service, or location. | 210-512-3345 | required |
| Postal Code | The postal code that the Organization, Service or Location resides. Zip+4 is optional in the US. | 99043 | required |
| Previous Value | The value that has been updated | Happy Shining House | required |
| Resource Id | Each service, program. location, address, or contact will have a unique identifier. Unique ids are UUIDs. | 8BBE1753-97EF-4683-BB93-CA7A32D59A58 | required |
| Service Area | The geographic area where a service is available. | ||
| Service Id | The service.id is the unique identifier for a service | 8BBE1753-97EF-4683-BB93-CA7A32D59A58 | required |
| Start Date | The first day that a service or location is closed during a public or private holiday | 2013-11-01 | required |
| Source | Source of funding | Private Foundation Grant | optional |
| State/Province | The state (or province) that the Organization, Service or Location resides. Uses ISO 3361-2 state codes (two letter abbreviations), for example in the US and Canada | CA | required |
| Status | The current status of the service. | active | required |
| Address_1 | This property contains the street number, prefix, street name, and suffix. | 2022 S. Palmetto Ave | required |
| Address_2 | This property contains additional address information such as the suite. | Suite 201 | optional |
| Address_3 | This property contains additional address information. | optional | |
| Address_4 | This property contains additional address information. | optional | |
| Tax Id | The tax.id is a government issued identifier used for the purpose of tax administration. | 12-3456789 | optional |
| Taxonomy id | Taxonomy terms related to a service | optional | |
| Tax Status | Government assigned tax designation. for tax-exempt organ | charitable tax exempt organization | optional |
| Title | Title of the contact. | Director | optional |
| Transportation | Access to public or private transportation to and from the location. | Bus 20 stop at corner of Hackberry and Pine. | recommended |
| Updated By | The name of the person who updated a value | Johnson Henry | required |
| Previous Value | The previous value of a field that has been updated | Center for Children | required |
| Wait time | Time a client may expect to wait before receiving a service. | 1 hour | optional |
| URL | URL of the organization or a service | htttp://havenforhope.org/ | optional |
| Weekday | Day of the week that service or location is open. | Monday | required |
| Year Incorporated | Date when organization was legally formed as a corporation. | 1970 | optional |
### Logical Model
- Note that although the relationships are not depicted, metadata.resource_id is the foreign key to all entities
| Entity | Attributes |
| organization | id name alternate_name description url tax_status tax_id year_incorporated |
| program | id organization_id name alternate_name |
| service | id organization_id program_id location_id name alternate_name description url status application_process wait_time |
| service_at_location | id service_id location_id url |
| location | id organization_id name alternate_name transportation latitude longitude description |
| phone | id service_id organization_id contact_id number extension type department country_prefix |
| contact | id organization_id service_id name title department |
| physical_address | id location_id attention address_1 address_2 address_3 address_4 city state_province postal_code country |
| postal_address | id location_id attention address_1 address_2 address_3 address_4 city state_province postal_code country |
| regular_schedule | id service_id location weekday opens_at closes_at |
| holiday_schedule | id service_id location_id opens_at closes_at closed start_date end_date |
| metadata | id resource_id last_action_date last_action_type field_name previous_value replacement_value updated_by |
| accreditation | id organization_id accreditation |
| license | id organization_id license |
| funding | id organization_id service source |
| eligibility | id service_id eligibility |
| service_area | id service_id service_area |
| required_document | id service_id document |
| fee | id service_id fee |
| payement_accepted | id service_id payment |
| interpretation_services | id service_id language |
| language | id service_id location_id language |
| accessibility_for_disabilities | id location_id accessibility |
| meta_table_description | id name language character_set |
### Tabular Data Package
The data will be in CSV formatted files with one CSV file per entity. This is the minimum requirement for distributing data. The recommended format for distributing data is the Tabular Data Package which is composed of the data in CSV files and a metadata file, called datapackage.json, that stores the schema in a JSON file using the Data Package format.
A CSV file is required for each entity in the logical model. The files and their associated attributes are listed below.
| File | Attributes | Required/Optional |
| organization.csv | id name alternate_name description email url legal_status tax_status tax_id year_incorporated | required |
| program.csv | id organization_id name alternate_name | required |
| service.csv | id organization_id program_id location_id name alternate_name description url email status application_process wait_time | required |
| service_at_location.csv | id service_id location_id url email | required |
| location.csv | id organization_id name alternate_name transportation latitude longitude description | required |
| phone.csv | id location_id service_id organization_id contact_id number extension number_type department country_prefix | required |
| contact.csv | id organization_id service_id name title department email | required |
| physical_address.csv | id location_id attention address_1 address_2 address_3 address_4 city state_province postal_code country | required |
| postal_address.csv | id location_id attention address_1 address_2 address_3 address_4 city state_province postal_code country | required |
| regular_schedule.csv | id service_id location weekday opens_at closes_at | optional |
| holiday_schedule.csv | id service_id location_id opens_at closes_at closed start_date end_date | optional |
| metadata.csv | id resource_id last_action_date last_action_type field_name previous_value replacement_value updated_by | recommended |
| accreditation.csv | id organization_id accreditation | optional |
| license.csv | id organization_id license | optional |
| funding.csv | id organization_id service_id source | optional |
| eligibility.csv | id service_id eligibility | required |
| service_area.csv | id service_id service_area | required |
| required_document.csv | id service_id document | required |
| fee.csv | id service_id fee | required |
| payment_accepted.csv | id service_id payment | required |
| interpretation_services.csv | id service_id language | required |
| language.csv | id service_id location_id language | required |
| accessibility_for_disabilities.csv | id location_id accessibility | required |
| meta_table_description.csv | id name language character_set | optional |
The datapackage.json file contains general metadata such as the name of the package, date published, publisher, etc. It also includes a list of the CSV files included along with the schema. The data types used in the schema are defined in the JSON Table Schema.
The following is the schema for the logical data model in the datapackage.json file.
{
"name": "human_services_data",
"title": "Human Services Data",
"license": [
{
"url": "http://opendatacommons.org/licenses/pddl/",
"name": "Open Data Commons Public Domain",
"version": "1.0",
"id": "odc-pddl"
}
],
"resources": [
{
"name": "organization",
"path": "organization.csv",
"format": "csv",
"mediatype": "text/csv",
"schema": {
"fields": [
{
"name": "id",
"type": "string"
},
{
"name": "name",
"type": "string"
},
{
"name": "alternate_name",
"type": "string"
},
{
"name": "description",
"type": "string",
"format": ""
},
{
"name": "email",
"type": "string"
},
{
"name": "url",
"type": "string"
},
{
"name": "tax_status",
"type": "string"
},
{
"name": "tax_id",
"type": "string"
},
{
"name": "year_incorporated",
"type": "date",
"format": "yyyy"
},
{
"name": "legal_status",
"type": "string"
}
],
"primaryKey": "id"
}
},
{
"name": "program",
"path": "program.csv",
"format": "csv",
"mediatype": "text/csv",
"schema": {
"fields": [
{
"name": "id",
"description": "",
"type": "string"
},
{
"name": "organization_id",
"description": "",
"type": "string"
},
{
"name": "name",
"description": "",
"type": "string"
},
{
"name": "alternate_name",
"description": "",
"type": "string"
}
],
"primaryKey": "id",
"foreignKeys": [
{
"fields": "organization_id",
"reference": {
"resource": "organization.csv",
"fields": "id"
}
}
]
}
},
{
"name": "service",
"path": "service.csv",
"format": "csv",
"mediatype": "text/csv",
"schema": {
"fields": [
{
"name": "id",
"description": "",
"type": "string"
},
{
"name": "organization_id",
"description": "",
"type": "string"
},
{
"name": "program_id",
"description": "",
"type": "string"
},
{
"name": "location_id",
"description": "",
"type": "string"
},
{
"name": "name",
"description": "",
"type": "string"
},
{
"name": "alternate_name",
"description": "",
"type": "string"
},
{
"name": "url",
"description": "",
"type": "string"
},
{
"name": "email",
"description": "",
"type": "string"
},
{
"name": "status",
"description": "",
"type": "string",
"values": ["active", "inactive", "defunct", "temporarily closed"]
},
{
"name": "application_process",
"description": "",
"type": "string"
},
{
"name": "wait_time",
"description": "",
"type": "string"
}
],
"primaryKey": "id",
"foreignKeys": [
{
"fields": "organization_id",
"reference": {
"resource": "organization.csv",
"fields": "id"
}
},
{
"fields": "program_id",
"reference": {
"resource": "program.csv",
"fields": "id"
}
},
{
"fields": "location_id",
"reference": {
"resource": "location.csv",
"fields": "id"
}
}
]
}
},
{
"name": "service_at_location",
"path": "service_at_location.csv",
"format": "csv",
"mediatype": "text/csv",
"schema": {
"fields": [
{
"name": "id",
"description": "",
"type": "string"
},
{
"name": "location_id",
"description": "",
"type": "string"
},
{
"name": "url",
"description": "",
"type": "string"
},
{
"name": "email",
"description": "",
"type": "string"
}
],
"primaryKey": "id",
"foreignKeys": [
{
"fields": "service_id",
"reference": {
"resource": "service.csv",
"fields": "id"
}
},
{
"fields": "location_id",
"reference": {
"resource": "location.csv",
"fields": "id"
}
}
]
}
},
{
"name": "location",
"path": "program.csv",
"format": "csv",
"mediatype": "text/csv",
"schema": {
"fields": [
{
"name": "id",
"description": "",
"type": "string"
},
{
"name": "organization_id",
"description": "",
"type": "string"
},
{
"name": "name",
"description": "",
"type": "string"
},
{
"name": "alternate_name",
"description": "",
"type": "string"
},
{
"name": "transportation",
"description": "",
"type": "string"
},
{
"name": "latitude",
"description": "",
"type": "float"
},
{
"name": "longitude",
"description": "",
"type": "float"
}
],
"primaryKey": "id",
"foreignKeys": [
{
"fields": "organization_id",
"reference": {
"resource": "organization.csv",
"fields": "id"
}
},
{
"fields": "service_id",
"reference": {
"resource": "service.csv",
"fields": "id"
}
}
]
}
},
{
"name": "phone",
"path": "phone.csv",
"format": "csv",
"mediatype": "text/csv",
"schema": {
"fields": [
{
"name": "id",
"description": "",
"type": "string"
},{
"name": "location_id",
"description": "",
"type": "string"
},
{
"name": "service_id",
"description": "",
"type": "string"
},
{
"name": "organization_id",
"description": "",
"type": "string"
},
{
"name": "contact_id",
"description": "",
"type": "string"
},
{
"name": "number",
"description": "",
"type": "string"
},
{
"name": "extension",
"description": "",
"type": "number"
},
{
"name": "type",
"description": "",
"type": "string"
},
{
"name": "department",
"description": "",
"type": "string"
}
],
"primaryKey": "id",
"foreignKeys": [
{
"fields": "organization_id",
"reference": {
"resource": "organization.csv",
"fields": "id"
}
},
{
"fields": "location_id",
"reference": {
"resource": "location.csv",
"fields": "id"
}
},
{
"fields": "service_id",
"reference": {
"resource": "service.csv",
"fields": "id"
}
},
{
"fields": "contact_id",
"reference": {
"resource": "contact.csv",
"fields": "id"
}
}
|
### Taxonomy
The Human Services Data Specification is agnostic with regards to taxonomy or any other method of classification or categorization of services. Data providers may have an existing taxonomy that they wish to include with their services data.
Taxonomies are often hierarchical, such as AIRS. A common way of representing hierarchy in relational databases and in flat files is materialized paths. They are a very common pattern for flattening a hierarchical structure into list, for example the URL in a browser is a materialized path. Materialized paths stores each element in a full path all the way to the root element, e.g. ‘fruit.apple.golden delicious’. Because materialized paths are such a common pattern, many relational (Oracle, MS SQLServer, MySQL, Postgres and nosql (MongoDB) databases implement it and provide a domain specific language to handle hierarchical data.
The elements in the hierarchy are separated by periods or ".", e.g. ‘emergency.disaster_response’.
| File | Attributes |
| service_taxonomy.csv | id organization_name organization_id service_name service_id taxonomy taxonomy_id |
| id | organization_name | organization_id | service_name | service_id | taxonomy | taxonomy_id |
| 16478826-2010-44af-94c2-ca012144e78e | AMERICAN RED CROSS BAY AREA CHAPTER, SAN MATEO COUNTY OFFICE | 3f85b68d-d9b6-4dd3-b7a2-a7bd224214ad | DISASTER PREPAREDNESS, RESPONSE AND ASSISTANCE SERVICES | 9096bb54-2edc-4d07-80c6-d70eff6e40b3 | emergency.disaster_response | 89 |