search

codeforamerica / ohana-api

The open source API directory of community social services.
http://ohana-api-demo.herokuapp.com/api
BSD 3-Clause "New" or "Revised" License
185 stars 344 forks source link

Update spreadsheet example to match 0.8 spec #298

Closed pmackay closed 9 years ago

pmackay commented 9 years ago

It seems the example tab names on https://docs.google.com/spreadsheets/d/1qkysLj5MAAvaysuac_9H0hOvTAb1aJEMhUVJAECmj2c/edit#gid=1983571683 are plural but the current spec is now singular. Plus there seem to be more tabs :)

monfresh commented 9 years ago

The convention for naming a table that holds many entries (in a database for example) is to give it the plural form. I think the spec is the one that should be updated to use the plural form.

As for "there seem to be more tabs", could you be more specific please? Are you saying the template has more tabs than the spec? If so, which ones?

pmackay commented 9 years ago

Looking at Appendix B of the current spec, there have been extra tables added, such metadata, accreditation, license, funding, etc. Below that the Tabular Data Package lists singular names for the CSV files as does the example datapackage.json.

Can you give some more info on how the process works for how HSDS and Ohana are updated? Does Ohana follow HSDS changes? I agree with the point about plural naming, should that be fed back to HSDS?

I raised this and #297 because I've spent some time looking at stuff related to validation and packaging and hence noticed the spec and Ohana are not currently in sync.

monfresh commented 9 years ago

Ohana and HSDS are both in development, and constantly changing and evolving as we work toward a 1.0 release. Ohana is not tracking or matching every release of HSDS. In some cases, Ohana has made design decisions that differ from HSDS, and I've made those recommendations to HSDS. Some of those recommendations have been accepted but not updated yet. Others are still being discussed. Once we all come to an agreement and HSDS 1.0 is released, Ohana will be updated and Ohana 1.0 will be released.

I noticed that you're already part of the OpenReferral Google group, but perhaps you missed a recent discussion we've had about how to deal with tables like accreditation, funding, licenses, etc.. My argument is that they should be columns within the main tables they are associated with. For example, if you look at the CSV template I created, and this Wiki article, you'll notice that accreditations is a column inside the Organizations table as opposed to being a separate table.

As for the metadata table, it is not currently supported in Ohana. If you want to be able to track changes in Ohana, you'll have to install and configure the PaperTrail gem on your own, as mentioned in this Wiki article: https://github.com/codeforamerica/ohana-api/wiki/Tracking-changes-to-the-data-in-the-database

pmackay commented 9 years ago

Just to check, would this also be an issue more appropriate for OR? Would the spreadsheet example belong to the spec, rather than Ohana?

monfresh commented 9 years ago

Good question. I guess it could belong to either one, but probably this repo since I originally created it to help people prepare data for importing here. However, I would wait until HSDS 1.0 is released before opening any issues against the spreadsheet. I'm fairly confident that the spreadsheet already reflects what will be specified in 1.0.

monfresh commented 9 years ago

I've updated the API with the latest field name changes in the OpenReferral spec, and I've updated the CSV Wiki with a note that there are currently a few differences between the spec and the API. Those differences only affect those who already have data and have already converted it to OpenReferral CSV files.

The Google spreadsheets template that I created is meant for people producing data from scratch, and that template is meant to be compatible with Ohana API. The two main issues you originally brought up (pluralized versus singular file names, and the various single-attribute tables) I still maintain are Open Referral issues that need to be resolved there. I've opened those issues against OpenReferral 1.0: https://github.com/codeforamerica/OpenReferral/issues/78 and https://github.com/codeforamerica/OpenReferral/issues/76.

So, since the issue was originally opened against the spreadsheet, which is meant to be Ohana API-compatible, and has always been, I'm closing this. Any remaining discrepancies between the spec and Ohana would need to be resolved by the user when they write their script that produces CSV files, or by the Ohana API import script. Contributions in the form of scripts that transform data between the spec and what the Ohana API app expects are always welcome.

pmackay commented 9 years ago

OK. Do you think there is merit in having a spreadsheet template that matches OR? I could open an issue on OR about that. Its an odd one because its useful for importing into Ohana (and hence needs to match API), but also the OR spec defines the table structure, so a reference example would be useful matching that too....

monfresh commented 9 years ago

Yes, I think there is merit in having an OR template. It would be most helpful to those who are producing data from scratch by entering it in the spreadsheet, and who are not planning on importing it into Ohana. I'm not sure if we've come across this use case yet.