Human Services Data Specification v1.0The 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.Human Services Data Specification Roadmap -- Open 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 formatsCode for AmericaC4A_4600defa-65da-11e4-97ff-d43e955b75b0The development of Open Referral has to date been sponsored and funded by the Knight Foundation and Code for America.Referral ServicesAll 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.Service ProvidersHuman Services Information ProvidersGovernment EntitiesGovernment 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.Community OrganizationsBusinessesHelp SeekersHelp 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.ReferrersA 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), andthe 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.ResearchersA 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.Data AdministratorsA 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.I&R PractitionersA Common Vocabulary -- 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.Alliance of Information and Referral Systems AIRS 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."schema.orgschema.org for Public Civic Services -- 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 EligibilityOpen 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."National Information Exchange Model (NIEM)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.Knight FoundationKF_a1198cd6-ebbf-11df-ae5d-52537a64ea2aThe development of Open Referral has to date been sponsored and funded by the Knight Foundation and Code for America.Information is provided about many services to common and overlapping audiences._378b89c6-e566-11e5-83d2-363c514a5bbcTo establish a common vocabulary among information and referral (I&R) practitioners._378b8b38-e566-11e5-83d2-363c514a5bbcPrinciplesThe design of Human Services Data Specification is based on five principles: simplicity, factual, fidelity, provenance, and accessibility.SimplicityThe 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.FactualityThe 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.FidelityData 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.ProvenanceThe 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.AccessibilityThe data must be a machine readable and writable format that can be created, updated and deleted with a basic text editor.Search & DiscoveryProvision the minimum amount of data needed to implement a service for search and discovery of human services provided by organizations._378b8c28-e566-11e5-83d2-363c514a5bbc1_378b8dd6-e566-11e5-83d2-363c514a5bbcMachine ReadabilitySpecify a 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._378b8ea8-e566-11e5-83d2-363c514a5bbc2CSVProvide files in comma-separated value format._378b8f70-e566-11e5-83d2-363c514a5bbc2.1CSV 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.Phone NumbersUse E.164 number formatting for phone numbers._378b9056-e566-11e5-83d2-363c514a5bbc2.2Telephone Formatting -- HSDS 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.AddressesSpecify a standard addressing format._378b9128-e566-11e5-83d2-363c514a5bbc2.3Address Formatting -- At 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* address_4* city/locality* state/province/region* postal code* countryBecause of the variety of addressing systems, every field is composed of alphanumeric characters. The country field uses ISO-3166 alpha 2 codes.DescriptionsSupport HTML or MarkDown tags in description fields._378b922c-e566-11e5-83d2-363c514a5bbc2.4Description Field Formatting -- The description field may include HTML or MarkDown tags.Data ExchangeProvide a common data exchange format between different information and referral systems._378b933a-e566-11e5-83d2-363c514a5bbc3Data MappingProvide guidance on mapping fields and values._378b940c-e566-11e5-83d2-363c514a5bbc3.1Guidance on Mapping Fields and Values -- Source data may or may not map directly to the HSDS. Guidelines are listed below to reduce ambiguity.Required FieldsPermit null values for required fields._378b94e8-e566-11e5-83d2-363c514a5bbc3.1.1A null value is acceptable for required fields.Null EntitiesFor entities lacking values, permit omission of the corresponding CSV file._378b95d8-e566-11e5-83d2-363c514a5bbc3.1.2If there are no values for an entity, the corresponding CSV file can be omitted.Null ValuesPermit null values._378b96aa-e566-11e5-83d2-363c514a5bbc3.1.3A 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.Organization NamesPermit usage of the organization name for either or both location or service._378b9786-e566-11e5-83d2-363c514a5bbc3.1.4In 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.Entity MappingPermit mapping of entities to multiple other entities._378b989e-e566-11e5-83d2-363c514a5bbc3.1.5Mapping 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.ExtensionsPermit extension of the specification to incorporate additional fields or entities._378b998e-e566-11e5-83d2-363c514a5bbc3.1.6The 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.2016-03-08https://github.com/codeforamerica/OpenReferral/blob/master/Human%20Services%20Data%20Specification%20%20v1.0.mdOwenAmburOwen.Ambur@verizon.net