Publish to HDX proposal

Rationale

We are planning a "Publish to HDX" functionality from KoBo and HOT-OSM, and will be discussing with other partners as well (e.g. DHIS2). OSM will likely use the CKAN API, but for others, it would make sense to design a reusable framework where we can easily support publish buttons from any number of additional partners with little or no incremental effort on our part.

Proposal

The minimum viable product for a "Publish to HDX" link/button would be the ability to link to HDX's contribute form at https://data.humdata.org/contribute/new with parameters to prefill the form. For example, a button or HTML a element linking to

https://data.humdata.org/contribute/new?url=http%3A%2F%2Fexample.org%2Fapi%2F12345.csv

would open the HDX contribute form with http://example.org/api/12345.csv already filled in as the first resource URL. A more-complicated example could include many more parameters, such as the location, the org id, and the dataset title:

https://data.humdata.org/contribute/new?url=http%3A%2F%2Fexample.org%2Fapi%2F12345.csv&title=Sample%20dataset&org=unicef&location=SYR

We should accept submissions via GET or POST requests (with a redirect after the POST request, so that the user can safely refresh the form).


Client-side usage

On a Bootstrap3 site, the HTML markup for a publish button might look like this:

<a class="btn btn-success"

     href="https://data.humdata.org/contribute/new?url=http%3A%2F%2Fexample.org%2Fapi%2F12345.csv">Publish to HDX</a>

or alternately, as a POST form:

<form method="post" action="https://data.humdata.org/contribute/new">

    <input type="hidden" name="url" value="http://example.org/api/12345.csv"/>

    <input type="hidden" name="title" value="Sample dataset"/>

    <input type="hidden" name="org" value="foo_org"/>

    <input type="hidden" name="location" value="SYR"/>

    <button type="submit" class="btn btn-success">Publish to HDX</button>

</form>


We can publish samples that clients can easily copy and paste into their HTML templates. Since a contributor still needs to log in, any organisation could include this in their site, without even needing to contact us first.

Suggested HTTP parameters

The only required parameter will be url for the URL of the first resource, but a sophisticated client implementation could prefill many more fields.

ParameterRequired?Description
urlYesURL of first resource
nameNoDownload filename for first resource
mimetypeNoType of first resource
descriptionNoLong description of first resource
privateNoFlag for whether the dataset should be private (default: true)
titleNoTitle for dataset
slugNoProposed slug for dataset (if the slug already exists, and the user has authorisation, open the form to update an existing dataset instead).
notesNoLong description of dataset
subnationalNoFlag for subnational data (default: false)
dataset_sourceNoDescription of original source
orgNoHDX org id
maintainerNoHDX user id for maintainer
dateNoSingle date for dataset (excludes start_date and end_date)
start_dateNoStart date for dataset (excludes date)
end_dateNoEnd date for dataset (excludes date)
locationNoHDX location id (e.g. "SYR")
licenseNoHDX license id
methodologyNoHDX methodology id
update_frequencyNoHDX update-frequency id
caveatsNoText with caveats
tagsNoHDX tags, comma-separated

Possible future features

  • Allow a CKAN authorisation token to log the user in automatically.
  • Allow real-time validation feedback on the dataset.
  • Add options for creating instant previews.