Citation required aka Terms of Use

[sandyfreelance]

Came up today with ViRES discussion-- HAPI server ability to include what the mandatory citation language is (in return for having access to the data). Discussed earlier in the 'about/' field, but is there a way to make this more obvious, less optional? Goes beyond the optional /about and /info 'citation' field, and might incur more text (e.g. boilerplate to add to paper Acknowledgements, rules for redistribution of data, etc) (Ref #94 and #104)

[jvandegriff]

I think we should add two optional fields:

1. in the about/ endpoint: serverTermsOfUse
2. in the info for each dataset: datasetTermsOfUse

If a dataset also needs to refer to the server terms of use, it can do that using human language or inclusion of relative URL for the serverTermsOfUse

We might consider doing this too for the citation term, since I think we have the same thing at the server and dataset level (i.e., have serverCitation and datasetCitation). I'm not sure how consistent we've ben on separating things like this, so we need to check that.

[jvandegriff]

Ready to make and issue-131 branch and a pull request:

The plan is to deprecate citation in about and info responses, and replace with more specific keywords: serverCitation and datasetCitation

Also, each of these has substructure that allows for either the actual citation text or a URL to the citation, like this:

"serverCitation" : {
   "content": "Dr. Amazing, Awesome Labs, Wonderful, IA"
}

OR

"serverCitation" : {
   "contentURL": "http://awesomelabs.uiowa.edu/data/citation"
}

Then a similar approach for terms of use, as described above. (And there's no existing terms of use keyword that needs to be renamed.) So in the about endpoint and the info endpoints have a serverTermsOfUse and datasetTermsOfUse respectively.

[jbfaden]

I suggest we deprecate "citation" in the 3.x versions of HAPI, and then remove it in 4.0.

[sandyfreelance]

Clarified: get rid of 'citation' in "About" in favor of 'serverCitation', and add 'datasetCitation' in "Info".

As transition, validators would parse the legacy dual-use of 'citation' but by 4.0 we deprecate 'citation' fully.

Issue will be moved to 3.3

[sandyfreelance]

Change commit to https://github.com/hapi-server/data-specification/tree/131-citation-required-aka-terms-of-use (which also updates the version number in examples to "HAPI":"3.3")

[sandyfreelance]

Validators and possibly servers may need updating with this change (since the original 'citation' fields disappear).