search

participedia / api

Website and API for Participedia V3
https://participedia.net
MIT License
20 stars 13 forks source link

Design and Implement Citations API #235

Open dethe opened 6 years ago

dethe commented 6 years ago

The goal of this API is to be able to generate citations for Participedia articles (whether cases, methods, etc.) that conform to various publication style requirements (i.e., APA, Chicago, MLA, etc.)

My hope is that there is an existing library for exporting data to these different styles, with a universal set of data requirements which can be mapped into any of the various styles, so I expect the first step is to find out if such a library does in fact exist, if there is a NodeJS library for it, and in the case that there are multiple such libraries, identifying the pros and cons so we can choose one.

The next step is, given a universal citation format, identifying what is missing from that in our current data model and how we propose to add or work around that.

Once we have identified a library and any data model requirements, then we can proceed with implementation.

Technical considerations:

  1. Solution must be usable from NodeJS
  2. Updates to our data model should be implemented as an SQL migration
  3. All work should be done in a PR to this repo
  4. PR should include tests
Jetroid commented 6 years ago

citation.js seems very promising and has an npm module. Natively outputs as human readable Harvard, APA, and Vancouver and also as the machine readable BibTeX, BibTXT, and CSL-JSON. It looks like you can add extra human readable style formats from here, but I don't see anyway to add all of the other machine readable formats that Robert listed here.

I was looking at the documentation for Zotero's formats and saw that they linked to bibutils, which is a set of commandline applications which, using XML as an intermediate format, could convert to a few additional machine readable formats. I found an example online of these tools interfacing with node, so it's a potentially viable approach.

Jetroid commented 6 years ago

I just noticed that bibutils is GPL, so perhaps something to be avoided.

dethe commented 6 years ago

We are fully open source, and while it doesn't look like we've actually chosen a license yet (we should do that!) I imagine we'll choose one that is either GPL or compatible with it, so I don't see the bibutils license as a problem.

dethe commented 6 years ago

Will citation.js or bibutils require any data which is not already in our schema?

Jetroid commented 6 years ago

Unless I'm overlooking something that I'll encounter later, I don't think so.

I took a look at citing on wikipedia, and there's really nothing there that the Participedia schema doesn't have. (Versioning, yes, but I think that's probably okay. They all have the time accessed anyway.)

As @scottofletcher brought up, author should probably be some text such as 'Partcipedia contributors' (Much like Wikipedia has just 'Wikipedia' or 'Wikipedia contributors' as the author).

...

The concern I have is slightly different. The common format between bibutils and citation.js is BibTeX, but BibTeX doesn't have a entry type for links. Instead, you must use the misc category - but as you can see from the citing on wikipedia link above, where there should be fields like Publisher or Access Date, you must instead hijack the title and note fields.

I had (perhaps naively) envisioned giving citation.js some data that it understands (Perhaps even BibTeX) use that to get apa, etc and also have it export a BibTeX for bibutils to use and covert to other formats. I'm afraid that the semantics would be lost for this method.

Here's a couple of examples of data generated by citation.js / bibutils compared to an 'ideal version'

RIS from Zotero vs RIS from bibutils converting BibTeX

Zotero:

TY  - ELEC
TI  - BibTeX - Wikipedia
UR  - https://en.wikipedia.org/wiki/BibTeX
Y2  - 2017/11/18/12:47:59
L2  - https://en.wikipedia.org/wiki/BibTeX
ER  -

And here's that same page, using bibutils's bib2xml | xml2ris on the BibTeX entry from the wikipedia Cite This Page:

TY  - STD
AU  - Wikipedia,
PY  - 2017//
TI  - BibTeX ?- Wikipedia, The Free Encyclopedia
UR  - https://en.wikipedia.org/w/index.php?title=BibTeX&oldid=801392872
N1  - [Online; accessed 18-November-2017]
ID  - wiki:xxx
ER  -

APA from Wikipedia vs APA from citation.js converting BibTex

Here's the APA citation from Wikipedia's Cite This Page

BibTeX. (2017, September 19). In Wikipedia, The Free Encyclopedia. Retrieved 13:06, November 18, 2017, from https://en.wikipedia.org/w/index.php?title=BibTeX&oldid=801392872

Here's the APA citation as exported by citation.js, using the BibTex entry from the wikipedia Cite This Page:

  Wikipedia. (2017). BibTeX — Wikipedia, The Free Encyclopedia. Retrieved from https://en.wikipedia.org/w/index.php?title=BibTeX&oldid=801392872

...

I think it's pretty clear that BibTeX is the wrong format to import from as it doesn't have enough meaning to convey the data. We always have the option of feeding citation.js and bibutils a different initial format, but BibTeX is the only common import format for the two tools.

Jetroid commented 6 years ago

Quick update:

Have completed the node wrapper for bibutils; also available on npm.