I’m needing to quantify some of the work that has occurred around my Human Services Data Specification work as part of a grant we received from Stanford. The grant shas helped us push forward almost three separate revisions of the API definition for working with human services data, and one of the things I’m needing to do is quantify the work that has occurred specifically around the OpenAPI definitions. At this point the specification is pretty verbose, and is now spanning multiple documents, making it difficult to quantify and share within an executive summary. To help support I wanted to craft some language that could help introduce the value that has been created to a non-technical audience.
The Human Services Data Specification (HSDS) provides the common schema for accessing, storing, and sharing of human data, providing a machine readable definition that human service practitioners can follow in their implementations. The Human Services Data API (HSDA) takes this schema, and provides an API definition for accessing, as well as adding, updating, and deleting data using a web API. While there are a growing number of code projects emerging that support HSDS/A, the center of the project is a set of OpenAPI definitions that outline the finer details of working with human services data via a web API.
With the assistance of the grant from Stanford, Open Referral was able to move forward the HSDA specification from version 1.0, to 1.1, 1.2, and now we are looking at delivering version 1.3 of the specification before end of 2017. The core OpenAPI definition for HSDA provides guidance for the design of human services APIs, with a focus on the core set of resources needed to operate a human services project. There are the handle of core resources defined as part of what is called HSDA core:
- Organizations (OpenAPI Definition) - Providing a framework for adding, updating, reading, and deleting organizational data. Describing the paths, parameters, and HSDS schema required to effectively communicate around organizations delivering human services.
- Locations (OpenAPI Definition) - Providing a framework for adding, updating, reading, and deleting location data. Describing the paths, parameters, and HSDS schema required to effectively communicate around specific locations that provide human services.
- Services (OpenAPI Definition) - Providing a framework for adding, updating, reading, and deleting services data. Describing the paths, parameters, and HSDS schema required to effectively communicate around specific human services.
- Contacts (OpenAPI Definition) - Providing a framework for adding, updating, reading, and deleting contact data. Describing the paths, parameters, and HSDS schema required to effectively communicate around contacts associated with organizations, locations, and services delivering human services.
This is considered to be the HSDA core specification, focusing on exactly what is needed to manage organizations, locations, services, and contacts involved with human services, and nothing more. As of version 1.2 of the specification we have spun off several additional specifications, which support the HSDA core specification, but are meant to reduce the complexity of the core specification. Here are seven additional projects we’ve managed to accomplish as part of our recent work:
- HSDA Search (OpenAPI Definition) - A machine readable API definition for searching across organizations, location, services, and contacts, as well as their sub-resources.
- HSDA Bulk (OpenAPI Definition) - A machine readable API definition dictating how bulk operations around organizations, location, services, and contacts can occur, minimizing the impact of core systems.
- HSDA Meta (OpenAPI Definition) - A machine readable API definition describing all the meta data in use as part of any HSDA implementation, providing a history of everything that has occurred.
- HSDA Taxonomy (OpenAPI Definition) - A machine readable API definition for managing one or more taxonomies in use, and how these taxonomies are applied to core organizations, locations, services, and contacts.
- HSDA Management (OpenAPI Definition) - A machine readable API definition for the management level details of operating an HSDA implementation, providing guidance for user access, application management, service usage, and authentication and logging for the HSDA meta system.
- HSDA Orchestration (OpenAPI Definition) - A machine readable API definition for orchestration data exchanges between HSDA implementations, allowing for schedule or event based integrations to be executed, involving one or many HSDA implementations.
- HSDA Validation (OpenAPI Definition) - A machine readable API definition for validating an HSDA implementation follows the API and data schema, providing a validation API that can be used keep any platform compliant.
The Stanford grant has allowed us to move forward HSDA three separate versions, but has also given us the time to properly break down HSDA into sensible, pragmatic services that do one thing, and does it well. The OpenAPI specifications provide a machine readable blueprint that can be used by any city, county, or other organization to define, implement, and manage their human services implementation, keeping it in sync with Open Referrals guidance. Each of the OpenAPI definitions provide a distilled down version of Open Referral guidance that anyone can follow within individual operations–designed for both business and technical users to adopt.
The HSDA specification is defined using OpenAPI, which is an open source specification format for defining web APIs, which is now part of the Linux Foundation. OpenAPI allows us to define HSDA using JSON Schema, but then also allows us to define how that schema is used as part of API requests and responses. It provides a YAML or JSON definition of the HSDA core, as well as each individual project. These definitions are then used to design, deploy, and manage individual API implementations, including providing documentation, code libraries, testing, and other essential aspects of operating an API that supports web, mobile, device, voice, spreadsheet, and other types of applications.
Hopefully this breaks down how the HSDA OpenAPI specifications are central to what Open Referral is doing. It provides the guidance that other human service providers can follow, going beyond just the data schema, and actually helping ensure access across many different implementations can work in concert. The HSDA OpenAPIs act as a set of rules that can guide individual implementations, while also ensuring their interoperability. When each human services provider adopts one of the HSDA specifications they are establishing a contract with their API consumers and application developers, promising they’ll deliver against this set of rules, ensuring their API will speak the same language as other human service APIs that also speak HSDA. This is the objective of Open Referral, and why we use OpenAPI as the central definition for everything we do.
