What is the format of the HSDS? Why CSV?

With the goal of broad accessibility in mind, the initial HSDS developer Sophia Parafina chose Comma-Separated Values (CSV) as the building blocks for HSDS. CSV serves as a ‘lowest common denominator’ that is simplest to use and most accessible to users with a modicum of technical abilities, as it can be edited in a simple text editor, and ingested by almost any information system. (For more reasoning behind this decision, consider Waldo Jaquith’s recent post, ‘In Praise of CSV.’)


For version 1.0, Parafina chose to accompany a more-complex set of CSV files with a JSON datapackage (using the Open Knowledge Foundation’s frictionless data specification) to describe the CSVs’ contents. In version 1.2, with support from Open Knowledge Foundation’s Frictionless Data Fund, Shelby Switzer upgraded the handling of JSON datapackages. 

Members of the Open Referral community have observed that they may need more structured data formats for use cases that involve complex, sensitive, and/or large-scale uses. We recognize the validity of these perspectives, and in fact we expect the HSDS model to evolve over time. Pilot projects and community members are already discussing plans to develop complementary formats (such as XML and JSON-LD) — and as these formats are field-tested and validated, they may become formal components of HSDS in future iterations.

Posted in: About the Human Service Data Specification